src/gromacs/selection/evaluate.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2009,2010,2011,2012,2013,2014,2016, by the GROMACS development team, led by
   5  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   6  * and including many others, as listed in the AUTHORS file in the
   7  * top-level source directory and at http://www.gromacs.org.
   8  *
   9  * GROMACS is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public License
  11  * as published by the Free Software Foundation; either version 2.1
  12  * of the License, or (at your option) any later version.
  13  *
  14  * GROMACS is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public
  20  * License along with GROMACS; if not, see
  21  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  22  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  23  *
  24  * If you want to redistribute modifications to GROMACS, please
  25  * consider that scientific software is very special. Version
  26  * control is crucial - bugs must be traceable. We will be happy to
  27  * consider code for inclusion in the official distribution, but
  28  * derived work must not be called official GROMACS. Details are found
  29  * in the README & COPYING files - if they are missing, get the
  30  * official version at http://www.gromacs.org.
  31  *
  32  * To help us fund GROMACS development, we humbly ask that you cite
  33  * the research papers on the package. Check out http://www.gromacs.org.
  34  */
  35 /*! \internal \file
  36  * \brief Evaluation functions for sel_evalfunc().
  37  *
  38  * This is an implementation header: there should be no need to use it outside
  39  * this directory.
  40  * Users should only use SelectionCollection::evaluate() to evaluate
  41  * selections.
  42  *
  43  * The functions defined in this header file are all the possible values
  44  * for the gmx::SelectionTreeElement::evaluate field (in addition to NULL).
  45  *
  46  * \author Teemu Murtola <teemu.murtola@gmail.com>
  47  * \ingroup module_selection
  48  */
  49 #ifndef GMX_SELECTION_EVALUATE_H
  50 #define GMX_SELECTION_EVALUATE_H
  51
  52 #include "selelem.h"
  53
  54 struct gmx_ana_index_t;
  55 struct gmx_mtop_t;
  56 struct gmx_sel_mempool_t;
  57 struct t_pbc;
  58 struct t_trxframe;
  59
  60 /*! \internal \brief
  61  * Data structure for passing information required during evaluation.
  62  */
  63 struct gmx_sel_evaluate_t
  64 {
  65     /** Memory pool for intermediate values. */
  66     gmx_sel_mempool_t        *mp;
  67     /** Index group that contains all the atoms. */
  68     gmx_ana_index_t          *gall;
  69     /** Topology information. */
  70     const gmx_mtop_t         *top;
  71     /** Current frame. */
  72     t_trxframe               *fr;
  73     /** PBC data. */
  74     t_pbc                    *pbc;
  75 };
  76
  77 /*! \name Utility functions
  78  */
  79 /*@{*/
  80 /** Initializes an evaluation data structure. */
  81 void
  82 _gmx_sel_evaluate_init(gmx_sel_evaluate_t *data,
  83                        gmx_sel_mempool_t *mp, gmx_ana_index_t *gall,
  84                        const gmx_mtop_t *top, t_trxframe *fr, t_pbc *pbc);
  85 /** Evaluates the children of a general selection element. */
  86 void
  87 _gmx_sel_evaluate_children(gmx_sel_evaluate_t                     *data,
  88                            const gmx::SelectionTreeElementPointer &sel,
  89                            gmx_ana_index_t                        *g);
  90 /** Evaluates the children of a \ref SEL_EXPRESSION element. */
  91 void
  92 _gmx_sel_evaluate_method_params(gmx_sel_evaluate_t                     *data,
  93                                 const gmx::SelectionTreeElementPointer &sel,
  94                                 gmx_ana_index_t                        *g);
  95 /*@}*/
  96
  97 /*! \name Misc. evaluation functions
  98  */
  99 /*@{*/
 100 /*! \brief
 101  * Evaluates a root selection element.
 102  *
 103  * \param[in] data Data for the current frame.
 104  * \param[in] sel Selection element being evaluated.
 105  * \param[in] g   Group for which \p sel should be evaluated
 106  *   (not used, can be NULL).
 107  * \returns   0 on success, a non-zero error code on error.
 108  *
 109  * Evaluates the first child element in the group defined by \p sel->u.cgrp.
 110  * If \p sel->u.cgrp is empty, nothing is done.
 111  * The value of \p sel is not touched (root elements do not evaluate to
 112  * values).
 113  *
 114  * This function can be used as gmx::SelectionTreeElement::evaluate for
 115  * \ref SEL_ROOT elements.
 116  */
 117 void
 118 _gmx_sel_evaluate_root(gmx_sel_evaluate_t                     *data,
 119                        const gmx::SelectionTreeElementPointer &sel,
 120                        gmx_ana_index_t                        *g);
 121 /*! \brief
 122  * Evaluates a static group selection element.
 123  *
 124  * \param[in] data Data for the current frame.
 125  * \param[in] sel Selection element being evaluated.
 126  * \param[in] g   Group for which \p sel should be evaluated.
 127  * \returns   0 for success.
 128  *
 129  * Sets the value of \p sel to the intersection of \p g and \p sel->u.cgrp.
 130  *
 131  * This function can be used as gmx::SelectionTreeElement::evaluate for
 132  * \ref SEL_CONST elements with value type \ref GROUP_VALUE.
 133  */
 134 void
 135 _gmx_sel_evaluate_static(gmx_sel_evaluate_t                     *data,
 136                          const gmx::SelectionTreeElementPointer &sel,
 137                          gmx_ana_index_t                        *g);
 138 /** Evaluates an arithmetic expression element. */
 139 void
 140 _gmx_sel_evaluate_arithmetic(gmx_sel_evaluate_t                     *data,
 141                              const gmx::SelectionTreeElementPointer &sel,
 142                              gmx_ana_index_t                        *g);
 143 /*@}*/
 144
 145 /*! \name Subexpression evaluation functions
 146  */
 147 /*@{*/
 148 /** Evaluates a subexpression when there is only one reference. */
 149 void
 150 _gmx_sel_evaluate_subexpr_simple(gmx_sel_evaluate_t                     *data,
 151                                  const gmx::SelectionTreeElementPointer &sel,
 152                                  gmx_ana_index_t                        *g);
 153 /** Evaluates a subexpression when the evaluation group is static. */
 154 void
 155 _gmx_sel_evaluate_subexpr_staticeval(gmx_sel_evaluate_t                     *data,
 156                                      const gmx::SelectionTreeElementPointer &sel,
 157                                      gmx_ana_index_t                        *g);
 158 /** Evaluates a subexpression. */
 159 void
 160 _gmx_sel_evaluate_subexpr(gmx_sel_evaluate_t                     *data,
 161                           const gmx::SelectionTreeElementPointer &sel,
 162                           gmx_ana_index_t                        *g);
 163 /** Evaluates a subexpression reference when there are no other references. */
 164 void
 165 _gmx_sel_evaluate_subexprref_simple(gmx_sel_evaluate_t                     *data,
 166                                     const gmx::SelectionTreeElementPointer &sel,
 167                                     gmx_ana_index_t                        *g);
 168 /** Evaluates a subexpression reference. */
 169 void
 170 _gmx_sel_evaluate_subexprref(gmx_sel_evaluate_t                     *data,
 171                              const gmx::SelectionTreeElementPointer &sel,
 172                              gmx_ana_index_t                        *g);
 173 /*@}*/
 174
 175 /*! \name Method evaluation functions
 176  */
 177 /*@{*/
 178
 179 /** Evaluates a method expression. */
 180 void
 181 _gmx_sel_evaluate_method(gmx_sel_evaluate_t                     *data,
 182                          const gmx::SelectionTreeElementPointer &sel,
 183                          gmx_ana_index_t                        *g);
 184 /** Evaluates a modifier expression. */
 185 void
 186 _gmx_sel_evaluate_modifier(gmx_sel_evaluate_t                     *data,
 187                            const gmx::SelectionTreeElementPointer &sel,
 188                            gmx_ana_index_t                        *g);
 189 /*@}*/
 190
 191 /*! \name Boolean evaluation functions
 192  */
 193 /*@{*/
 194 /** Evaluates a boolean NOT element. */
 195 void
 196 _gmx_sel_evaluate_not(gmx_sel_evaluate_t                     *data,
 197                       const gmx::SelectionTreeElementPointer &sel,
 198                       gmx_ana_index_t                        *g);
 199 /** Evaluates a boolean AND element with short-circuiting. */
 200 void
 201 _gmx_sel_evaluate_and(gmx_sel_evaluate_t                     *data,
 202                       const gmx::SelectionTreeElementPointer &sel,
 203                       gmx_ana_index_t                        *g);
 204 /** Evaluates a boolean OR element with short-circuiting. */
 205 void
 206 _gmx_sel_evaluate_or(gmx_sel_evaluate_t                     *data,
 207                      const gmx::SelectionTreeElementPointer &sel,
 208                      gmx_ana_index_t                        *g);
 209 /*@}*/
 210
 211 #endif