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 /*@}*/
 105
 106 /** Specifies the type of positions to be calculated. */
 107 typedef enum
 108 {
 109     POS_ATOM,    /**< Copy atomic coordinates. */
 110     POS_RES,     /**< Calculate center for each residue. */
 111     POS_MOL,     /**< Calculate center for each molecule. */
 112     POS_ALL,     /**< Calculate center for the whole group. */
 113     POS_ALL_PBC, /**< Calculate center for the whole group with PBC. */
 114 } e_poscalc_t;
 115
 116 /** Collection of \c gmx_ana_poscalc_t structures for the same topology. */
 117 typedef struct gmx_ana_poscalc_coll_t gmx_ana_poscalc_coll_t;
 118 /** Data structure for position calculation. */
 119 typedef struct gmx_ana_poscalc_t gmx_ana_poscalc_t;
 120
 121 struct gmx_ana_index_t;
 122 struct gmx_ana_pos_t;
 123
 124 /** Converts a string to parameters for gmx_ana_poscalc_create(). */
 125 extern int
 126 gmx_ana_poscalc_type_from_enum(const char *post, e_poscalc_t *type, int *flags);
 127 /** Creates a list of strings for position enum parameter handling. */
 128 extern const char **
 129 gmx_ana_poscalc_create_type_enum(bool bAtom);
 130
 131 /** Creates a new position calculation collection object. */
 132 extern int
 133 gmx_ana_poscalc_coll_create(gmx_ana_poscalc_coll_t **pccp);
 134 /** Sets the topology for a position calculation collection. */
 135 extern void
 136 gmx_ana_poscalc_coll_set_topology(gmx_ana_poscalc_coll_t *pcc, t_topology *top);
 137 /** Frees memory allocated for a position calculation collection. */
 138 extern void
 139 gmx_ana_poscalc_coll_free(gmx_ana_poscalc_coll_t *pcc);
 140 /** Prints information about calculations in a position calculation collection. */
 141 extern void
 142 gmx_ana_poscalc_coll_print_tree(FILE *fp, gmx_ana_poscalc_coll_t *pcc);
 143
 144 /** Creates a new position calculation. */
 145 extern int
 146 gmx_ana_poscalc_create(gmx_ana_poscalc_t **pcp, gmx_ana_poscalc_coll_t *pcc,
 147                        e_poscalc_t type, int flags);
 148 /** Creates a new position calculation based on an enum value. */
 149 extern int
 150 gmx_ana_poscalc_create_enum(gmx_ana_poscalc_t **pcp, gmx_ana_poscalc_coll_t *pcc,
 151                             const char *post, int flags);
 152 /** Sets the flags for position calculation. */
 153 extern void
 154 gmx_ana_poscalc_set_flags(gmx_ana_poscalc_t *pc, int flags);
 155 /** Sets the maximum possible input index group for position calculation. */
 156 extern void
 157 gmx_ana_poscalc_set_maxindex(gmx_ana_poscalc_t *pc, struct gmx_ana_index_t *g);
 158 /** Initializes positions for position calculation output. */
 159 extern void
 160 gmx_ana_poscalc_init_pos(gmx_ana_poscalc_t *pc, struct gmx_ana_pos_t *p);
 161 /** Frees the memory allocated for position calculation. */
 162 extern void
 163 gmx_ana_poscalc_free(gmx_ana_poscalc_t *pc);
 164 /** Returns TRUE if the position calculation requires topology information. */
 165 extern bool
 166 gmx_ana_poscalc_requires_top(gmx_ana_poscalc_t *pc);
 167
 168 /** Initializes evaluation for a position calculation collection. */
 169 extern void
 170 gmx_ana_poscalc_init_eval(gmx_ana_poscalc_coll_t *pcc);
 171 /** Initializes a position calculation collection for a new frame. */
 172 extern void
 173 gmx_ana_poscalc_init_frame(gmx_ana_poscalc_coll_t *pcc);
 174 /** Updates a single COM/COG structure for a frame. */
 175 extern void
 176 gmx_ana_poscalc_update(gmx_ana_poscalc_t *pc,
 177                        struct gmx_ana_pos_t *p, struct gmx_ana_index_t *g,
 178                        rvec x[], t_pbc *pbc);
 179
 180 #ifdef __cplusplus
 181 }
 182 #endif
 183
 184 #endif