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