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
  33  * API for structured and optimized calculation of positions.
  34  *
  35  * This header declares an API for calculating positions in an automated way,
  36  * for internal use by the selection engine.  This is useful in particular with
  37  * dynamic selections, because the same COM/COG positions may be needed in
  38  * several contexts.  The API makes it possible to optimize the evaluation such
  39  * that any heavy calculation is only done once, and the results just copied if
  40  * needed more than once.  The functions also provide a convenient interface
  41  * for keeping the whole \c gmx_ana_pos_t structure up-to-date.
  42  *
  43  * The API is documented in more detail in gmx::PositionCalculationCollection.
  44  *
  45  * \author Teemu Murtola <teemu.murtola@cbr.su.se>
  46  * \ingroup module_selection
  47  */
  48 #ifndef GMX_SELECTION_POSCALC_H
  49 #define GMX_SELECTION_POSCALC_H
  50
  51 #include "../legacyheaders/typedefs.h"
  52
  53 #include "../utility/common.h"
  54
  55 /*! \name Flags for position calculation.
  56  * \anchor poscalc_flags
  57  */
  58 /*@{*/
  59 /*! \brief
  60  * Use mass weighting.
  61  *
  62  * If this flag is set, the positions will be calculated using mass weighting,
  63  * i.e., one gets center-of-mass positions.
  64  * Without the flag, center-of-geometry positions are calculated.
  65  * Does not have any effect if the calculation type is \ref POS_ATOM.
  66  */
  67 #define POS_MASS        1
  68 /*! \brief
  69  * Calculate positions for the same atoms in residues/molecules.
  70  *
  71  * If this flag is set, the positions are always calculated using the same
  72  * atoms for each residue/molecule, even if the evaluation group contains only
  73  * some of the atoms for some frames.
  74  * The group passed to gmx_ana_poscalc_set_maxindex() is used to determine
  75  * the atoms to use for the calculation.
  76  *
  77  * Has no effect unless \ref POS_DYNAMIC is set or if the calculation type
  78  * is not \ref POS_RES of \ref POS_MOL.
  79  */
  80 #define POS_COMPLMAX    2
  81 /*! \brief
  82  * Calculate positions for whole residues/molecules.
  83  *
  84  * If this flag is set, the positions will be calculated for whole
  85  * residues/molecules, even if the group contains only some of the atoms in
  86  * the residue/molecule.
  87  *
  88  * Has no effect unless the calculation type is \ref POS_RES or \ref POS_MOL.
  89  */
  90 #define POS_COMPLWHOLE  4
  91 /*! \brief
  92  * Enable handling of changing calculation groups.
  93  *
  94  * Can be used for static calculations as well, but implies a small
  95  * performance penalty.
  96  */
  97 #define POS_DYNAMIC     16
  98 /*! \brief
  99  * Update \c gmx_ana_pos_t::m dynamically for an otherwise static
 100  * calculation.
 101  *
 102  * Has effect only if \ref POS_DYNAMIC is not set.
 103  */
 104 #define POS_MASKONLY    32
 105 /*! \brief
 106  * Calculate velocities of the positions.
 107  */
 108 #define POS_VELOCITIES  64
 109 /*! \brief
 110  * Calculate forces on the positions.
 111  */
 112 #define POS_FORCES      128
 113 /*@}*/
 114
 115 /** Specifies the type of positions to be calculated. */
 116 typedef enum
 117 {
 118     POS_ATOM,    /**< Copy atomic coordinates. */
 119     POS_RES,     /**< Calculate center for each residue. */
 120     POS_MOL,     /**< Calculate center for each molecule. */
 121     POS_ALL,     /**< Calculate center for the whole group. */
 122     POS_ALL_PBC  /**< Calculate center for the whole group with PBC. */
 123 } e_poscalc_t;
 124
 125 /** Data structure for position calculation. */
 126 typedef struct gmx_ana_poscalc_t gmx_ana_poscalc_t;
 127
 128 struct gmx_ana_index_t;
 129 struct gmx_ana_pos_t;
 130
 131 namespace gmx
 132 {
 133
 134 /*! \internal \brief
 135  * Collection of \c gmx_ana_poscalc_t structures for the same topology.
 136  *
 137  * Calculations within one collection share the same topology, and they are
 138  * optimized.  Calculations in different collections do not interact.
 139  * The topology for a collection can be set with setTopology().
 140  * This needs to be done before calling gmx_ana_poscalc_set_maxindex() for
 141  * any calculation in the collection, unless that calculation does not
 142  * require topology information.
 143  *
 144  * A new calculation is created with createCalculation().
 145  * If flags need to be adjusted later, gmx_ana_poscalc_set_flags() can be
 146  * used.
 147  * After the flags are final, the largest possible index group for which the
 148  * positions are needed has to be set with gmx_ana_poscalc_set_maxindex().
 149  * setTopology() should have been called before this function is called.
 150  * After the above calls, gmx_ana_poscalc_init_pos() can be used to initialize
 151  * output to a \c gmx_ana_pos_t structure.  Several different structures can be
 152  * initialized for the same calculation; the only requirement is that the
 153  * structure passed later to gmx_ana_poscalc_update() has been initialized
 154  * properly.
 155  * The memory allocated for a calculation can be freed with
 156  * gmx_ana_poscalc_free().
 157  *
 158  * The position evaluation is simple: initFrame() should be
 159  * called once for each frame, and gmx_ana_poscalc_update() can then be called
 160  * for each calculation that is needed for that frame.
 161  *
 162  * It is also possible to initialize the calculations based on a type provided
 163  * as a string.
 164  * The possible strings are listed in \ref typeEnumValues, and the string can
 165  * be converted to the parameters for createCalculation() using typeFromEnum().
 166  * createCalculationFromEnum() is also provided for convenience.
 167  *
 168  * \ingroup module_selection
 169  */
 170 class PositionCalculationCollection
 171 {
 172     public:
 173         /*! \brief
 174          * Array of strings acceptable for position calculation type enum.
 175          *
 176          * This array contains the acceptable values for typeFromEnum() and
 177          * createCalculationFromEnum().
 178          * The array contains a NULL pointer after the last item to indicate
 179          * the end of the list.
 180          */
 181         static const char * const typeEnumValues[];
 182
 183         /*! \brief
 184          * Converts a string to parameters for createCalculationFromEnum().
 185          *
 186          * \param[in]     post  String (typically an enum argument).
 187          *     Allowed values: 'atom', 'res_com', 'res_cog', 'mol_com', 'mol_cog',
 188          *     or one of the last four prepended by 'whole_', 'part_', or 'dyn_'.
 189          * \param[out]    type  \c e_poscalc_t corresponding to \p post.
 190          * \param[in,out] flags Flags corresponding to \p post.
 191          *     On input, the flags should contain the default flags.
 192          *     On exit, the flags \ref POS_MASS, \ref POS_COMPLMAX and
 193          *     \ref POS_COMPLWHOLE have been set according to \p post
 194          *     (the completion flags are left at the default values if no
 195          *     completion prefix is given).
 196          * \throws  InternalError  if post is not recognized.
 197          *
 198          * \attention
 199          * Checking is not complete, and other values than those listed above
 200          * may be accepted for \p post, but the results are undefined.
 201          *
 202          * \see typeEnumValues
 203          */
 204         static void typeFromEnum(const char *post, e_poscalc_t *type, int *flags);
 205
 206         /*! \brief
 207          * Creates a new position calculation collection object.
 208          *
 209          * \throws  std::bad_alloc if out of memory.
 210          */
 211         PositionCalculationCollection();
 212         /*! \brief
 213          * Destroys a position calculation collection and its calculations.
 214          *
 215          * Any calculations in the collection are also freed, even if
 216          * references to them are left.
 217          */
 218         ~PositionCalculationCollection();
 219
 220         /*! \brief
 221          * Sets the topology used for the calculations.
 222          *
 223          * \param[in]     top   Topology data structure.
 224          *
 225          * This function should be called to set the topology before using
 226          * gmx_ana_poscalc_set_maxindex() for any calculation that requires
 227          * topology information.
 228          *
 229          * Does not throw.
 230          */
 231         void setTopology(t_topology *top);
 232         /*! \brief
 233          * Prints information about calculations.
 234          *
 235          * \param[in] fp    File handle to receive the output.
 236          *
 237          * The output is very technical, making this function mainly useful for
 238          * debugging purposes.
 239          *
 240          * Does not throw.
 241          */
 242         void printTree(FILE *fp) const;
 243
 244         /*! \brief
 245          * Creates a new position calculation.
 246          *
 247          * \param[in]  type  Type of calculation.
 248          * \param[in]  flags Flags for setting calculation options
 249          *   (see \ref poscalc_flags "documentation of the flags").
 250          *
 251          * Does not throw currently, but may throw std::bad_alloc in the
 252          * future.
 253          */
 254         gmx_ana_poscalc_t *createCalculation(e_poscalc_t type, int flags);
 255         /*! \brief
 256          * Creates a new position calculation based on an enum value.
 257          *
 258          * \param[in]  post  One of the strings acceptable for
 259          *      typeFromEnum().
 260          * \param[in]  flags Flags for setting calculation options
 261          *      (see \ref poscalc_flags "documentation of the flags").
 262          * \throws     InternalError  if post is not recognized.
 263          *
 264          * This is a convenience wrapper for createCalculation().
 265          * \p flags sets the default calculation options if not overridden by
 266          * \p post; see typeFromEnum().
 267          *
 268          * May also throw std::bad_alloc in the future.
 269          *
 270          * \see createCalculation(), typeFromEnum()
 271          */
 272         gmx_ana_poscalc_t *createCalculationFromEnum(const char *post, int flags);
 273
 274         /*! \brief
 275          * Initializes evaluation for a position calculation collection.
 276          *
 277          * This function does some final initialization of the data structures
 278          * in the collection to prepare them for evaluation.
 279          * After this function has been called, it is no longer possible to add
 280          * new calculations to the collection.
 281          *
 282          * Multiple calls to the function are ignored.
 283          *
 284          * Does not throw currently, but may throw std::bad_alloc in the
 285          * future.
 286          */
 287         void initEvaluation();
 288         /*! \brief
 289          * Initializes a position calculation collection for a new frame.
 290          *
 291          * Clears the evaluation flag for all calculations.
 292          * Should be called for each frame before calling
 293          * gmx_ana_poscalc_update().
 294          *
 295          * This function calls initEvaluation() automatically if it has not
 296          * been called earlier.
 297          *
 298          * Does not throw, but may throw if initEvaluation() is changed to
 299          * throw.
 300          */
 301         void initFrame();
 302
 303     private:
 304         class Impl;
 305
 306         PrivateImplPointer<Impl> impl_;
 307
 308         /*! \brief
 309          * Needed to access the implementation class from the C code.
 310          */
 311         friend struct ::gmx_ana_poscalc_t;
 312 };
 313
 314 } // namespace gmx
 315
 316 /** Sets the flags for position calculation. */
 317 void
 318 gmx_ana_poscalc_set_flags(gmx_ana_poscalc_t *pc, int flags);
 319 /** Sets the maximum possible input index group for position calculation. */
 320 void
 321 gmx_ana_poscalc_set_maxindex(gmx_ana_poscalc_t *pc, struct gmx_ana_index_t *g);
 322 /** Initializes positions for position calculation output. */
 323 void
 324 gmx_ana_poscalc_init_pos(gmx_ana_poscalc_t *pc, struct gmx_ana_pos_t *p);
 325 /** Frees the memory allocated for position calculation. */
 326 void
 327 gmx_ana_poscalc_free(gmx_ana_poscalc_t *pc);
 328 /** Returns true if the position calculation requires topology information. */
 329 bool
 330 gmx_ana_poscalc_requires_top(gmx_ana_poscalc_t *pc);
 331
 332 /** Updates a single COM/COG structure for a frame. */
 333 void
 334 gmx_ana_poscalc_update(gmx_ana_poscalc_t *pc,
 335                        struct gmx_ana_pos_t *p, struct gmx_ana_index_t *g,
 336                        t_trxframe *fr, t_pbc *pbc);
 337
 338 #endif