Merge branch 'master' of git://git.gromacs.org/gromacs
[gromacs/adressmacs.git] / include / poscalc.h
blobaaac1836df6b564a05699f1608aa738bd4c58091
1 /*
3 * This source code is part of
5 * G R O M A C S
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
31 /*! \file
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 * \internal
42 * The API is documented in more detail on a separate page:
43 * \ref poscalcengine.
45 #ifndef POSCALC_H
46 #define POSCALC_H
48 #include "typedefs.h"
50 #ifdef __cplusplus
51 extern "C" {
52 #endif
54 /*! \name Flags for position calculation.
55 * \anchor poscalc_flags
57 /*@{*/
58 /*! \brief
59 * Use mass weighting.
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.
66 #define POS_MASS 1
67 /*! \brief
68 * Calculate positions for the same atoms in residues/molecules.
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.
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.
79 #define POS_COMPLMAX 2
80 /*! \brief
81 * Calculate positions for whole residues/molecules.
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.
87 * Has no effect unless the calculation type is \ref POS_RES or \ref POS_MOL.
89 #define POS_COMPLWHOLE 4
90 /*! \brief
91 * Enable handling of changing calculation groups.
93 * Can be used for static calculations as well, but implies a small
94 * performance penalty.
96 #define POS_DYNAMIC 16
97 /*! \brief
98 * Update \c gmx_ana_pos_t::m dynamically for an otherwise static
99 * calculation.
101 * Has effect only if \ref POS_DYNAMIC is not set.
103 #define POS_MASKONLY 32
104 /*! \brief
105 * Calculate velocities of the positions.
107 #define POS_VELOCITIES 64
108 /*! \brief
109 * Calculate forces on the positions.
111 #define POS_FORCES 128
112 /*@}*/
114 /** Specifies the type of positions to be calculated. */
115 typedef enum
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;
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;
129 struct gmx_ana_index_t;
130 struct gmx_ana_pos_t;
132 /** Converts a string to parameters for gmx_ana_poscalc_create(). */
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 const char **
137 gmx_ana_poscalc_create_type_enum(gmx_bool bAtom);
139 /** Creates a new position calculation collection object. */
141 gmx_ana_poscalc_coll_create(gmx_ana_poscalc_coll_t **pccp);
142 /** Sets the topology for a position calculation collection. */
143 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 void
147 gmx_ana_poscalc_coll_free(gmx_ana_poscalc_coll_t *pcc);
148 /** Prints information about calculations in a position calculation collection. */
149 void
150 gmx_ana_poscalc_coll_print_tree(FILE *fp, gmx_ana_poscalc_coll_t *pcc);
152 /** Creates a new position calculation. */
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. */
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 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 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 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 void
171 gmx_ana_poscalc_free(gmx_ana_poscalc_t *pc);
172 /** Returns TRUE if the position calculation requires topology information. */
173 gmx_bool
174 gmx_ana_poscalc_requires_top(gmx_ana_poscalc_t *pc);
176 /** Initializes evaluation for a position calculation collection. */
177 void
178 gmx_ana_poscalc_init_eval(gmx_ana_poscalc_coll_t *pcc);
179 /** Initializes a position calculation collection for a new frame. */
180 void
181 gmx_ana_poscalc_init_frame(gmx_ana_poscalc_coll_t *pcc);
182 /** Updates a single COM/COG structure for a frame. */
183 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);
188 #ifdef __cplusplus
190 #endif
192 #endif