src/gromacs/selection/selectioncollection-impl.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2009,2010,2011,2012,2013,2014,2015,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
  37  * Declares private implementation class for gmx::SelectionCollection.
  38  *
  39  * This header also defines ::gmx_ana_selcollection_t, which is used in the old
  40  * C code for handling selection collections.
  41  *
  42  * \author Teemu Murtola <teemu.murtola@gmail.com>
  43  * \ingroup module_selection
  44  */
  45 #ifndef GMX_SELECTION_SELECTIONCOLLECTION_IMPL_H
  46 #define GMX_SELECTION_SELECTIONCOLLECTION_IMPL_H
  47
  48 #include <memory>
  49 #include <string>
  50 #include <vector>
  51
  52 #include "gromacs/onlinehelp/ihelptopic.h"
  53 #include "gromacs/selection/indexutil.h"
  54 #include "gromacs/selection/selection.h" // For gmx::SelectionList
  55 #include "gromacs/selection/selectioncollection.h"
  56
  57 #include "poscalc.h"
  58 #include "selelem.h"
  59
  60 struct gmx_mtop_t;
  61 struct gmx_sel_mempool_t;
  62 struct t_pbc;
  63 struct t_trxframe;
  64
  65 namespace gmx
  66 {
  67
  68 //! Smart pointer for managing an internal selection data object.
  69 typedef std::unique_ptr<internal::SelectionData> SelectionDataPointer;
  70 //! Container for storing a list of selections internally.
  71 typedef std::vector<SelectionDataPointer> SelectionDataList;
  72
  73 class SelectionParserSymbolTable;
  74 struct SelectionTopologyProperties;
  75
  76 } // namespace gmx
  77
  78 /*! \internal \brief
  79  * Information for a collection of selections.
  80  *
  81  * \ingroup module_selection
  82  */
  83 struct gmx_ana_selcollection_t
  84 {
  85     //! Position calculation collection used for selection position evaluation.
  86     gmx::PositionCalculationCollection  pcc;
  87     //! Root of the selection element tree.
  88     gmx::SelectionTreeElementPointer    root;
  89     /*! \brief
  90      * Array of compiled selections.
  91      *
  92      * Has the responsibility of managing the memory for the contained objects,
  93      * but note that gmx::Selection instances also hold pointers to the
  94      * objects.
  95      */
  96     gmx::SelectionDataList         sel;
  97     /** Number of variables defined. */
  98     int                            nvars;
  99     /** Selection strings for variables. */
 100     char                         **varstrs;
 101
 102     /** Topology for the collection. */
 103     const gmx_mtop_t                                  *top;
 104     /** Index group that contains all the atoms. */
 105     gmx_ana_index_t                                    gall;
 106     /** Memory pool used for selection evaluation. */
 107     gmx_sel_mempool_t                                 *mempool;
 108     //! Parser symbol table.
 109     // Never releases ownership.
 110     std::unique_ptr<gmx::SelectionParserSymbolTable>   symtab;
 111     //! Root of help topic tree (NULL is no help yet requested).
 112     gmx::HelpTopicPointer                              rootHelp;
 113 };
 114
 115 namespace gmx
 116 {
 117
 118 class ExceptionInitializer;
 119
 120 /*! \internal \brief
 121  * Private implemention class for SelectionCollection.
 122  *
 123  * \ingroup module_selection
 124  */
 125 class SelectionCollection::Impl
 126 {
 127     public:
 128         /*! \brief
 129          * Creates a new selection collection.
 130          *
 131          * \throws  std::bad_alloc if out of memory.
 132          */
 133         Impl();
 134         ~Impl();
 135
 136         /*! \brief
 137          * Clears the symbol table of the selection collection.
 138          *
 139          * Does not throw.
 140          */
 141         void clearSymbolTable();
 142         /*! \brief
 143          * Replace group references by group contents.
 144          *
 145          * \param[in]    root    Root of selection tree to process.
 146          * \param        errors  Object for reporting any error messages.
 147          * \throws std::bad_alloc if out of memory.
 148          *
 149          * Recursively searches the selection tree for unresolved external
 150          * references.  If one is found, finds the referenced group in
 151          * \a grps_ and replaces the reference with a constant element that
 152          * contains the atoms from the referenced group.  Any failures to
 153          * resolve references are reported to \p errors.
 154          */
 155         void resolveExternalGroups(const gmx::SelectionTreeElementPointer &root,
 156                                    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         SelectionTopologyProperties
 164         requiredTopologyPropertiesForPositionType(const std::string &post,
 165                                                   bool               forces) const;
 166
 167         //! Internal data, used for interfacing with old C code.
 168         gmx_ana_selcollection_t sc_;
 169         //! Default reference position type for selections.
 170         std::string             rpost_;
 171         //! Default output position type for selections.
 172         std::string             spost_;
 173         //! Atoms needed for evaluating the selections.
 174         gmx_ana_index_t         requiredAtoms_;
 175         /*! \brief
 176          * Debugging level for the collection.
 177          *
 178          * Possible values:
 179          *  - 0: no debugging
 180          *  - 1: print selection trees after parsing and compilation
 181          *  - 2: like 1, also print intermediate compilation trees
 182          *  - 3: like 1, also print the tree after evaluation
 183          *  - 4: combine 2 and 3
 184          */
 185         int                     debugLevel_;
 186         //! Whether setIndexGroups() has been called.
 187         bool                    bExternalGroupsSet_;
 188         //! External index groups (can be NULL).
 189         gmx_ana_indexgrps_t    *grps_;
 190 };
 191
 192 /*! \internal
 193  * \brief
 194  * Implements selection evaluation.
 195  *
 196  * This class is used to implement SelectionCollection::evaluate() and
 197  * SelectionCollection::evaluateFinal().
 198  *
 199  * \ingroup module_selection
 200  */
 201 class SelectionEvaluator
 202 {
 203     public:
 204         SelectionEvaluator();
 205
 206         /*! \brief
 207          * Evaluates selections in a collection.
 208          */
 209         void evaluate(SelectionCollection *sc, t_trxframe *fr, t_pbc *pbc);
 210         /*! \brief
 211          * Evaluates the final state for dynamic selections.
 212          */
 213         void evaluateFinal(SelectionCollection *sc, int nframes);
 214 };
 215
 216 } // namespace gmx
 217
 218 #endif