include/trajana.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 Main API of the trajectory analysis library.
  33  *
  34  * Contains the API for the core analysis library.
  35  *
  36  * \todo
  37  * Better handling of reference groups.
  38  * It would be nice to be able to provide a string that would be used in
  39  * prompting the groups, and also in automatic reporting of what the tool
  40  * is about to do.
  41  *
  42  * Most analysis tools should include trajana.h
  43  * (which automatically includes indexutil.h, selection.h, position.h)
  44  * and possibly one or more of the following headers:
  45  * displacement.h, histogram.h, nbsearch.h.
  46  * If the tool implements custom selection methods, it should also include
  47  * selmethod.h (which automatically includes selparam.h and selvalue.h).
  48  *
  49  * Other headers (centerofmass.h, poscalc.h) are used internally by the
  50  * library to calculate positions.
  51  * Analysis tools should preferably not use the routines in these headers
  52  * directly, but instead get all positions through selections. This makes
  53  * them more flexible with a minimal amount of work.
  54  */
  55 #ifndef TRAJANA_H
  56 #define TRAJANA_H
  57
  58 #include <typedefs.h>
  59 #include <filenm.h>
  60 #include <readinp.h>
  61
  62 #include <indexutil.h>
  63 #include <selection.h>
  64
  65 #ifdef __cplusplus
  66 extern "C" {
  67 #endif
  68
  69 /** Data structure for trajectory analysis tools. */
  70 typedef struct gmx_ana_traj_t gmx_ana_traj_t;
  71
  72 /*! \name Flags for gmx_ana_traj_create()
  73  * \anchor analysis_flags
  74  * These flags can be used to alter the behavior of the analysis library to
  75  * suit the analysis tool.
  76  * They are given to the gmx_ana_traj_create() when creating the
  77  * \c gmx_ana_traj_t data structure, and affect the behavior of the other
  78  * functions in this header.
  79  */
  80 /*@{*/
  81 /*! \brief
  82  * Force loading of a topology file.
  83  *
  84  * If this flag is not specified, the topology file is loaded only if it is
  85  * provided on the command line explicitly.
  86  *
  87  * \see gmx_ana_get_topology()
  88  */
  89 #define ANA_REQUIRE_TOP      (1<<0)
  90 /*! \brief
  91  * Do no free the coordinates loaded from the topology.
  92  *
  93  * If this flag is specified, the coordinates loaded from the topology can
  94  * be accessed with gmx_ana_get_topconf().
  95  *
  96  * \see gmx_ana_get_topconf()
  97  */
  98 #define ANA_USE_TOPX         (1<<1)
  99 /*! \brief
 100  * Disallows the user from changing PBC handling.
 101  *
 102  * If this option is not specified, the analysis program (see gmx_analysisfunc())
 103  * may be passed a NULL PBC structure, and it should be able to handle such a
 104  * situation.
 105  */
 106 #define ANA_NOUSER_PBC       (1<<4)
 107 /*! \brief
 108  * Disallows the user from changing PBC removal.
 109  */
 110 #define ANA_NOUSER_RMPBC     (1<<5)
 111 /*! \brief
 112  * Disallows dynamic selections.
 113  *
 114  * If this flag is specified, an error is reported if the user specifies
 115  * any dynamic selections.
 116  */
 117 #define ANA_NO_DYNSEL        (1<<8)
 118 /*! \brief
 119  * Disallows breaking of residues in dynamic selections.
 120  *
 121  * Makes it impossible for the user to select atom-based dynamic selections.
 122  *
 123  * Only has effect if \ref ANA_NO_DYNSEL is not specified.
 124  */
 125 #define ANA_REQUIRE_WHOLE    (1<<9)
 126 /*! \brief
 127  * Disables automatic initialization of selection groups.
 128  *
 129  * If this flag is specified, parse_trjana_args() does not call
 130  * gmx_ana_init_selections(), allowing the program to do some initialization
 131  * before the call.
 132  * In particular, the program can use gmx_ana_set_nrefgprs() and
 133  * gmx_ana_set_nanagrps() before calling gmx_ana_init_selections() to
 134  * control the number of selections to expect.
 135  * This is useful if the program requires a different number of index groups
 136  * with different command-line arguments.
 137  * If the flag is specified, the program should call gmx_ana_init_selections()
 138  * exactly once after the parse_trjana_args() call.
 139  */
 140 #define ANA_USER_SELINIT     (1<<10)
 141 /*! \brief
 142  * Allow only atomic positions to be selected.
 143  *
 144  * Note that this flag only applies to the analysis groups, not the reference
 145  * groups. The reference groups should be checked in the analysis program
 146  * if some limitations are imposed on them.
 147  */
 148 #define ANA_ONLY_ATOMPOS     (1<<11)
 149 /*! \brief
 150  * Use masks in the positions to convey dynamic information.
 151  *
 152  * If this flag is specified, the positions calculated for the selections
 153  * are calculated always for the same group of atoms, even if the selection is
 154  * dynamic.
 155  * Dynamic selections only affect the \p refid field of the indexgroup map
 156  * given in the positions.
 157  */
 158 #define ANA_USE_POSMASK      (1<<12)
 159 /*! \brief
 160  * Pass the reference groups to gmx_analysisfunc().
 161  *
 162  * If this flag is specified, the reference groups are passed on to
 163  * gmx_analysisfunc().
 164  * Similarly, the arrays returned by gmx_ana_get_anagrps() and
 165  * gmx_ana_get_grpnames() contain the reference groups in the beginning.
 166  */
 167 #define ANA_USE_FULLGRPS     (1<<13)
 168 /*! \brief
 169  * Dump the parsed and compiled selection trees.
 170  *
 171  * This flag is used by internal debugging tools to make
 172  * gmx_ana_init_selections() dump the selection trees to stderr.
 173  */
 174 #define ANA_DEBUG_SELECTION  (1<<16)
 175 /*@}*/
 176
 177
 178 /*! \name Functions for initialization */
 179 /*@{*/
 180
 181 /** Allocates and initializes data structure for trajectory analysis. */
 182 extern int
 183 gmx_ana_traj_create(gmx_ana_traj_t **data, unsigned long flags);
 184 /** Frees the memory allocated for trajectory analysis data. */
 185 extern void
 186 gmx_ana_traj_free(gmx_ana_traj_t *d);
 187 /** Sets additional flags after gmx_ana_traj_create() has been called. */
 188 extern int
 189 gmx_ana_add_flags(gmx_ana_traj_t *d, unsigned long flags);
 190 /** Sets the number of reference groups required. */
 191 extern int
 192 gmx_ana_set_nrefgrps(gmx_ana_traj_t *d, int nrefgrps);
 193 /** Sets the number of analysis groups required. */
 194 extern int
 195 gmx_ana_set_nanagrps(gmx_ana_traj_t *d, int nanagrps);
 196 /** Sets whether PBC are used. */
 197 extern int
 198 gmx_ana_set_pbc(gmx_ana_traj_t *d, bool bPBC);
 199 /** Sets whether molecules are made whole. */
 200 extern int
 201 gmx_ana_set_rmpbc(gmx_ana_traj_t *d, bool bRmPBC);
 202 /** Sets flags that determine what to read from the trajectory. */
 203 extern int
 204 gmx_ana_set_frflags(gmx_ana_traj_t *d, int frflags);
 205 /** Parses command-line arguments and performs some initialization. */
 206 extern int
 207 parse_trjana_args(gmx_ana_traj_t *d, int *argc, char *argv[],
 208                   unsigned long pca_flags, int nfile, t_filenm fnm[],
 209                   int npargs, t_pargs *pa,
 210                   int ndesc, const char **desc,
 211                   int nbugs, const char **bugs,
 212                   output_env_t *oenv);
 213 /** Initializes selection information. */
 214 extern int
 215 gmx_ana_init_selections(gmx_ana_traj_t *d);
 216 /** Initializes calculation of covered fractions for selections. */
 217 extern int
 218 gmx_ana_init_coverfrac(gmx_ana_traj_t *d, e_coverfrac_t type);
 219
 220 /** Returns whether PBC should be used. */
 221 extern bool
 222 gmx_ana_has_pbc(gmx_ana_traj_t *d);
 223 /** Gets the topology information. */
 224 extern int
 225 gmx_ana_get_topology(gmx_ana_traj_t *d, bool bReq, t_topology **top, bool *bTop);
 226 /** Gets the configuration from the topology. */
 227 extern int
 228 gmx_ana_get_topconf(gmx_ana_traj_t *d, rvec **x, matrix box, int *ePBC);
 229 /** Gets the first frame to be analyzed. */
 230 extern int
 231 gmx_ana_get_first_frame(gmx_ana_traj_t *d, t_trxframe **fr);
 232
 233 /** Gets the total number of selections provided by the user. */
 234 extern int
 235 gmx_ana_get_ngrps(gmx_ana_traj_t *d, int *ngrps);
 236 /** Gets the number of analysis groups provided by the user. */
 237 extern int
 238 gmx_ana_get_nanagrps(gmx_ana_traj_t *d, int *nanagrps);
 239 /** Gets the selection object for a reference selection. */
 240 extern int
 241 gmx_ana_get_refsel(gmx_ana_traj_t *d, int i, gmx_ana_selection_t **sel);
 242 /** Gets the selection object for a reference selection. */
 243 extern int
 244 gmx_ana_get_anagrps(gmx_ana_traj_t *d, gmx_ana_selection_t ***sel);
 245 /** Gets an array of names for the selections. */
 246 extern int
 247 gmx_ana_get_grpnames(gmx_ana_traj_t *d, char ***grpnames);
 248 /** Gets the selection collection object that contains all the selections. */
 249 extern int
 250 gmx_ana_get_selcollection(gmx_ana_traj_t *d, gmx_ana_selcollection_t **sc);
 251 /** Prints the selection strings into an XVGR file as comments. */
 252 extern int
 253 xvgr_selections(FILE *out, gmx_ana_traj_t *d);
 254
 255 /*@}*/
 256
 257
 258 /*! \name Functions for reading and analyzing the trajectory
 259  */
 260 /*@{*/
 261
 262 /*! \brief
 263  * Function pointer type for frame analysis functions.
 264  *
 265  * \param[in] top  Topology structure.
 266  * \param[in] fr   Current frame.
 267  * \param[in] pbc  Initialized PBC structure for this frame.
 268  * \param[in] nr   Number of selections in the \p sel array.
 269  * \param[in] sel  Array of selections.
 270  * \param     data User data as provided to gmx_ana_do().
 271  * \returns   0 on success, a non-zero error code on error.
 272  *
 273  * This function is called by gmx_ana_do() for each frame that
 274  * needs to be analyzed.
 275  * Positions to be analyzed can be found in the \p sel array.
 276  * The selection array \p sel also provides information about the atoms that
 277  * have been used to evaluate the positions.
 278  * If a non-zero value is returned, gmx_ana_do() immediately exits and returns
 279  * the same value to the caller.
 280  */
 281 typedef int (*gmx_analysisfunc)(t_topology *top, t_trxframe *fr, t_pbc *pbc,
 282                                 int nr, gmx_ana_selection_t *sel[], void *data);
 283
 284 /** Loops through all frames in the trajectory. */
 285 extern int
 286 gmx_ana_do(gmx_ana_traj_t *d, int flags, gmx_analysisfunc analyze, void *data);
 287 /** Gets the total number of frames analyzed. */
 288 extern int
 289 gmx_ana_get_nframes(gmx_ana_traj_t *d, int *nframes);
 290
 291 /*@}*/
 292
 293 #ifdef __cplusplus
 294 }
 295 #endif
 296
 297 #endif