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