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,2019, 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 _gmx_sel_evaluate_init(gmx_sel_evaluate_t* data,
  82                             gmx_sel_mempool_t*  mp,
  83                             gmx_ana_index_t*    gall,
  84                             const gmx_mtop_t*   top,
  85                             t_trxframe*         fr,
  86                             t_pbc*              pbc);
  87 /** Evaluates the children of a general selection element. */
  88 void _gmx_sel_evaluate_children(gmx_sel_evaluate_t*                     data,
  89                                 const gmx::SelectionTreeElementPointer& sel,
  90                                 gmx_ana_index_t*                        g);
  91 /** Evaluates the children of a \ref SEL_EXPRESSION element. */
  92 void _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 _gmx_sel_evaluate_root(gmx_sel_evaluate_t*                     data,
 118                             const gmx::SelectionTreeElementPointer& sel,
 119                             gmx_ana_index_t*                        g);
 120 /*! \brief
 121  * Evaluates a static group selection element.
 122  *
 123  * \param[in] data Data for the current frame.
 124  * \param[in] sel Selection element being evaluated.
 125  * \param[in] g   Group for which \p sel should be evaluated.
 126  * \returns   0 for success.
 127  *
 128  * Sets the value of \p sel to the intersection of \p g and \p sel->u.cgrp.
 129  *
 130  * This function can be used as gmx::SelectionTreeElement::evaluate for
 131  * \ref SEL_CONST elements with value type \ref GROUP_VALUE.
 132  */
 133 void _gmx_sel_evaluate_static(gmx_sel_evaluate_t*                     data,
 134                               const gmx::SelectionTreeElementPointer& sel,
 135                               gmx_ana_index_t*                        g);
 136 /** Evaluates an arithmetic expression element. */
 137 void _gmx_sel_evaluate_arithmetic(gmx_sel_evaluate_t*                     data,
 138                                   const gmx::SelectionTreeElementPointer& sel,
 139                                   gmx_ana_index_t*                        g);
 140 /*@}*/
 141
 142 /*! \name Subexpression evaluation functions
 143  */
 144 /*@{*/
 145 /** Evaluates a subexpression when there is only one reference. */
 146 void _gmx_sel_evaluate_subexpr_simple(gmx_sel_evaluate_t*                     data,
 147                                       const gmx::SelectionTreeElementPointer& sel,
 148                                       gmx_ana_index_t*                        g);
 149 /** Evaluates a subexpression when the evaluation group is static. */
 150 void _gmx_sel_evaluate_subexpr_staticeval(gmx_sel_evaluate_t*                     data,
 151                                           const gmx::SelectionTreeElementPointer& sel,
 152                                           gmx_ana_index_t*                        g);
 153 /** Evaluates a subexpression. */
 154 void _gmx_sel_evaluate_subexpr(gmx_sel_evaluate_t*                     data,
 155                                const gmx::SelectionTreeElementPointer& sel,
 156                                gmx_ana_index_t*                        g);
 157 /** Evaluates a subexpression reference when there are no other references. */
 158 void _gmx_sel_evaluate_subexprref_simple(gmx_sel_evaluate_t*                     data,
 159                                          const gmx::SelectionTreeElementPointer& sel,
 160                                          gmx_ana_index_t*                        g);
 161 /** Evaluates a subexpression reference. */
 162 void _gmx_sel_evaluate_subexprref(gmx_sel_evaluate_t*                     data,
 163                                   const gmx::SelectionTreeElementPointer& sel,
 164                                   gmx_ana_index_t*                        g);
 165 /*@}*/
 166
 167 /*! \name Method evaluation functions
 168  */
 169 /*@{*/
 170
 171 /** Evaluates a method expression. */
 172 void _gmx_sel_evaluate_method(gmx_sel_evaluate_t*                     data,
 173                               const gmx::SelectionTreeElementPointer& sel,
 174                               gmx_ana_index_t*                        g);
 175 /** Evaluates a modifier expression. */
 176 void _gmx_sel_evaluate_modifier(gmx_sel_evaluate_t*                     data,
 177                                 const gmx::SelectionTreeElementPointer& sel,
 178                                 gmx_ana_index_t*                        g);
 179 /*@}*/
 180
 181 /*! \name Boolean evaluation functions
 182  */
 183 /*@{*/
 184 /** Evaluates a boolean NOT element. */
 185 void _gmx_sel_evaluate_not(gmx_sel_evaluate_t*                     data,
 186                            const gmx::SelectionTreeElementPointer& sel,
 187                            gmx_ana_index_t*                        g);
 188 /** Evaluates a boolean AND element with short-circuiting. */
 189 void _gmx_sel_evaluate_and(gmx_sel_evaluate_t*                     data,
 190                            const gmx::SelectionTreeElementPointer& sel,
 191                            gmx_ana_index_t*                        g);
 192 /** Evaluates a boolean OR element with short-circuiting. */
 193 void _gmx_sel_evaluate_or(gmx_sel_evaluate_t*                     data,
 194                           const gmx::SelectionTreeElementPointer& sel,
 195                           gmx_ana_index_t*                        g);
 196 /*@}*/
 197
 198 #endif