include/trajana.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
   5  * Copyright (c) 2001-2009, The GROMACS development team,
   6  * check out http://www.gromacs.org for more information.
   7  * Copyright (c) 2012,2013, by the GROMACS development team, led by
   8  * David van der Spoel, Berk Hess, Erik Lindahl, and including many
   9  * others, as listed in the AUTHORS file in the top-level source
  10  * directory and at http://www.gromacs.org.
  11  *
  12  * GROMACS is free software; you can redistribute it and/or
  13  * modify it under the terms of the GNU Lesser General Public License
  14  * as published by the Free Software Foundation; either version 2.1
  15  * of the License, or (at your option) any later version.
  16  *
  17  * GROMACS is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  20  * Lesser General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU Lesser General Public
  23  * License along with GROMACS; if not, see
  24  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  25  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  26  *
  27  * If you want to redistribute modifications to GROMACS, please
  28  * consider that scientific software is very special. Version
  29  * control is crucial - bugs must be traceable. We will be happy to
  30  * consider code for inclusion in the official distribution, but
  31  * derived work must not be called official GROMACS. Details are found
  32  * in the README & COPYING files - if they are missing, get the
  33  * official version at http://www.gromacs.org.
  34  *
  35  * To help us fund GROMACS development, we humbly ask that you cite
  36  * the research papers on the package. Check out http://www.gromacs.org.
  37  */
  38 /*! \file
  39  * \brief Main API of the trajectory analysis library.
  40  *
  41  * Contains the API for the core analysis library.
  42  *
  43  * \todo
  44  * Better handling of reference groups.
  45  * It would be nice to be able to provide a string that would be used in
  46  * prompting the groups, and also in automatic reporting of what the tool
  47  * is about to do.
  48  *
  49  * Most analysis tools should include trajana.h
  50  * (which automatically includes indexutil.h, selection.h, position.h)
  51  * and possibly one or more of the following headers:
  52  * displacement.h, histogram.h, nbsearch.h.
  53  * If the tool implements custom selection methods, it should also include
  54  * selmethod.h (which automatically includes selparam.h and selvalue.h).
  55  *
  56  * Other headers (centerofmass.h, poscalc.h) are used internally by the
  57  * library to calculate positions.
  58  * Analysis tools should preferably not use the routines in these headers
  59  * directly, but instead get all positions through selections. This makes
  60  * them more flexible with a minimal amount of work.
  61  */
  62 #ifndef TRAJANA_H
  63 #define TRAJANA_H
  64 #include "visibility.h"
  65 #include "typedefs.h"
  66 #include "filenm.h"
  67 #include "readinp.h"
  68
  69 #include "indexutil.h"
  70 #include "selection.h"
  71
  72 #ifdef __cplusplus
  73 extern "C" {
  74 #endif
  75
  76 /** Data structure for trajectory analysis tools. */
  77 typedef struct gmx_ana_traj_t gmx_ana_traj_t;
  78
  79 /*! \name Flags for gmx_ana_traj_create()
  80  * \anchor analysis_flags
  81  * These flags can be used to alter the behavior of the analysis library to
  82  * suit the analysis tool.
  83  * They are given to the gmx_ana_traj_create() when creating the
  84  * \c gmx_ana_traj_t data structure, and affect the behavior of the other
  85  * functions in this header.
  86  */
  87 /*@{*/
  88 /*! \brief
  89  * Force loading of a topology file.
  90  *
  91  * If this flag is not specified, the topology file is loaded only if it is
  92  * provided on the command line explicitly.
  93  *
  94  * \see gmx_ana_get_topology()
  95  */
  96 #define ANA_REQUIRE_TOP      (1<<0)
  97 /*! \brief
  98  * Do no free the coordinates loaded from the topology.
  99  *
 100  * If this flag is specified, the coordinates loaded from the topology can
 101  * be accessed with gmx_ana_get_topconf().
 102  *
 103  * \see gmx_ana_get_topconf()
 104  */
 105 #define ANA_USE_TOPX         (1<<1)
 106 /*! \brief
 107  * Disallows the user from changing PBC handling.
 108  *
 109  * If this option is not specified, the analysis program (see gmx_analysisfunc())
 110  * may be passed a NULL PBC structure, and it should be able to handle such a
 111  * situation.
 112  */
 113 #define ANA_NOUSER_PBC       (1<<4)
 114 /*! \brief
 115  * Disallows the user from changing PBC removal.
 116  */
 117 #define ANA_NOUSER_RMPBC     (1<<5)
 118 /*! \brief
 119  * Disallows dynamic selections.
 120  *
 121  * If this flag is specified, an error is reported if the user specifies
 122  * any dynamic selections.
 123  */
 124 #define ANA_NO_DYNSEL        (1<<8)
 125 /*! \brief
 126  * Disallows breaking of residues in dynamic selections.
 127  *
 128  * Makes it impossible for the user to select atom-based dynamic selections.
 129  *
 130  * Only has effect if \ref ANA_NO_DYNSEL is not specified.
 131  */
 132 #define ANA_REQUIRE_WHOLE    (1<<9)
 133 /*! \brief
 134  * Disables automatic initialization of selection groups.
 135  *
 136  * If this flag is specified, parse_trjana_args() does not call
 137  * gmx_ana_init_selections(), allowing the program to do some initialization
 138  * before the call.
 139  * In particular, the program can use gmx_ana_set_nrefgprs() and
 140  * gmx_ana_set_nanagrps() before calling gmx_ana_init_selections() to
 141  * control the number of selections to expect.
 142  * This is useful if the program requires a different number of index groups
 143  * with different command-line arguments.
 144  * If the flag is specified, the program should call gmx_ana_init_selections()
 145  * exactly once after the parse_trjana_args() call.
 146  */
 147 #define ANA_USER_SELINIT     (1<<10)
 148 /*! \brief
 149  * Allow only atomic positions to be selected.
 150  *
 151  * Note that this flag only applies to the analysis groups, not the reference
 152  * groups. The reference groups should be checked in the analysis program
 153  * if some limitations are imposed on them.
 154  */
 155 #define ANA_ONLY_ATOMPOS     (1<<11)
 156 /*! \brief
 157  * Use masks in the positions to convey dynamic information.
 158  *
 159  * If this flag is specified, the positions calculated for the selections
 160  * are calculated always for the same group of atoms, even if the selection is
 161  * dynamic.
 162  * Dynamic selections only affect the \p refid field of the indexgroup map
 163  * given in the positions.
 164  */
 165 #define ANA_USE_POSMASK      (1<<12)
 166 /*! \brief
 167  * Pass the reference groups to gmx_analysisfunc().
 168  *
 169  * If this flag is specified, the reference groups are passed on to
 170  * gmx_analysisfunc().
 171  * Similarly, the arrays returned by gmx_ana_get_anagrps() and
 172  * gmx_ana_get_grpnames() contain the reference groups in the beginning.
 173  */
 174 #define ANA_USE_FULLGRPS     (1<<13)
 175 /*! \brief
 176  * Dump the parsed and compiled selection trees.
 177  *
 178  * This flag is used by internal debugging tools to make
 179  * gmx_ana_init_selections() dump the selection trees to stderr.
 180  */
 181 #define ANA_DEBUG_SELECTION  (1<<16)
 182 /*@}*/
 183
 184
 185 /*! \name Functions for initialization */
 186 /*@{*/
 187
 188 /** Allocates and initializes data structure for trajectory analysis. */
 189 GMX_LIBGMX_EXPORT
 190 int
 191 gmx_ana_traj_create(gmx_ana_traj_t **data, unsigned long flags);
 192 /** Frees the memory allocated for trajectory analysis data. */
 193 void
 194 gmx_ana_traj_free(gmx_ana_traj_t *d);
 195 /** Sets additional flags after gmx_ana_traj_create() has been called. */
 196 int
 197 gmx_ana_add_flags(gmx_ana_traj_t *d, unsigned long flags);
 198 /** Sets the number of reference groups required. */
 199 GMX_LIBGMX_EXPORT
 200 int
 201 gmx_ana_set_nrefgrps(gmx_ana_traj_t *d, int nrefgrps);
 202 /** Sets the number of analysis groups required. */
 203 GMX_LIBGMX_EXPORT
 204 int
 205 gmx_ana_set_nanagrps(gmx_ana_traj_t *d, int nanagrps);
 206 /** Sets whether PBC are used. */
 207 int
 208 gmx_ana_set_pbc(gmx_ana_traj_t *d, gmx_bool bPBC);
 209 /** Sets whether molecules are made whole. */
 210 int
 211 gmx_ana_set_rmpbc(gmx_ana_traj_t *d, gmx_bool bRmPBC);
 212 /** Sets flags that determine what to read from the trajectory. */
 213 int
 214 gmx_ana_set_frflags(gmx_ana_traj_t *d, int frflags);
 215 /** Parses command-line arguments and performs some initialization. */
 216 GMX_LIBGMX_EXPORT
 217 int
 218 parse_trjana_args(gmx_ana_traj_t *d, int *argc, char *argv[],
 219                   unsigned long pca_flags, int nfile, t_filenm fnm[],
 220                   int npargs, t_pargs *pa,
 221                   int ndesc, const char **desc,
 222                   int nbugs, const char **bugs,
 223                   output_env_t *oenv);
 224 /** Initializes selection information. */
 225 int
 226 gmx_ana_init_selections(gmx_ana_traj_t *d);
 227 /** Initializes calculation of covered fractions for selections. */
 228 GMX_LIBGMX_EXPORT
 229 int
 230 gmx_ana_init_coverfrac(gmx_ana_traj_t *d, e_coverfrac_t type);
 231
 232 /** Returns whether PBC should be used. */
 233 gmx_bool
 234 gmx_ana_has_pbc(gmx_ana_traj_t *d);
 235 /** Gets the topology information. */
 236 GMX_LIBGMX_EXPORT
 237 int
 238 gmx_ana_get_topology(gmx_ana_traj_t *d, gmx_bool bReq, t_topology **top, gmx_bool *bTop);
 239 /** Gets the configuration from the topology. */
 240 int
 241 gmx_ana_get_topconf(gmx_ana_traj_t *d, rvec **x, matrix box, int *ePBC);
 242 /** Gets the first frame to be analyzed. */
 243 int
 244 gmx_ana_get_first_frame(gmx_ana_traj_t *d, t_trxframe **fr);
 245
 246 /** Gets the total number of selections provided by the user. */
 247 int
 248 gmx_ana_get_ngrps(gmx_ana_traj_t *d, int *ngrps);
 249 /** Gets the number of analysis groups provided by the user. */
 250 GMX_LIBGMX_EXPORT
 251 int
 252 gmx_ana_get_nanagrps(gmx_ana_traj_t *d, int *nanagrps);
 253 /** Gets the selection object for a reference selection. */
 254 GMX_LIBGMX_EXPORT
 255 int
 256 gmx_ana_get_refsel(gmx_ana_traj_t *d, int i, gmx_ana_selection_t **sel);
 257 /** Gets the selection object for a reference selection. */
 258 GMX_LIBGMX_EXPORT
 259 int
 260 gmx_ana_get_anagrps(gmx_ana_traj_t *d, gmx_ana_selection_t ***sel);
 261 /** Gets an array of names for the selections. */
 262 GMX_LIBGMX_EXPORT
 263 int
 264 gmx_ana_get_grpnames(gmx_ana_traj_t *d, char ***grpnames);
 265 /** Gets the selection collection object that contains all the selections. */
 266 int
 267 gmx_ana_get_selcollection(gmx_ana_traj_t *d, gmx_ana_selcollection_t **sc);
 268 /** Prints the selection strings into an XVGR file as comments. */
 269 GMX_LIBGMX_EXPORT
 270 int
 271 xvgr_selections(FILE *out, gmx_ana_traj_t *d);
 272
 273 /*@}*/
 274
 275
 276 /*! \name Functions for reading and analyzing the trajectory
 277  */
 278 /*@{*/
 279
 280 /*! \brief
 281  * Function pointer type for frame analysis functions.
 282  *
 283  * \param[in] top  Topology structure.
 284  * \param[in] fr   Current frame.
 285  * \param[in] pbc  Initialized PBC structure for this frame.
 286  * \param[in] nr   Number of selections in the \p sel array.
 287  * \param[in] sel  Array of selections.
 288  * \param     data User data as provided to gmx_ana_do().
 289  * \returns   0 on success, a non-zero error code on error.
 290  *
 291  * This function is called by gmx_ana_do() for each frame that
 292  * needs to be analyzed.
 293  * Positions to be analyzed can be found in the \p sel array.
 294  * The selection array \p sel also provides information about the atoms that
 295  * have been used to evaluate the positions.
 296  * If a non-zero value is returned, gmx_ana_do() immediately exits and returns
 297  * the same value to the caller.
 298  */
 299 typedef int (*gmx_analysisfunc)(t_topology *top, t_trxframe *fr, t_pbc *pbc,
 300                                 int nr, gmx_ana_selection_t *sel[], void *data);
 301
 302 /** Loops through all frames in the trajectory. */
 303 GMX_LIBGMX_EXPORT
 304 int
 305 gmx_ana_do(gmx_ana_traj_t *d, int flags, gmx_analysisfunc analyze, void *data);
 306 /** Gets the total number of frames analyzed. */
 307 int
 308 gmx_ana_get_nframes(gmx_ana_traj_t *d, int *nframes);
 309
 310 /*@}*/
 311
 312 #ifdef __cplusplus
 313 }
 314 #endif
 315
 316 #endif