src/gromacs/selection/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 /*! \internal \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  * The API is documented in more detail on a separate page:
  41  * \ref poscalcengine.
  42  *
  43  * \author Teemu Murtola <teemu.murtola@cbr.su.se>
  44  * \ingroup module_selection
  45  */
  46 #ifndef GMX_SELECTION_POSCALC_H
  47 #define GMX_SELECTION_POSCALC_H
  48
  49 #include "../legacyheaders/typedefs.h"
  50
  51 /*! \name Flags for position calculation.
  52  * \anchor poscalc_flags
  53  */
  54 /*@{*/
  55 /*! \brief
  56  * Use mass weighting.
  57  *
  58  * If this flag is set, the positions will be calculated using mass weighting,
  59  * i.e., one gets center-of-mass positions.
  60  * Without the flag, center-of-geometry positions are calculated.
  61  * Does not have any effect if the calculation type is \ref POS_ATOM.
  62  */
  63 #define POS_MASS        1
  64 /*! \brief
  65  * Calculate positions for the same atoms in residues/molecules.
  66  *
  67  * If this flag is set, the positions are always calculated using the same
  68  * atoms for each residue/molecule, even if the evaluation group contains only
  69  * some of the atoms for some frames.
  70  * The group passed to gmx_ana_poscalc_set_maxindex() is used to determine
  71  * the atoms to use for the calculation.
  72  *
  73  * Has no effect unless \ref POS_DYNAMIC is set or if the calculation type
  74  * is not \ref POS_RES of \ref POS_MOL.
  75  */
  76 #define POS_COMPLMAX    2
  77 /*! \brief
  78  * Calculate positions for whole residues/molecules.
  79  *
  80  * If this flag is set, the positions will be calculated for whole
  81  * residues/molecules, even if the group contains only some of the atoms in
  82  * the residue/molecule.
  83  *
  84  * Has no effect unless the calculation type is \ref POS_RES or \ref POS_MOL.
  85  */
  86 #define POS_COMPLWHOLE  4
  87 /*! \brief
  88  * Enable handling of changing calculation groups.
  89  *
  90  * Can be used for static calculations as well, but implies a small
  91  * performance penalty.
  92  */
  93 #define POS_DYNAMIC     16
  94 /*! \brief
  95  * Update \c gmx_ana_pos_t::m dynamically for an otherwise static
  96  * calculation.
  97  *
  98  * Has effect only if \ref POS_DYNAMIC is not set.
  99  */
 100 #define POS_MASKONLY    32
 101 /*! \brief
 102  * Calculate velocities of the positions.
 103  */
 104 #define POS_VELOCITIES  64
 105 /*! \brief
 106  * Calculate forces on the positions.
 107  */
 108 #define POS_FORCES      128
 109 /*@}*/
 110
 111 /** Specifies the type of positions to be calculated. */
 112 typedef enum
 113 {
 114     POS_ATOM,    /**< Copy atomic coordinates. */
 115     POS_RES,     /**< Calculate center for each residue. */
 116     POS_MOL,     /**< Calculate center for each molecule. */
 117     POS_ALL,     /**< Calculate center for the whole group. */
 118     POS_ALL_PBC  /**< Calculate center for the whole group with PBC. */
 119 } e_poscalc_t;
 120
 121 /** Collection of \c gmx_ana_poscalc_t structures for the same topology. */
 122 typedef struct gmx_ana_poscalc_coll_t gmx_ana_poscalc_coll_t;
 123 /** Data structure for position calculation. */
 124 typedef struct gmx_ana_poscalc_t gmx_ana_poscalc_t;
 125
 126 struct gmx_ana_index_t;
 127 struct gmx_ana_pos_t;
 128
 129 /** Converts a string to parameters for gmx_ana_poscalc_create(). */
 130 void
 131 gmx_ana_poscalc_type_from_enum(const char *post, e_poscalc_t *type, int *flags);
 132 /** Creates a list of strings for position enum parameter handling. */
 133 const char **
 134 gmx_ana_poscalc_create_type_enum(bool bAtom);
 135
 136 /** Creates a new position calculation collection object. */
 137 int
 138 gmx_ana_poscalc_coll_create(gmx_ana_poscalc_coll_t **pccp);
 139 /** Sets the topology for a position calculation collection. */
 140 void
 141 gmx_ana_poscalc_coll_set_topology(gmx_ana_poscalc_coll_t *pcc, t_topology *top);
 142 /** Frees memory allocated for a position calculation collection. */
 143 void
 144 gmx_ana_poscalc_coll_free(gmx_ana_poscalc_coll_t *pcc);
 145 /** Prints information about calculations in a position calculation collection. */
 146 void
 147 gmx_ana_poscalc_coll_print_tree(FILE *fp, gmx_ana_poscalc_coll_t *pcc);
 148
 149 /** Creates a new position calculation. */
 150 void
 151 gmx_ana_poscalc_create(gmx_ana_poscalc_t **pcp, gmx_ana_poscalc_coll_t *pcc,
 152                        e_poscalc_t type, int flags);
 153 /** Creates a new position calculation based on an enum value. */
 154 void
 155 gmx_ana_poscalc_create_enum(gmx_ana_poscalc_t **pcp, gmx_ana_poscalc_coll_t *pcc,
 156                             const char *post, int flags);
 157 /** Sets the flags for position calculation. */
 158 void
 159 gmx_ana_poscalc_set_flags(gmx_ana_poscalc_t *pc, int flags);
 160 /** Sets the maximum possible input index group for position calculation. */
 161 void
 162 gmx_ana_poscalc_set_maxindex(gmx_ana_poscalc_t *pc, struct gmx_ana_index_t *g);
 163 /** Initializes positions for position calculation output. */
 164 void
 165 gmx_ana_poscalc_init_pos(gmx_ana_poscalc_t *pc, struct gmx_ana_pos_t *p);
 166 /** Frees the memory allocated for position calculation. */
 167 void
 168 gmx_ana_poscalc_free(gmx_ana_poscalc_t *pc);
 169 /** Returns true if the position calculation requires topology information. */
 170 bool
 171 gmx_ana_poscalc_requires_top(gmx_ana_poscalc_t *pc);
 172
 173 /** Initializes evaluation for a position calculation collection. */
 174 void
 175 gmx_ana_poscalc_init_eval(gmx_ana_poscalc_coll_t *pcc);
 176 /** Initializes a position calculation collection for a new frame. */
 177 void
 178 gmx_ana_poscalc_init_frame(gmx_ana_poscalc_coll_t *pcc);
 179 /** Updates a single COM/COG structure for a frame. */
 180 void
 181 gmx_ana_poscalc_update(gmx_ana_poscalc_t *pc,
 182                        struct gmx_ana_pos_t *p, struct gmx_ana_index_t *g,
 183                        t_trxframe *fr, t_pbc *pbc);
 184
 185 #endif