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