src/gromacs/selection/selectioncollection_impl.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2009-2016, The GROMACS development team.
   5  * Copyright (c) 2019,2020, by the GROMACS development team, led by
   6  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   7  * and including many others, as listed in the AUTHORS file in the
   8  * top-level source directory and at http://www.gromacs.org.
   9  *
  10  * GROMACS is free software; you can redistribute it and/or
  11  * modify it under the terms of the GNU Lesser General Public License
  12  * as published by the Free Software Foundation; either version 2.1
  13  * of the License, or (at your option) any later version.
  14  *
  15  * GROMACS is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18  * Lesser General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU Lesser General Public
  21  * License along with GROMACS; if not, see
  22  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  23  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  24  *
  25  * If you want to redistribute modifications to GROMACS, please
  26  * consider that scientific software is very special. Version
  27  * control is crucial - bugs must be traceable. We will be happy to
  28  * consider code for inclusion in the official distribution, but
  29  * derived work must not be called official GROMACS. Details are found
  30  * in the README & COPYING files - if they are missing, get the
  31  * official version at http://www.gromacs.org.
  32  *
  33  * To help us fund GROMACS development, we humbly ask that you cite
  34  * the research papers on the package. Check out http://www.gromacs.org.
  35  */
  36 /*! \internal \file
  37  * \brief
  38  * Declares private implementation class for gmx::SelectionCollection.
  39  *
  40  * This header also defines ::gmx_ana_selcollection_t, which is used in the old
  41  * C code for handling selection collections.
  42  *
  43  * \author Teemu Murtola <teemu.murtola@gmail.com>
  44  * \ingroup module_selection
  45  */
  46 #ifndef GMX_SELECTION_SELECTIONCOLLECTION_IMPL_H
  47 #define GMX_SELECTION_SELECTIONCOLLECTION_IMPL_H
  48
  49 #include <memory>
  50 #include <string>
  51 #include <vector>
  52
  53 #include "gromacs/onlinehelp/ihelptopic.h"
  54 #include "gromacs/selection/indexutil.h"
  55 #include "gromacs/selection/selection.h" // For gmx::SelectionList
  56 #include "gromacs/selection/selectioncollection.h"
  57
  58 #include "poscalc.h"
  59 #include "selelem.h"
  60
  61 struct gmx_mtop_t;
  62 struct gmx_sel_mempool_t;
  63 struct t_pbc;
  64 struct t_trxframe;
  65
  66 namespace gmx
  67 {
  68
  69 //! Smart pointer for managing an internal selection data object.
  70 typedef std::unique_ptr<internal::SelectionData> SelectionDataPointer;
  71 //! Container for storing a list of selections internally.
  72 typedef std::vector<SelectionDataPointer> SelectionDataList;
  73
  74 class SelectionParserSymbolTable;
  75 struct SelectionTopologyProperties;
  76
  77 } // namespace gmx
  78
  79 /*! \internal \brief
  80  * Information for a collection of selections.
  81  *
  82  * \ingroup module_selection
  83  */
  84 struct gmx_ana_selcollection_t
  85 {
  86     //! Position calculation collection used for selection position evaluation.
  87     gmx::PositionCalculationCollection pcc;
  88     //! Root of the selection element tree.
  89     gmx::SelectionTreeElementPointer root;
  90     /*! \brief
  91      * Array of compiled selections.
  92      *
  93      * Has the responsibility of managing the memory for the contained objects,
  94      * but note that gmx::Selection instances also hold pointers to the
  95      * objects.
  96      */
  97     gmx::SelectionDataList sel;
  98     /** Number of variables defined. */
  99     int nvars;
 100     /** Selection strings for variables. */
 101     char** varstrs;
 102
 103     /** Topology for the collection. */
 104     const gmx_mtop_t* top;
 105     /** Index group that contains all the atoms. */
 106     gmx_ana_index_t gall;
 107     /** Memory pool used for selection evaluation. */
 108     gmx_sel_mempool_t* mempool;
 109     //! Parser symbol table.
 110     // Never releases ownership.
 111     std::unique_ptr<gmx::SelectionParserSymbolTable> symtab;
 112     //! Root of help topic tree (NULL is no help yet requested).
 113     gmx::HelpTopicPointer rootHelp;
 114 };
 115
 116 namespace gmx
 117 {
 118
 119 class ExceptionInitializer;
 120
 121 /*! \internal \brief
 122  * Private implemention class for SelectionCollection.
 123  *
 124  * \ingroup module_selection
 125  */
 126 class SelectionCollection::Impl
 127 {
 128 public:
 129     /*! \brief
 130      * Creates a new selection collection.
 131      *
 132      * \throws  std::bad_alloc if out of memory.
 133      */
 134     Impl();
 135     ~Impl();
 136
 137     /*! \brief
 138      * Clears the symbol table of the selection collection.
 139      *
 140      * Does not throw.
 141      */
 142     void clearSymbolTable();
 143     /*! \brief
 144      * Replace group references by group contents.
 145      *
 146      * \param[in]    root    Root of selection tree to process.
 147      * \param        errors  Object for reporting any error messages.
 148      * \throws std::bad_alloc if out of memory.
 149      *
 150      * Recursively searches the selection tree for unresolved external
 151      * references.  If one is found, finds the referenced group in
 152      * \a grps_ and replaces the reference with a constant element that
 153      * contains the atoms from the referenced group.  Any failures to
 154      * resolve references are reported to \p errors.
 155      */
 156     void resolveExternalGroups(const gmx::SelectionTreeElementPointer& root, ExceptionInitializer* errors);
 157
 158     //! Whether forces have been requested for some selection.
 159     bool areForcesRequested() const;
 160     /*! \brief
 161      * Returns topology properties needed for a certain position type.
 162      */
 163     static SelectionTopologyProperties requiredTopologyPropertiesForPositionType(const std::string& post,
 164                                                                                  bool forces);
 165
 166     //! Describes the available debugging levels
 167     enum class DebugLevel : int
 168     {
 169         //! No debugging
 170         None,
 171         //! Print selection trees after parsing and compilation
 172         Basic,
 173         //! As PrintCompiled, also print intermediate compilation trees
 174         Compiled,
 175         //! As PrintCompiled, also print the tree after evaluation
 176         Evaluated,
 177         //! Combine Compiled and Evaluated
 178         Full,
 179         //! Ends the enumeration
 180         Count
 181     };
 182
 183     //! Internal data, used for interfacing with old C code.
 184     gmx_ana_selcollection_t sc_;
 185     //! Default reference position type for selections.
 186     std::string rpost_;
 187     //! Default output position type for selections.
 188     std::string spost_;
 189     //! Atoms needed for evaluating the selections.
 190     gmx_ana_index_t requiredAtoms_;
 191     //! Debugging level for the collection.
 192     DebugLevel debugLevel_;
 193     //! Whether setIndexGroups() has been called.
 194     bool bExternalGroupsSet_;
 195     //! External index groups (can be NULL).
 196     gmx_ana_indexgrps_t* grps_;
 197 };
 198
 199 /*! \internal
 200  * \brief
 201  * Implements selection evaluation.
 202  *
 203  * This class is used to implement SelectionCollection::evaluate() and
 204  * SelectionCollection::evaluateFinal().
 205  *
 206  * \ingroup module_selection
 207  */
 208 class SelectionEvaluator
 209 {
 210 public:
 211     SelectionEvaluator();
 212
 213     /*! \brief
 214      * Evaluates selections in a collection.
 215      */
 216     void evaluate(SelectionCollection* sc, t_trxframe* fr, t_pbc* pbc);
 217     /*! \brief
 218      * Evaluates the final state for dynamic selections.
 219      */
 220     void evaluateFinal(SelectionCollection* sc, int nframes);
 221 };
 222
 223 } // namespace gmx
 224
 225 #endif