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