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