2 * This file is part of the GROMACS molecular simulation package.
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.
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.
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.
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.
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.
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.
37 * Declares gmx::SelectionCollection.
39 * \author Teemu Murtola <teemu.murtola@gmail.com>
41 * \ingroup module_selection
43 #ifndef GMX_SELECTION_SELECTIONCOLLECTION_H
44 #define GMX_SELECTION_SELECTIONCOLLECTION_H
51 #include "../legacyheaders/types/oenv.h"
53 #include "../onlinehelp/helptopicinterface.h"
54 #include "../utility/common.h"
55 #include "selection.h" // For gmx::SelectionList
57 struct gmx_ana_indexgrps_t;
66 class SelectionCompiler;
67 class SelectionEvaluator;
70 * Collection of selections.
72 * This class is the main interface to the core of the selection engine.
73 * It is used to initialize and manage a collection of selections that share
74 * the same topology. Selections within one collection can share variables and
75 * can be optimized together. Selections from two different collections do not
78 * The constructor creates an empty selection collection object. To initialize
79 * the object, either call initOptions(), or both setReferencePosType() and
80 * setOutputPosType(). See these methods for more details on the
81 * initialization options.
83 * After setting the default values, one or more selections can be parsed with
84 * one or more calls to parseFromStdin(), parseFromFile(), and/or
85 * parseFromString(). After all selections are parsed, the topology must be
86 * set with setTopology() unless requiresTopology() returns false (the topology
87 * can also be set earlier).
88 * setIndexGroups() must also be called if external index group references are
89 * used in the selections; it can be called at any point before compile().
90 * Once all selections are parsed, they must be compiled all at once using
93 * After compilation, dynamic selections have the maximum number of atoms they
94 * can evaluate to, but positions have undefined values (see \ref Selection and
95 * SelectionPosition). evaluate() can be used to update the selections for a
96 * new frame. evaluateFinal() can be called after all the frames have been
97 * processed to restore the selection values back to the ones they were after
100 * At any point, requiresTopology() can be called to see whether the
101 * information provided so far requires loading the topology.
102 * printTree() can be used to print the internal representation of the
103 * selections (mostly useful for debugging).
105 * Note that for trajectory analysis using TrajectoryAnalysisModule, the
106 * SelectionCollection object is managed by Gromacs, and \ref Selection objects
107 * are obtained from SelectionOption.
110 * \ingroup module_selection
112 class SelectionCollection
116 * Creates a help tree for selections.
118 * \throws std::bad_alloc if out of memory.
119 * \returns Root topic of the created selection tree.
121 static HelpTopicPointer createDefaultHelpTopic();
124 * Creates an empty selection collection.
126 * \throws std::bad_alloc if out of memory.
128 SelectionCollection();
129 ~SelectionCollection();
132 * Initializes options for setting global properties on the collection.
134 * \param[in,out] options Options object to initialize.
135 * \throws std::bad_alloc if out of memory.
137 * Adds options to \p options that can be used to set the default
138 * position types (see setReferencePosType() and setOutputPosType())
139 * and debugging flags.
141 void initOptions(Options *options);
144 * Sets the default reference position handling for a selection
147 * \param[in] type Default selection reference position type
148 * (one of the strings acceptable for
149 * PositionCalculationCollection::typeFromEnum()).
150 * \throws InternalError if \p type is invalid.
152 * Should be called before calling the parser functions, unless
153 * initOptions() has been called. In the latter case, can still be
154 * used to override the default value (before initOptions() is called)
155 * and/or the value provided through the Options object.
157 * Strong exception safety.
159 void setReferencePosType(const char *type);
161 * Sets the default reference position handling for a selection
164 * \param[in] type Default selection output position type
165 * (one of the strings acceptable for
166 * PositionCalculationCollection::typeFromEnum()).
167 * \throws InternalError if \p type is invalid.
169 * Should be called before calling the parser functions, unless
170 * initOptions() has been called. In the latter case, can still be
171 * used to override the default value (before initOptions() is called)
172 * and/or the value provided through the Options object.
174 * Strong exception safety.
176 void setOutputPosType(const char *type);
178 * Sets the debugging level for the selection collection.
180 * \param[in] debugLevel Debug level to set (0 = no debug
183 * initOptions() creates debugging options that can also be used to set
184 * the debug level. These are normally hidden, but if this method is
185 * called before initOptions() with a non-zero \p debugLevel, they are
188 * Mostly useful for debugging tools.
192 void setDebugLevel(int debugLevel);
195 * Returns true if the collection requires topology information for
198 * \returns true if any selection in the collection requires topology
201 * Before the parser functions have been called, the return value is
202 * based just on the position types set.
203 * After parser functions have been called, the return value also takes
204 * into account the selection keywords used.
208 bool requiresTopology() const;
210 * Sets the topology for the collection.
212 * \param[in] top Topology data.
213 * \param[in] natoms Number of atoms. If <=0, the number of
214 * atoms in the topology is used.
216 * Either the topology must be provided, or \p natoms must be > 0.
218 * \p natoms determines the largest atom index that can be selected by
219 * the selection: even if the topology contains more atoms, they will
222 * Does not throw currently, but this is subject to change when more
223 * underlying code is converted to C++.
225 void setTopology(t_topology *top, int natoms);
227 * Sets the external index groups to use for the selections.
229 * \param[in] grps Index groups to use for the selections.
230 * \throws std::bad_alloc if out of memory.
231 * \throws InconsistentInputError if a group reference cannot be resolved.
233 * Only the first call to this method can have a non-NULL \p grps.
234 * At this point, any selections that have already been provided are
235 * searched for references to external groups, and the references are
236 * replaced by the contents of the groups. If any referenced group
237 * cannot be found in \p grps (or if \p grps is NULL and there are any
238 * references), InconsistentInputError is thrown.
240 * The selection collection keeps a reference to \p grps until this
241 * method is called with a NULL \p grps.
242 * If this method is not called before compile(), it is automatically
243 * called as setIndexGroups(NULL).
245 void setIndexGroups(gmx_ana_indexgrps_t *grps);
247 * Parses selection(s) from standard input.
249 * \param[in] count Number of selections to parse
250 * (if -1, parse as many as provided by the user).
251 * \param[in] bInteractive Whether the parser should behave
253 * \param[in] context Context to print for interactive input.
254 * \returns Vector of parsed selections.
255 * \throws std::bad_alloc if out of memory.
256 * \throws InvalidInputError if there is a parsing error
257 * (an interactive parser only throws this if too few selections
258 * are provided and the user forced the end of input).
260 * The returned objects remain valid for the lifetime of
261 * the selection collection.
262 * Some information about the selections only becomes available once
263 * compile() has been called; see \ref Selection.
265 * The string provided to \p context should be such that it can replace
266 * the three dots in "Specify selections ...:". It can be empty.
268 SelectionList parseFromStdin(int count, bool bInteractive,
269 const std::string &context);
271 * Parses selection(s) from a file.
273 * \param[in] filename Name of the file to parse selections from.
274 * \returns Vector of parsed selections.
275 * \throws std::bad_alloc if out of memory.
276 * \throws InvalidInputError if there is a parsing error.
278 * The returned objects remain valid for the lifetime of
279 * the selection collection.
280 * Some information about the selections only becomes available once
281 * compile() has been called; see \ref Selection.
283 SelectionList parseFromFile(const std::string &filename);
285 * Parses selection(s) from a string.
287 * \param[in] str String to parse selections from.
288 * \returns Vector of parsed selections.
289 * \throws std::bad_alloc if out of memory.
290 * \throws InvalidInputError if there is a parsing error.
292 * The returned objects remain valid for the lifetime of
293 * the selection collection.
294 * Some information about the selections only becomes available once
295 * compile() has been called; see \ref Selection.
297 SelectionList parseFromString(const std::string &str);
299 * Prepares the selections for evaluation and performs optimizations.
301 * \throws InconsistentInputError if topology is required but not set.
302 * \throws InvalidInputError if setIndexGroups() has not been called
303 * and there are index group references.
304 * \throws unspecified if compilation fails (TODO: list/reduce these).
306 * Before compilation, selections should have been added to the
307 * collection using the parseFrom*() functions.
308 * The compiled selection collection can be passed to evaluate() to
309 * evaluate the selection for a frame.
310 * Before the compiled selection is evaluated, the selections indicate
311 * the maximal set of atoms/positions to which they can be evaluated;
312 * see \ref Selection.
314 * If an error occurs, the collection is cleared.
316 * The covered fraction information is initialized to ::CFRAC_NONE for
321 * Evaluates selections in the collection.
323 * \param[in] fr Frame for which the evaluation should be carried out.
324 * \param[in] pbc PBC data, or NULL if no PBC should be used.
325 * \throws unspeficied Multiple possible exceptions to indicate
326 * evaluation failure (TODO: enumerate).
328 void evaluate(t_trxframe *fr, t_pbc *pbc);
330 * Evaluates the largest possible index groups from dynamic selections.
332 * \param[in] nframes Total number of frames.
334 * This method restores the selections to the state they were after
337 * \p nframes should equal the number of times evaluate() has been
342 void evaluateFinal(int nframes);
345 * Prints a human-readable version of the internal selection element
348 * \param[in] fp File handle to receive the output.
349 * \param[in] bValues If true, the evaluated values of selection
350 * elements are printed as well.
352 * The output is very techical, and intended for debugging purposes.
356 void printTree(FILE *fp, bool bValues) const;
358 * Prints the selection strings into an XVGR file as comments.
360 * \param[in] fp Output file.
361 * \param[in] oenv Output options structure.
365 void printXvgrInfo(FILE *fp, output_env_t oenv) const;
370 PrivateImplPointer<Impl> impl_;
373 * Needed for the compiler to freely modify the collection.
375 friend class SelectionCompiler;
377 * Needed for the evaluator to freely modify the collection.
379 friend class SelectionEvaluator;