src/gromacs/selection/selectioncollection-impl.h

   1 /*
   2  *
   3  *                This source code is part of
   4  *
   5  *                 G   R   O   M   A   C   S
   6  *
   7  *          GROningen MAchine for Chemical Simulations
   8  *
   9  * Written by David van der Spoel, Erik Lindahl, Berk Hess, and others.
  10  * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
  11  * Copyright (c) 2001-2009, The GROMACS development team,
  12  * check out http://www.gromacs.org for more information.
  13
  14  * This program is free software; you can redistribute it and/or
  15  * modify it under the terms of the GNU General Public License
  16  * as published by the Free Software Foundation; either version 2
  17  * of the License, or (at your option) any later version.
  18  *
  19  * If you want to redistribute modifications, please consider that
  20  * scientific software is very special. Version control is crucial -
  21  * bugs must be traceable. We will be happy to consider code for
  22  * inclusion in the official distribution, but derived work must not
  23  * be called official GROMACS. Details are found in the README & COPYING
  24  * files - if they are missing, get the official version at www.gromacs.org.
  25  *
  26  * To help us fund GROMACS development, we humbly ask that you cite
  27  * the papers on the package - you can find them in the top README file.
  28  *
  29  * For more info, check our website at http://www.gromacs.org
  30  */
  31 /*! \internal \file
  32  * \brief
  33  * Declares private implementation class for gmx::SelectionCollection.
  34  *
  35  * This header also defines ::gmx_ana_selcollection_t, which is used in the old
  36  * C code for handling selection collections.
  37  *
  38  * \author Teemu Murtola <teemu.murtola@cbr.su.se>
  39  * \ingroup module_selection
  40  */
  41 #ifndef GMX_SELECTION_SELECTIONCOLLECTION_IMPL_H
  42 #define GMX_SELECTION_SELECTIONCOLLECTION_IMPL_H
  43
  44 #include <string>
  45 #include <vector>
  46
  47 #include "../legacyheaders/typedefs.h"
  48
  49 #include "../onlinehelp/helptopicinterface.h"
  50 #include "../options/options.h"
  51 #include "../utility/uniqueptr.h"
  52 #include "indexutil.h"
  53 #include "poscalc.h"
  54 #include "selection.h" // For gmx::SelectionList
  55 #include "selectioncollection.h"
  56
  57 namespace gmx
  58 {
  59 //! Smart pointer for managing an internal selection data object.
  60 typedef gmx_unique_ptr<internal::SelectionData>::type SelectionDataPointer;
  61 //! Container for storing a list of selections internally.
  62 typedef std::vector<SelectionDataPointer> SelectionDataList;
  63 }
  64
  65 /*! \internal \brief
  66  * Information for a collection of selections.
  67  *
  68  * \ingroup module_selection
  69  */
  70 struct gmx_ana_selcollection_t
  71 {
  72     /** Root of the selection element tree. */
  73     struct t_selelem           *root;
  74     /*! \brief
  75      * Array of compiled selections.
  76      *
  77      * Has the responsibility of managing the memory for the contained objects,
  78      * but note that gmx::Selection instances also hold pointers to the
  79      * objects.
  80      */
  81     gmx::SelectionDataList         sel;
  82     /** Number of variables defined. */
  83     int                            nvars;
  84     /** Selection strings for variables. */
  85     char                         **varstrs;
  86
  87     /** Topology for the collection. */
  88     t_topology                    *top;
  89     /** Index group that contains all the atoms. */
  90     struct gmx_ana_index_t         gall;
  91     /** Position calculation collection used for selection position evaluation. */
  92     gmx::PositionCalculationCollection  pcc;
  93     /** Memory pool used for selection evaluation. */
  94     struct gmx_sel_mempool_t      *mempool;
  95     /** Parser symbol table. */
  96     struct gmx_sel_symtab_t     *symtab;
  97     //! Root of help topic tree (NULL is no help yet requested).
  98     gmx::HelpTopicPointer          rootHelp;
  99 };
 100
 101 namespace gmx
 102 {
 103
 104 class MessageStringCollector;
 105
 106 /*! \internal \brief
 107  * Private implemention class for SelectionCollection.
 108  *
 109  * \ingroup module_selection
 110  */
 111 class SelectionCollection::Impl
 112 {
 113     public:
 114         /*! \brief
 115          * Creates a new selection collection.
 116          *
 117          * \throws  std::bad_alloc if out of memory.
 118          */
 119         Impl();
 120         ~Impl();
 121
 122         /*! \brief
 123          * Clears the symbol table of the selection collection.
 124          *
 125          * Does not throw.
 126          */
 127         void clearSymbolTable();
 128         /*! \brief
 129          * Helper function that runs the parser once the tokenizer has been
 130          * initialized.
 131          *
 132          * \param[in,out] scanner Scanner data structure.
 133          * \param[in]     maxnr   Maximum number of selections to parse
 134          *      (if -1, parse as many as provided by the user).
 135          * \returns       Vector of parsed selections.
 136          * \throws        std::bad_alloc if out of memory.
 137          * \throws        InvalidInputError if there is a parsing error.
 138          *
 139          * Used internally to implement parseFromStdin(), parseFromFile() and
 140          * parseFromString().
 141          */
 142         SelectionList runParser(void *scanner, int maxnr);
 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          *
 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          * Does not throw currently, but this is subject to change when more
 156          * underlying code is converted to C++.
 157          */
 158         void resolveExternalGroups(struct t_selelem *root,
 159                                    MessageStringCollector *errors);
 160
 161         //! Internal data, used for interfacing with old C code.
 162         gmx_ana_selcollection_t _sc;
 163         //! Options object for setting global properties on the collection.
 164         Options                 _options;
 165         //! Default reference position type for selections.
 166         std::string             _rpost;
 167         //! Default output position type for selections.
 168         std::string             _spost;
 169         /*! \brief
 170          * Debugging level for the collection.
 171          *
 172          * Possible values:
 173          *  - 0: no debugging
 174          *  - 1: print selection trees after parsing and compilation
 175          *  - 2: like 1, also print intermediate compilation trees
 176          *  - 3: like 1, also print the tree after evaluation
 177          *  - 4: combine 2 and 3
 178          */
 179         int                     _debugLevel;
 180         //! Whether setIndexGroups() has been called.
 181         bool                    _bExternalGroupsSet;
 182         //! External index groups (can be NULL).
 183         gmx_ana_indexgrps_t    *_grps;
 184 };
 185
 186 /*! \internal \brief
 187  * Implements selection evaluation.
 188  *
 189  * This class is used to implement SelectionCollection::evaluate() and
 190  * SelectionCollection::evaluateFinal().
 191  *
 192  * \ingroup module_selection
 193  */
 194 class SelectionEvaluator
 195 {
 196     public:
 197         SelectionEvaluator();
 198
 199         /*! \brief
 200          * Evaluates selections in a collection.
 201          */
 202         void evaluate(SelectionCollection *sc, t_trxframe *fr, t_pbc *pbc);
 203         /*! \brief
 204          * Evaluates the final state for dynamic selections.
 205          */
 206         void evaluateFinal(SelectionCollection *sc, int nframes);
 207 };
 208
 209 } // namespace gmx
 210
 211 #endif