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