src/gromacs/selection/selectionoption.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2010,2011,2012,2013,2014, 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 /*! \file
  36  * \brief
  37  * Declares gmx::SelectionOption and gmx::SelectionOptionInfo.
  38  *
  39  * \author Teemu Murtola <teemu.murtola@gmail.com>
  40  * \inpublicapi
  41  * \ingroup module_selection
  42  */
  43 #ifndef GMX_SELECTION_SELECTIONOPTION_H
  44 #define GMX_SELECTION_SELECTIONOPTION_H
  45
  46 #include "gromacs/options/abstractoption.h"
  47 #include "gromacs/selection/selection.h"
  48 #include "gromacs/selection/selectionenums.h"
  49
  50 namespace gmx
  51 {
  52
  53 class SelectionOptionInfo;
  54 class SelectionOptionManager;
  55 class SelectionOptionStorage;
  56
  57 /*! \brief
  58  * Specifies an option that provides selection(s).
  59  *
  60  * Public methods in this class do not throw.
  61  *
  62  * To use options of this type, SelectionOptionManager must first be added to
  63  * the Options collection.  For trajectory analysis tools, the framework takes
  64  * care of this.
  65  *
  66  * \todo
  67  * Support for specifying that an option accepts, e.g., two to four selections.
  68  * Currently, only a fixed count or any number of selections is possible.
  69  * \if internal
  70  * In addition to allowing this in OptionTemplate, also SelectionOptionManager
  71  * needs to be updated.
  72  * \endif
  73  *
  74  * \inpublicapi
  75  * \ingroup module_selection
  76  */
  77 class SelectionOption : public OptionTemplate<Selection, SelectionOption>
  78 {
  79     public:
  80         //! OptionInfo subclass corresponding to this option type.
  81         typedef SelectionOptionInfo InfoType;
  82
  83         //! Initializes an option with the given name.
  84         explicit SelectionOption(const char *name)
  85             : MyBase(name), defaultText_(""),
  86               selectionFlags_(efSelection_DisallowEmpty)
  87         {
  88         }
  89
  90         /*! \brief
  91          * Request velocity evaluation for output positions.
  92          *
  93          * \see Selection::setEvaluateVelocities()
  94          */
  95         MyClass &evaluateVelocities()
  96         { selectionFlags_.set(efSelection_EvaluateVelocities); return me(); }
  97         /*! \brief
  98          * Request force evaluation for output positions.
  99          *
 100          * \see Selection::setEvaluateForces()
 101          */
 102         MyClass &evaluateForces()
 103         { selectionFlags_.set(efSelection_EvaluateForces); return me(); }
 104         /*! \brief
 105          * Only accept selections that evaluate to atom positions.
 106          */
 107         MyClass &onlyAtoms()
 108         { selectionFlags_.set(efSelection_OnlyAtoms); return me(); }
 109         /*! \brief
 110          * Only accept static selections for this option.
 111          */
 112         MyClass &onlyStatic()
 113         { selectionFlags_.set(efSelection_OnlyStatic); return me(); }
 114         /*! \brief
 115          * Handle dynamic selections for this option with position masks.
 116          *
 117          * \see Selection
 118          * \see SelectionPosition::selected()
 119          */
 120         MyClass &dynamicMask()
 121         { selectionFlags_.set(efSelection_DynamicMask); return me(); }
 122         /*! \brief
 123          * Allow specifying an unconditionally empty selection for this option.
 124          *
 125          * If this option is not set, selections that are unconditionally empty
 126          * (i.e., can never match any atoms) result in errors.
 127          * Note that even without this option, it is still possible that a
 128          * dynamic selection evaluates to zero atoms for some frames.
 129          */
 130         MyClass &allowEmpty()
 131         { selectionFlags_.clear(efSelection_DisallowEmpty); return me(); }
 132
 133         /*! \brief
 134          * Sets default selection text for the option.
 135          *
 136          * If the option is not set by the user, the provided text is parsed as
 137          * the value of the selection.
 138          */
 139         MyClass &defaultSelectionText(const char *text)
 140         { defaultText_ = text; return me(); }
 141
 142     private:
 143         // Disable possibility to allow multiple occurrences, since it isn't
 144         // implemented.
 145         using MyBase::allowMultiple;
 146         // Disable default value because it is impossible to provide a
 147         // Selection object.
 148         using MyBase::defaultValue;
 149         using MyBase::defaultValueIfSet;
 150
 151         virtual AbstractOptionStorage *createStorage(
 152             const OptionManagerContainer &managers) const;
 153
 154         const char             *defaultText_;
 155         SelectionFlags          selectionFlags_;
 156
 157         /*! \brief
 158          * Needed to initialize SelectionOptionStorage from this class without
 159          * otherwise unnecessary accessors.
 160          */
 161         friend class SelectionOptionStorage;
 162 };
 163
 164 /*! \brief
 165  * Wrapper class for accessing and modifying selection option information.
 166  *
 167  * Allows changes to a selection option after creation.
 168  *
 169  * This class provides the necessary interface for changing, e.g., the number
 170  * of allowed selections for a selection option after the option has been
 171  * created with Options::addOption().  This is needed if the number or other
 172  * flags are only known after other options have been parsed.  The main
 173  * advantage of this class over custom checks is that if used before
 174  * interactive selection prompt, the interactive prompt is updated accordingly.
 175  *
 176  * When using this class, the option should be initially created with the most
 177  * permissive flags, and this class should be used to place restrictions where
 178  * appropriate.  Otherwise, values that are provided before adjustments will
 179  * need to follow the more strict checks.  In most cases in trajectory analysis
 180  * (which is the main use case for selection options), the adjustments should
 181  * be done in TrajectoryAnalysisModule::initOptionsDone() for them to take
 182  * place before interactive selection prompts.
 183  *
 184  * An instance of this class for a selection option can be obtained with
 185  * SelectionOption::getAdjuster() when the option is created.
 186  *
 187  * Example use:
 188  * \code
 189    SelectionList sel;
 190    Options options("example", "Example options");
 191    SelectionOptionInfo *info;
 192    info = options.addOption(SelectionOption("sel").storeVector(&sel)
 193                                 .multiValue());
 194    // < ... assign values to options ...>
 195    if ( condition )
 196    {
 197        // Put limitations on the selections based on the condition,
 198        // which can depend on other option values.
 199        // Throws if input given so far violates the limitations.
 200        info->setValueCount(2);
 201        info->setOnlyStatic(true);
 202    }
 203  * \endcode
 204  *
 205  * \inpublicapi
 206  * \ingroup module_selection
 207  */
 208 class SelectionOptionInfo : public OptionInfo
 209 {
 210     public:
 211         /*! \brief
 212          * Creates option info object for given storage object.
 213          *
 214          * Does not throw.
 215          */
 216         explicit SelectionOptionInfo(SelectionOptionStorage *option);
 217
 218         /*! \brief
 219          * Sets the number of selections allowed for the option.
 220          *
 221          * \param[in] count  Number of allowed selections.
 222          * \throws    std::bad_alloc if out of memory.
 223          * \throws    InvalidInputError if values have already been provided
 224          *      and their count does not match.
 225          */
 226         void setValueCount(int count);
 227
 228         /*! \brief
 229          * Sets whether this option evaluates velocities for positions.
 230          *
 231          * \param[in] bEnabled  If true, velocities are evaluated.
 232          *
 233          * Does not throw.
 234          *
 235          * \see Selection::setEvaluateVelocities()
 236          */
 237         void setEvaluateVelocities(bool bEnabled);
 238         /*! \brief
 239          * Sets whether this option evaluates forces for positions.
 240          *
 241          * \param[in] bEnabled  If true, forces are evaluated.
 242          *
 243          * Does not throw.
 244          *
 245          * \see Selection::setEvaluateForces()
 246          */
 247         void setEvaluateForces(bool bEnabled);
 248         /*! \brief
 249          * Sets whether this option accepts positions that come from multiple
 250          * atoms.
 251          *
 252          * \param[in] bEnabled  If true, the option accepts only positions that
 253          *      evaluate to atom positions.
 254          *
 255          * \see SelectionOption::onlyAtoms()
 256          */
 257         void setOnlyAtoms(bool bEnabled);
 258         /*! \brief
 259          * Sets whether this option accepts dynamic selections.
 260          *
 261          * \param[in] bEnabled  If true, the option accepts only static
 262          *      selections.
 263          * \throws    std::bad_alloc if out of memory.
 264          * \throws    InvalidInputError if dynamic selections have already been
 265          *      provided.
 266          *
 267          * Strong exception safety guarantee.
 268          *
 269          * \see SelectionOption::onlyStatic()
 270          */
 271         void setOnlyStatic(bool bEnabled);
 272         /*! \brief
 273          * Sets whether this option uses position masks for dynamic selections.
 274          *
 275          * \param[in] bEnabled  If true, the position masks are used.
 276          *
 277          * Does not throw.
 278          *
 279          * \see SelectionOption::dynamicMask()
 280          */
 281         void setDynamicMask(bool bEnabled);
 282
 283     private:
 284         SelectionOptionStorage &option();
 285         const SelectionOptionStorage &option() const;
 286 };
 287
 288 } // namespace gmx
 289
 290 #endif