3 * This source code is part of
7 * GROningen MAchine for Chemical Simulations
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.
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.
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.
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.
29 * For more info, check our website at http://www.gromacs.org
32 * \brief API for structured and optimized calculation of positions.
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.
40 * The API is documented in more detail on a separate page:
43 * \author Teemu Murtola <teemu.murtola@cbr.su.se>
44 * \ingroup module_selection
46 #ifndef GMX_SELECTION_POSCALC_H
47 #define GMX_SELECTION_POSCALC_H
49 #include "../legacyheaders/typedefs.h"
51 /*! \name Flags for position calculation.
52 * \anchor poscalc_flags
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.
65 * Calculate positions for the same atoms in residues/molecules.
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.
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.
76 #define POS_COMPLMAX 2
78 * Calculate positions for whole residues/molecules.
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.
84 * Has no effect unless the calculation type is \ref POS_RES or \ref POS_MOL.
86 #define POS_COMPLWHOLE 4
88 * Enable handling of changing calculation groups.
90 * Can be used for static calculations as well, but implies a small
91 * performance penalty.
93 #define POS_DYNAMIC 16
95 * Update \c gmx_ana_pos_t::m dynamically for an otherwise static
98 * Has effect only if \ref POS_DYNAMIC is not set.
100 #define POS_MASKONLY 32
102 * Calculate velocities of the positions.
104 #define POS_VELOCITIES 64
106 * Calculate forces on the positions.
108 #define POS_FORCES 128
111 /** Specifies the type of positions to be calculated. */
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. */
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;
126 struct gmx_ana_index_t;
127 struct gmx_ana_pos_t;
129 /** Converts a string to parameters for gmx_ana_poscalc_create(). */
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. */
134 gmx_ana_poscalc_create_type_enum(bool bAtom);
136 /** Creates a new position calculation collection object. */
138 gmx_ana_poscalc_coll_create(gmx_ana_poscalc_coll_t **pccp);
139 /** Sets the topology for a position calculation collection. */
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. */
144 gmx_ana_poscalc_coll_free(gmx_ana_poscalc_coll_t *pcc);
145 /** Prints information about calculations in a position calculation collection. */
147 gmx_ana_poscalc_coll_print_tree(FILE *fp, gmx_ana_poscalc_coll_t *pcc);
149 /** Creates a new position calculation. */
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. */
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. */
159 gmx_ana_poscalc_set_flags(gmx_ana_poscalc_t *pc, int flags);
160 /** Sets the maximum possible input index group for position calculation. */
162 gmx_ana_poscalc_set_maxindex(gmx_ana_poscalc_t *pc, struct gmx_ana_index_t *g);
163 /** Initializes positions for position calculation output. */
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. */
168 gmx_ana_poscalc_free(gmx_ana_poscalc_t *pc);
169 /** Returns true if the position calculation requires topology information. */
171 gmx_ana_poscalc_requires_top(gmx_ana_poscalc_t *pc);
173 /** Initializes evaluation for a position calculation collection. */
175 gmx_ana_poscalc_init_eval(gmx_ana_poscalc_coll_t *pcc);
176 /** Initializes a position calculation collection for a new frame. */
178 gmx_ana_poscalc_init_frame(gmx_ana_poscalc_coll_t *pcc);
179 /** Updates a single COM/COG structure for a frame. */
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);