include/poscalc.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
   5  * Copyright (c) 2001-2009, The GROMACS development team,
   6  * check out http://www.gromacs.org for more information.
   7  * Copyright (c) 2012,2013, by the GROMACS development team, led by
   8  * David van der Spoel, Berk Hess, Erik Lindahl, and including many
   9  * others, as listed in the AUTHORS file in the top-level source
  10  * directory and at http://www.gromacs.org.
  11  *
  12  * GROMACS is free software; you can redistribute it and/or
  13  * modify it under the terms of the GNU Lesser General Public License
  14  * as published by the Free Software Foundation; either version 2.1
  15  * of the License, or (at your option) any later version.
  16  *
  17  * GROMACS is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  20  * Lesser General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU Lesser General Public
  23  * License along with GROMACS; if not, see
  24  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  25  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  26  *
  27  * If you want to redistribute modifications to GROMACS, please
  28  * consider that scientific software is very special. Version
  29  * control is crucial - bugs must be traceable. We will be happy to
  30  * consider code for inclusion in the official distribution, but
  31  * derived work must not be called official GROMACS. Details are found
  32  * in the README & COPYING files - if they are missing, get the
  33  * official version at http://www.gromacs.org.
  34  *
  35  * To help us fund GROMACS development, we humbly ask that you cite
  36  * the research papers on the package. Check out http://www.gromacs.org.
  37  */
  38 /*! \file
  39  * \brief API for structured and optimized calculation of positions.
  40  *
  41  * The functions in this header are used internally by the analysis library
  42  * to calculate positions.
  43  * They can also be used in user code, but in most cases there should be no
  44  * need. Instead, one should write an analysis tool such that it gets all
  45  * positions through selections.
  46  *
  47  * \internal
  48  *
  49  * The API is documented in more detail on a separate page:
  50  * \ref poscalcengine.
  51  */
  52 #ifndef POSCALC_H
  53 #define POSCALC_H
  54
  55 #include "typedefs.h"
  56
  57 #ifdef __cplusplus
  58 extern "C" {
  59 #endif
  60
  61 /*! \name Flags for position calculation.
  62  * \anchor poscalc_flags
  63  */
  64 /*@{*/
  65 /*! \brief
  66  * Use mass weighting.
  67  *
  68  * If this flag is set, the positions will be calculated using mass weighting,
  69  * i.e., one gets center-of-mass positions.
  70  * Without the flag, center-of-geometry positions are calculated.
  71  * Does not have any effect if the calculation type is \ref POS_ATOM.
  72  */
  73 #define POS_MASS        1
  74 /*! \brief
  75  * Calculate positions for the same atoms in residues/molecules.
  76  *
  77  * If this flag is set, the positions are always calculated using the same
  78  * atoms for each residue/molecule, even if the evaluation group contains only
  79  * some of the atoms for some frames.
  80  * The group passed to gmx_ana_poscalc_set_maxindex() is used to determine
  81  * the atoms to use for the calculation.
  82  *
  83  * Has no effect unless \ref POS_DYNAMIC is set or if the calculation type
  84  * is not \ref POS_RES of \ref POS_MOL.
  85  */
  86 #define POS_COMPLMAX    2
  87 /*! \brief
  88  * Calculate positions for whole residues/molecules.
  89  *
  90  * If this flag is set, the positions will be calculated for whole
  91  * residues/molecules, even if the group contains only some of the atoms in
  92  * the residue/molecule.
  93  *
  94  * Has no effect unless the calculation type is \ref POS_RES or \ref POS_MOL.
  95  */
  96 #define POS_COMPLWHOLE  4
  97 /*! \brief
  98  * Enable handling of changing calculation groups.
  99  *
 100  * Can be used for static calculations as well, but implies a small
 101  * performance penalty.
 102  */
 103 #define POS_DYNAMIC     16
 104 /*! \brief
 105  * Update \c gmx_ana_pos_t::m dynamically for an otherwise static
 106  * calculation.
 107  *
 108  * Has effect only if \ref POS_DYNAMIC is not set.
 109  */
 110 #define POS_MASKONLY    32
 111 /*! \brief
 112  * Calculate velocities of the positions.
 113  */
 114 #define POS_VELOCITIES  64
 115 /*! \brief
 116  * Calculate forces on the positions.
 117  */
 118 #define POS_FORCES      128
 119 /*@}*/
 120
 121 /** Specifies the type of positions to be calculated. */
 122 typedef enum
 123 {
 124     POS_ATOM,    /**< Copy atomic coordinates. */
 125     POS_RES,     /**< Calculate center for each residue. */
 126     POS_MOL,     /**< Calculate center for each molecule. */
 127     POS_ALL,     /**< Calculate center for the whole group. */
 128     POS_ALL_PBC  /**< Calculate center for the whole group with PBC. */
 129 } e_poscalc_t;
 130
 131 /** Collection of \c gmx_ana_poscalc_t structures for the same topology. */
 132 typedef struct gmx_ana_poscalc_coll_t gmx_ana_poscalc_coll_t;
 133 /** Data structure for position calculation. */
 134 typedef struct gmx_ana_poscalc_t gmx_ana_poscalc_t;
 135
 136 struct gmx_ana_index_t;
 137 struct gmx_ana_pos_t;
 138
 139 /** Converts a string to parameters for gmx_ana_poscalc_create(). */
 140 int
 141 gmx_ana_poscalc_type_from_enum(const char *post, e_poscalc_t *type, int *flags);
 142 /** Creates a list of strings for position enum parameter handling. */
 143 const char **
 144 gmx_ana_poscalc_create_type_enum(gmx_bool bAtom);
 145
 146 /** Creates a new position calculation collection object. */
 147 int
 148 gmx_ana_poscalc_coll_create(gmx_ana_poscalc_coll_t **pccp);
 149 /** Sets the topology for a position calculation collection. */
 150 void
 151 gmx_ana_poscalc_coll_set_topology(gmx_ana_poscalc_coll_t *pcc, t_topology *top);
 152 /** Frees memory allocated for a position calculation collection. */
 153 void
 154 gmx_ana_poscalc_coll_free(gmx_ana_poscalc_coll_t *pcc);
 155 /** Prints information about calculations in a position calculation collection. */
 156 void
 157 gmx_ana_poscalc_coll_print_tree(FILE *fp, gmx_ana_poscalc_coll_t *pcc);
 158
 159 /** Creates a new position calculation. */
 160 int
 161 gmx_ana_poscalc_create(gmx_ana_poscalc_t **pcp, gmx_ana_poscalc_coll_t *pcc,
 162                        e_poscalc_t type, int flags);
 163 /** Creates a new position calculation based on an enum value. */
 164 int
 165 gmx_ana_poscalc_create_enum(gmx_ana_poscalc_t **pcp, gmx_ana_poscalc_coll_t *pcc,
 166                             const char *post, int flags);
 167 /** Sets the flags for position calculation. */
 168 void
 169 gmx_ana_poscalc_set_flags(gmx_ana_poscalc_t *pc, int flags);
 170 /** Sets the maximum possible input index group for position calculation. */
 171 void
 172 gmx_ana_poscalc_set_maxindex(gmx_ana_poscalc_t *pc, struct gmx_ana_index_t *g);
 173 /** Initializes positions for position calculation output. */
 174 void
 175 gmx_ana_poscalc_init_pos(gmx_ana_poscalc_t *pc, struct gmx_ana_pos_t *p);
 176 /** Frees the memory allocated for position calculation. */
 177 void
 178 gmx_ana_poscalc_free(gmx_ana_poscalc_t *pc);
 179 /** Returns TRUE if the position calculation requires topology information. */
 180 gmx_bool
 181 gmx_ana_poscalc_requires_top(gmx_ana_poscalc_t *pc);
 182
 183 /** Initializes evaluation for a position calculation collection. */
 184 void
 185 gmx_ana_poscalc_init_eval(gmx_ana_poscalc_coll_t *pcc);
 186 /** Initializes a position calculation collection for a new frame. */
 187 void
 188 gmx_ana_poscalc_init_frame(gmx_ana_poscalc_coll_t *pcc);
 189 /** Updates a single COM/COG structure for a frame. */
 190 void
 191 gmx_ana_poscalc_update(gmx_ana_poscalc_t *pc,
 192                        struct gmx_ana_pos_t *p, struct gmx_ana_index_t *g,
 193                        t_trxframe *fr, t_pbc *pbc);
 194
 195 #ifdef __cplusplus
 196 }
 197 #endif
 198
 199 #endif