Merge branch 'release-4-6'
[alexxy/gromacs.git] / 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  * 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), selectionFlags_(efSelection_DisallowEmpty)
83         {
84         }
85
86         /*! \brief
87          * Request velocity evaluation for output positions.
88          *
89          * \see Selection::setEvaluateVelocities()
90          */
91         MyClass &evaluateVelocities()
92         { selectionFlags_.set(efSelection_EvaluateVelocities); return me(); }
93         /*! \brief
94          * Request force evaluation for output positions.
95          *
96          * \see Selection::setEvaluateForces()
97          */
98         MyClass &evaluateForces()
99         { selectionFlags_.set(efSelection_EvaluateForces); return me(); }
100         /*! \brief
101          * Only accept selections that evaluate to atom positions.
102          */
103         MyClass &onlyAtoms()
104         { selectionFlags_.set(efSelection_OnlyAtoms); return me(); }
105         /*! \brief
106          * Only accept static selections for this option.
107          */
108         MyClass &onlyStatic()
109         { selectionFlags_.set(efSelection_OnlyStatic); return me(); }
110         /*! \brief
111          * Handle dynamic selections for this option with position masks.
112          *
113          * \see Selection
114          * \see SelectionPosition::selected()
115          */
116         MyClass &dynamicMask()
117         { selectionFlags_.set(efSelection_DynamicMask); return me(); }
118         /*! \brief
119          * Allow specifying an unconditionally empty selection for this option.
120          *
121          * If this option is not set, selections that are unconditionally empty
122          * (i.e., can never match any atoms) result in errors.
123          * Note that even without this option, it is still possible that a
124          * dynamic selection evaluates to zero atoms for some frames.
125          */
126         MyClass &allowEmpty()
127         { selectionFlags_.clear(efSelection_DisallowEmpty); return me(); }
128
129     private:
130         // Disable possibility to allow multiple occurrences, since it isn't
131         // implemented.
132         using MyBase::allowMultiple;
133         // Disable default value because it is impossible to provide a
134         // Selection object.
135         using MyBase::defaultValue;
136         using MyBase::defaultValueIfSet;
137
138         virtual AbstractOptionStoragePointer createStorage() const;
139
140         SelectionFlags          selectionFlags_;
141
142         /*! \brief
143          * Needed to initialize SelectionOptionStorage from this class without
144          * otherwise unnecessary accessors.
145          */
146         friend class SelectionOptionStorage;
147 };
148
149 /*! \brief
150  * Wrapper class for accessing and modifying selection option information.
151  *
152  * Allows changes to a selection option after creation.
153  *
154  * This class provides the necessary interface for changing, e.g., the number
155  * of allowed selections for a selection option after the option has been
156  * created with Options::addOption().  This is needed if the number or other
157  * flags are only known after other options have been parsed.  The main
158  * advantage of this class over custom checks is that if used before
159  * interactive selection prompt, the interactive prompt is updated accordingly.
160  *
161  * When using this class, the option should be initially created with the most
162  * permissive flags, and this class should be used to place restrictions where
163  * appropriate.  Otherwise, values that are provided before adjustments will
164  * need to follow the more strict checks.  In most cases in trajectory analysis
165  * (which is the main use case for selection options), the adjustments should
166  * be done in TrajectoryAnalysisModule::initOptionsDone() for them to take
167  * place before interactive selection prompts.
168  *
169  * An instance of this class for a selection option can be obtained with
170  * SelectionOption::getAdjuster() when the option is created.
171  *
172  * Example use:
173  * \code
174    SelectionList sel;
175    Options options("example", "Example options");
176    SelectionOptionInfo *info;
177    info = options.addOption(SelectionOption("sel").storeVector(&sel)
178                                 .multiValue());
179    // < ... assign values to options ...>
180    if ( condition )
181    {
182        // Put limitations on the selections based on the condition,
183        // which can depend on other option values.
184        // Throws if input given so far violates the limitations.
185        info->setValueCount(2);
186        info->setOnlyStatic(true);
187    }
188  * \endcode
189  *
190  * \inpublicapi
191  * \ingroup module_selection
192  */
193 class SelectionOptionInfo : public OptionInfo
194 {
195     public:
196         /*! \brief
197          * Creates option info object for given storage object.
198          *
199          * Does not throw.
200          */
201         explicit SelectionOptionInfo(SelectionOptionStorage *option);
202
203         /*! \brief
204          * Set manager for handling interaction with other options and the
205          * selection collection.
206          *
207          * \param   manager  Selection manager to set.
208          *
209          * This must be called before the values are added.
210          *
211          * Typically it is called through setManagerForSelectionOptions(),
212          * which recursively sets the manager for all selection options in
213          * an Options object.
214          *
215          * Does not throw.
216          */
217         void setManager(SelectionOptionManager *manager);
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