3 * This source code is part of
7 * GROningen MAchine for Chemical Simulations
9 * Written by David van der Spoel, Erik Lindahl, Berk Hess, and others.
10 * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
11 * Copyright (c) 2001-2009, The GROMACS development team,
12 * check out http://www.gromacs.org for more information.
14 * This program is free software; you can redistribute it and/or
15 * modify it under the terms of the GNU General Public License
16 * as published by the Free Software Foundation; either version 2
17 * of the License, or (at your option) any later version.
19 * If you want to redistribute modifications, please consider that
20 * scientific software is very special. Version control is crucial -
21 * bugs must be traceable. We will be happy to consider code for
22 * inclusion in the official distribution, but derived work must not
23 * be called official GROMACS. Details are found in the README & COPYING
24 * files - if they are missing, get the official version at www.gromacs.org.
26 * To help us fund GROMACS development, we humbly ask that you cite
27 * the papers on the package - you can find them in the top README file.
29 * For more info, check our website at http://www.gromacs.org
33 * Declares gmx::SelectionCollection.
35 * \author Teemu Murtola <teemu.murtola@cbr.su.se>
37 * \ingroup module_selection
39 #ifndef GMX_SELECTION_SELECTIONCOLLECTION_H
40 #define GMX_SELECTION_SELECTIONCOLLECTION_H
45 #include "../legacyheaders/typedefs.h"
47 #include "../onlinehelp/helptopicinterface.h"
48 #include "../utility/common.h"
49 #include "selection.h" // For gmx::SelectionList
51 struct gmx_ana_indexgrps_t;
57 class SelectionCompiler;
58 class SelectionEvaluator;
61 * Collection of selections.
63 * This class is the main interface to the core of the selection engine.
64 * It is used to initialize and manage a collection of selections that share
65 * the same topology. Selections within one collection can share variables and
66 * can be optimized together. Selections from two different collections do not
69 * The constructor creates an empty selection collection object. To initialize
70 * the object, either call initOptions(), or both setReferencePosType() and
71 * setOutputPosType(). See these methods for more details on the
72 * initialization options.
74 * After setting the default values, one or more selections can be parsed with
75 * one or more calls to parseFromStdin(), parseFromFile(), and/or
76 * parseFromString(). After all selections are parsed, the topology must be
77 * set with setTopology() unless requiresTopology() returns false (the topology
78 * can also be set earlier).
79 * setIndexGroups() must also be called if external index group references are
80 * used in the selections; it can be called at any point before compile().
81 * Once all selections are parsed, they must be compiled all at once using
84 * After compilation, dynamic selections have the maximum number of atoms they
85 * can evaluate to, but positions have undefined values (see \ref Selection and
86 * SelectionPosition). evaluate() can be used to update the selections for a
87 * new frame. evaluateFinal() can be called after all the frames have been
88 * processed to restore the selection values back to the ones they were after
91 * At any point, requiresTopology() can be called to see whether the
92 * information provided so far requires loading the topology.
93 * printTree() can be used to print the internal representation of the
94 * selections (mostly useful for debugging).
96 * Note that for trajectory analysis using TrajectoryAnalysisModule, the
97 * SelectionCollection object is managed by Gromacs, and \ref Selection objects
98 * are obtained from SelectionOption.
101 * \ingroup module_selection
103 class SelectionCollection
107 * Creates a help tree for selections.
109 * \throws std::bad_alloc if out of memory.
110 * \returns Root topic of the created selection tree.
112 static HelpTopicPointer createDefaultHelpTopic();
115 * Creates an empty selection collection.
117 * \throws std::bad_alloc if out of memory.
119 SelectionCollection();
120 ~SelectionCollection();
123 * Initializes options for setting global properties on the collection.
125 * \param[in,out] options Options object to initialize.
126 * \throws std::bad_alloc if out of memory.
128 * Adds options to \p options that can be used to set the default
129 * position types (see setReferencePosType() and setOutputPosType())
130 * and debugging flags.
132 void initOptions(Options *options);
135 * Sets the default reference position handling for a selection
138 * \param[in] type Default selection reference position type
139 * (one of the strings acceptable for
140 * PositionCalculationCollection::typeFromEnum()).
141 * \throws InternalError if \p type is invalid.
143 * Should be called before calling the parser functions, unless
144 * initOptions() has been called. In the latter case, can still be
145 * used to override the default value (before initOptions() is called)
146 * and/or the value provided through the Options object.
148 * Strong exception safety.
150 void setReferencePosType(const char *type);
152 * Sets the default reference position handling for a selection
155 * \param[in] type Default selection output position type
156 * (one of the strings acceptable for
157 * PositionCalculationCollection::typeFromEnum()).
158 * \throws InternalError if \p type is invalid.
160 * Should be called before calling the parser functions, unless
161 * initOptions() has been called. In the latter case, can still be
162 * used to override the default value (before initOptions() is called)
163 * and/or the value provided through the Options object.
165 * Strong exception safety.
167 void setOutputPosType(const char *type);
169 * Sets the debugging level for the selection collection.
171 * \param[in] debugLevel Debug level to set (0 = no debug
174 * initOptions() creates debugging options that can also be used to set
175 * the debug level. These are normally hidden, but if this method is
176 * called before initOptions() with a non-zero \p debugLevel, they are
179 * Mostly useful for debugging tools.
183 void setDebugLevel(int debugLevel);
186 * Returns true if the collection requires topology information for
189 * \returns true if any selection in the collection requires topology
192 * Before the parser functions have been called, the return value is
193 * based just on the position types set.
194 * After parser functions have been called, the return value also takes
195 * into account the selection keywords used.
199 bool requiresTopology() const;
201 * Sets the topology for the collection.
203 * \param[in] top Topology data.
204 * \param[in] natoms Number of atoms. If <=0, the number of
205 * atoms in the topology is used.
207 * Either the topology must be provided, or \p natoms must be > 0.
209 * \p natoms determines the largest atom index that can be selected by
210 * the selection: even if the topology contains more atoms, they will
213 * Does not throw currently, but this is subject to change when more
214 * underlying code is converted to C++.
216 void setTopology(t_topology *top, int natoms);
218 * Sets the external index groups to use for the selections.
220 * \param[in] grps Index groups to use for the selections.
221 * \throws std::bad_alloc if out of memory.
222 * \throws InvalidInputError if a group reference cannot be resolved.
224 * Only the first call to this method can have a non-NULL \p grps.
225 * At this point, any selections that have already been provided are
226 * searched for references to external groups, and the references are
227 * replaced by the contents of the groups. If any referenced group
228 * cannot be found in \p grps (or if \p grps is NULL and there are any
229 * references), InvalidInputError is thrown.
231 * The selection collection keeps a reference to \p grps until this
232 * method is called with a NULL \p grps.
233 * If this method is not called before compile(), it is automatically
234 * called as setIndexGroups(NULL).
236 void setIndexGroups(gmx_ana_indexgrps_t *grps);
238 * Parses selection(s) from standard input.
240 * \param[in] count Number of selections to parse
241 * (if -1, parse as many as provided by the user).
242 * \param[in] bInteractive Whether the parser should behave
244 * \returns Vector of parsed selections.
245 * \throws std::bad_alloc if out of memory.
246 * \throws InvalidInputError if there is a parsing error
247 * (an interactive parser only throws this if too few selections
248 * are provided and the user forced the end of input).
250 * The returned objects remain valid for the lifetime of
251 * the selection collection.
252 * Some information about the selections only becomes available once
253 * compile() has been called; see \ref Selection.
255 SelectionList parseFromStdin(int count, bool bInteractive);
257 * Parses selection(s) from a file.
259 * \param[in] filename Name of the file to parse selections from.
260 * \returns Vector of parsed selections.
261 * \throws std::bad_alloc if out of memory.
262 * \throws InvalidInputError if there is a parsing error.
264 * The returned objects remain valid for the lifetime of
265 * the selection collection.
266 * Some information about the selections only becomes available once
267 * compile() has been called; see \ref Selection.
269 SelectionList parseFromFile(const std::string &filename);
271 * Parses selection(s) from a string.
273 * \param[in] str String 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 parseFromString(const std::string &str);
285 * Prepares the selections for evaluation and performs optimizations.
287 * \throws InconsistentInputError if topology is required but not set.
288 * \throws InvalidInputError if setIndexGroups() has not been called
289 * and there are index group references.
290 * \throws unspecified if compilation fails (TODO: list/reduce these).
292 * Before compilation, selections should have been added to the
293 * collection using the parseFrom*() functions.
294 * The compiled selection collection can be passed to evaluate() to
295 * evaluate the selection for a frame.
296 * Before the compiled selection is evaluated, the selections indicate
297 * the maximal set of atoms/positions to which they can be evaluated;
298 * see \ref Selection.
300 * If an error occurs, the collection is cleared.
302 * The covered fraction information is initialized to ::CFRAC_NONE for
307 * Evaluates selections in the collection.
309 * \param[in] fr Frame for which the evaluation should be carried out.
310 * \param[in] pbc PBC data, or NULL if no PBC should be used.
311 * \throws unspeficied Multiple possible exceptions to indicate
312 * evaluation failure (TODO: enumerate).
314 void evaluate(t_trxframe *fr, t_pbc *pbc);
316 * Evaluates the largest possible index groups from dynamic selections.
318 * \param[in] nframes Total number of frames.
320 * This method restores the selections to the state they were after
323 * \p nframes should equal the number of times evaluate() has been
328 void evaluateFinal(int nframes);
331 * Prints a human-readable version of the internal selection element
334 * \param[in] fp File handle to receive the output.
335 * \param[in] bValues If true, the evaluated values of selection
336 * elements are printed as well.
338 * The output is very techical, and intended for debugging purposes.
342 void printTree(FILE *fp, bool bValues) const;
344 * Prints the selection strings into an XVGR file as comments.
346 * \param[in] fp Output file.
347 * \param[in] oenv Output options structure.
351 void printXvgrInfo(FILE *fp, output_env_t oenv) const;
356 PrivateImplPointer<Impl> impl_;
359 * Needed for the compiler to freely modify the collection.
361 friend class SelectionCompiler;
363 * Needed for the evaluator to freely modify the collection.
365 friend class SelectionEvaluator;