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