include/poscalc.h

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