include/selection.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 API for handling selection (the \c gmx_ana_selection_t structure and related functions).
  33  *
  34  * There should be no need to use the data structures or call the
  35  * functions in this file directly unless using the selection routines outside
  36  * the main trajectory analysis API.
  37  */
  38 #ifndef SELECTION_H
  39 #define SELECTION_H
  40
  41 #include <position.h>
  42 #include <indexutil.h>
  43
  44 #ifdef __cplusplus
  45 extern "C"
  46 {
  47 #endif
  48
  49 /** Information for a collection of selections. */
  50 typedef struct gmx_ana_selcollection_t gmx_ana_selcollection_t;
  51
  52 struct gmx_ana_poscalc_coll_t;
  53
  54 /** Defines the type of covered fraction. */
  55 typedef enum
  56 {
  57     CFRAC_NONE,         /**< No covered fraction (everything covered). */
  58     CFRAC_SOLIDANGLE,   /**< Fraction of a solid (3D) angle covered. */
  59 } e_coverfrac_t;
  60
  61 /*! \brief
  62  * Describes a single selection.
  63  */
  64 typedef struct gmx_ana_selection_t
  65 {
  66     /** Name of the selection. */
  67     char                   *name;
  68     /** The actual selection string. */
  69     char                   *selstr;
  70     /** Selected positions. */
  71     gmx_ana_pos_t           p;
  72     /** Masses associated with the positions. */
  73     real                   *m;
  74     /** Charges associated with the positions. */
  75     real                   *q;
  76     /** Pointer to the index group that holds the selected atoms. */
  77     struct gmx_ana_index_t *g;
  78     /** TRUE if the value can change as a function of time. */
  79     bool                    bDynamic;
  80     /** Type of the covered fraction. */
  81     e_coverfrac_t           cfractype;
  82     /** TRUE if the covered fraction depends on the frame. */
  83     bool                    bCFracDyn;
  84     /** Covered fraction of the selection for the current frame. */
  85     real                    cfrac;
  86     /** The average covered fraction (over the trajectory). */
  87     real                    avecfrac;
  88
  89     /*! \brief
  90      * Pointer to the root of the selection element tree (internal use only).
  91      *
  92      * \internal
  93      * This field is NULL if the selection has been loaded directly from an
  94      * index file.
  95      */
  96     struct t_selelem       *selelem;
  97     /** Original masses of all possible positions (internal use only). */
  98     real                   *orgm;
  99     /** Original charges of all possible positions (internal use only). */
 100     real                   *orgq;
 101 } gmx_ana_selection_t;
 102
 103 /** Frees the memory allocated for a selection. */
 104 extern void
 105 gmx_ana_selection_free(gmx_ana_selection_t *sel);
 106 /** Returns the name of a selection. */
 107 extern char *
 108 gmx_ana_selection_name(gmx_ana_selection_t *sel);
 109 /** Prints out the selection information. */
 110 extern void
 111 gmx_ana_selection_print_info(gmx_ana_selection_t *sel);
 112 /** Initializes the information for covered fraction. */
 113 extern bool
 114 gmx_ana_selection_init_coverfrac(gmx_ana_selection_t *sel, e_coverfrac_t type);
 115
 116 /** Creates a new empty selection collection. */
 117 extern int
 118 gmx_ana_selcollection_create(gmx_ana_selcollection_t **sc,
 119                              struct gmx_ana_poscalc_coll_t *pcc);
 120 /** Frees the memory allocated for a selection collection. */
 121 extern void
 122 gmx_ana_selcollection_free(gmx_ana_selcollection_t *sc);
 123 /** Sets the default reference position handling for a selection collection. */
 124 extern void
 125 gmx_ana_selcollection_set_refpostype(gmx_ana_selcollection_t *sc, const char *type);
 126 /** Sets the default output position handling for a selection collection. */
 127 extern void
 128 gmx_ana_selcollection_set_outpostype(gmx_ana_selcollection_t *sc,
 129                                      const char *type, bool bMaskOnly);
 130 /** Request evaluation of velocities for selections. */
 131 extern void
 132 gmx_ana_selcollection_set_veloutput(gmx_ana_selcollection_t *sc,
 133                                     bool bVelOut);
 134 /** Request evaluation of forces for selections. */
 135 extern void
 136 gmx_ana_selcollection_set_forceoutput(gmx_ana_selcollection_t *sc,
 137                                       bool bForceOut);
 138 /** Sets the topology for a selection collection. */
 139 extern int
 140 gmx_ana_selcollection_set_topology(gmx_ana_selcollection_t *sc, t_topology *top,
 141                                    int natoms);
 142 /** Returns the number of selections specified by a selection collection. */
 143 extern int
 144 gmx_ana_selcollection_get_count(gmx_ana_selcollection_t *sc);
 145 /** Returns a selection by index. */
 146 extern gmx_ana_selection_t *
 147 gmx_ana_selcollection_get_selection(gmx_ana_selcollection_t *sc, int i);
 148 /** Returns TRUE if the collection requires topology information for evaluation. */
 149 extern bool
 150 gmx_ana_selcollection_requires_top(gmx_ana_selcollection_t *sc);
 151 /** Prints a human-readable version of the internal selection element tree. */
 152 extern void
 153 gmx_ana_selcollection_print_tree(FILE *fp, gmx_ana_selcollection_t *sc, bool bValues);
 154 /** Prints the selection strings into an XVGR file as comments. */
 155 extern void
 156 xvgr_selcollection(FILE *fp, gmx_ana_selcollection_t *sc,
 157                    const output_env_t oenv);
 158
 159 /* In parsetree.c */
 160 /** Parses selection(s) from standard input. */
 161 extern int
 162 gmx_ana_selcollection_parse_stdin(gmx_ana_selcollection_t *sc, int nr,
 163                                   gmx_ana_indexgrps_t *grps,
 164                                   bool bInteractive);
 165 /** Parses selection(s) from a file. */
 166 extern int
 167 gmx_ana_selcollection_parse_file(gmx_ana_selcollection_t *sc, const char *fnm,
 168                                   gmx_ana_indexgrps_t *grps);
 169 /** Parses selection(s) from a string. */
 170 extern int
 171 gmx_ana_selcollection_parse_str(gmx_ana_selcollection_t *sc, const char *str,
 172                                 gmx_ana_indexgrps_t *grps);
 173
 174 /* In compiler.c */
 175 /** Prepares the selections for evaluation and performs some optimizations. */
 176 extern int
 177 gmx_ana_selcollection_compile(gmx_ana_selcollection_t *sc);
 178
 179 /* In evaluate.c */
 180 /** Evaluates the selection. */
 181 extern int
 182 gmx_ana_selcollection_evaluate(gmx_ana_selcollection_t *sc,
 183                                t_trxframe *fr, t_pbc *pbc);
 184 /** Evaluates the largest possible index groups from dynamic selections. */
 185 extern int
 186 gmx_ana_selcollection_evaluate_fin(gmx_ana_selcollection_t *sc, int nframes);
 187
 188 #ifdef __cplusplus
 189 }
 190 #endif
 191
 192 #endif