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 "../utility/common.h"
48 #include "selection.h" // For gmx::SelectionList
50 struct gmx_ana_indexgrps_t;
56 class SelectionCompiler;
57 class SelectionEvaluator;
60 * Collection of selections.
62 * This class is the main interface to the core of the selection engine.
63 * It is used to initialize and manage a collection of selections that share
64 * the same topology. Selections within one collection can share variables and
65 * can be optimized together. Selections from two different collections do not
68 * The constructor creates an empty selection collection object. To initialize
69 * the object, either call initOptions(), or both setReferencePosType() and
70 * setOutputPosType(). See these methods for more details on the
71 * initialization options.
73 * After setting the default values, one or more selections can be parsed with
74 * one or more calls to parseFromStdin(), parseFromFile(), and/or
75 * parseFromString(). After all selections are parsed, the topology must be
76 * set with setTopology() unless requiresTopology() returns false (the topology
77 * can also be set earlier).
78 * setIndexGroups() must also be called if external index group references are
79 * used in the selections; it can be called at any point before compile().
80 * Once all selections are parsed, they must be compiled all at once using
83 * After compilation, dynamic selections have the maximum number of atoms they
84 * can evaluate to, but positions have undefined values (see \ref Selection and
85 * SelectionPosition). evaluate() can be used to update the selections for a
86 * new frame. evaluateFinal() can be called after all the frames have been
87 * processed to restore the selection values back to the ones they were after
90 * At any point, requiresTopology() can be called to see whether the
91 * information provided so far requires loading the topology.
92 * printTree() can be used to print the internal representation of the
93 * selections (mostly useful for debugging).
95 * Note that for trajectory analysis using TrajectoryAnalysisModule, the
96 * SelectionCollection object is managed by Gromacs, and \ref Selection objects
97 * are obtained from SelectionOption.
100 * \ingroup module_selection
102 class SelectionCollection
106 * Creates an empty selection collection.
108 * \throws std::bad_alloc if out of memory.
110 SelectionCollection();
111 ~SelectionCollection();
114 * Initializes options for setting global properties on the collection.
116 * \returns Initialized options object.
117 * \throws std::bad_alloc if out of memory.
119 * The returned options can be used to set the default position types
120 * (see setReferencePosType() and setOutputPosType()) and debugging
123 Options &initOptions();
126 * Sets the default reference position handling for a selection
129 * \param[in] type Default selection reference position type
130 * (one of the strings acceptable for
131 * PositionCalculationCollection::typeFromEnum()).
132 * \throws InternalError if \p type is invalid.
134 * Should be called before calling the parser functions, unless
135 * initOptions() has been called. In the latter case, can still be
136 * used to override the default value (before initOptions() is called)
137 * and/or the value provided through the Options object.
139 * Strong exception safety.
141 void setReferencePosType(const char *type);
143 * Sets the default reference position handling for a selection
146 * \param[in] type Default selection output position type
147 * (one of the strings acceptable for
148 * PositionCalculationCollection::typeFromEnum()).
149 * \throws InternalError if \p type is invalid.
151 * Should be called before calling the parser functions, unless
152 * initOptions() has been called. In the latter case, can still be
153 * used to override the default value (before initOptions() is called)
154 * and/or the value provided through the Options object.
156 * Strong exception safety.
158 void setOutputPosType(const char *type);
160 * Sets the debugging level for the selection collection.
162 * \param[in] debugLevel Debug level to set (0 = no debug
165 * initOptions() creates debugging options that can also be used to set
166 * the debug level. These are normally hidden, but if this method is
167 * called before initOptions() with a non-zero \p debugLevel, they are
170 * Mostly useful for debugging tools.
174 void setDebugLevel(int debugLevel);
177 * Returns true if the collection requires topology information for
180 * \returns true if any selection in the collection requires topology
183 * Before the parser functions have been called, the return value is
184 * based just on the position types set.
185 * After parser functions have been called, the return value also takes
186 * into account the selection keywords used.
190 bool requiresTopology() const;
192 * Sets the topology for the collection.
194 * \param[in] top Topology data.
195 * \param[in] natoms Number of atoms. If <=0, the number of
196 * atoms in the topology is used.
198 * Either the topology must be provided, or \p natoms must be > 0.
200 * \p natoms determines the largest atom index that can be selected by
201 * the selection: even if the topology contains more atoms, they will
204 * Does not throw currently, but this is subject to change when more
205 * underlying code is converted to C++.
207 void setTopology(t_topology *top, int natoms);
209 * Sets the external index groups to use for the selections.
211 * \param[in] grps Index groups to use for the selections.
212 * \throws std::bad_alloc if out of memory.
213 * \throws InvalidInputError if a group reference cannot be resolved.
215 * Only the first call to this method can have a non-NULL \p grps.
216 * At this point, any selections that have already been provided are
217 * searched for references to external groups, and the references are
218 * replaced by the contents of the groups. If any referenced group
219 * cannot be found in \p grps (or if \p grps is NULL and there are any
220 * references), InvalidInputError is thrown.
222 * The selection collection keeps a reference to \p grps until this
223 * method is called with a NULL \p grps.
224 * If this method is not called before compile(), it is automatically
225 * called as setIndexGroups(NULL).
227 void setIndexGroups(gmx_ana_indexgrps_t *grps);
229 * Parses selection(s) from standard input.
231 * \param[in] count Number of selections to parse
232 * (if -1, parse as many as provided by the user).
233 * \param[in] bInteractive Whether the parser should behave
235 * \returns Vector of parsed selections.
236 * \throws std::bad_alloc if out of memory.
237 * \throws InvalidInputError if there is a parsing error
238 * (an interactive parser only throws this if too few selections
239 * are provided and the user forced the end of input).
241 * The returned objects remain valid for the lifetime of
242 * the selection collection.
243 * Some information about the selections only becomes available once
244 * compile() has been called; see \ref Selection.
246 SelectionList parseFromStdin(int count, bool bInteractive);
248 * Parses selection(s) from a file.
250 * \param[in] filename Name of the file to parse selections from.
251 * \returns Vector of parsed selections.
252 * \throws std::bad_alloc if out of memory.
253 * \throws InvalidInputError if there is a parsing error.
255 * The returned objects remain valid for the lifetime of
256 * the selection collection.
257 * Some information about the selections only becomes available once
258 * compile() has been called; see \ref Selection.
260 SelectionList parseFromFile(const std::string &filename);
262 * Parses selection(s) from a string.
264 * \param[in] str String to parse selections from.
265 * \returns Vector of parsed selections.
266 * \throws std::bad_alloc if out of memory.
267 * \throws InvalidInputError if there is a parsing error.
269 * The returned objects remain valid for the lifetime of
270 * the selection collection.
271 * Some information about the selections only becomes available once
272 * compile() has been called; see \ref Selection.
274 SelectionList parseFromString(const std::string &str);
276 * Prepares the selections for evaluation and performs optimizations.
278 * \throws InconsistentInputError if topology is required but not set.
279 * \throws InvalidInputError if setIndexGroups() has not been called
280 * and there are index group references.
281 * \throws unspecified if compilation fails (TODO: list/reduce these).
283 * Before compilation, selections should have been added to the
284 * collection using the parseFrom*() functions.
285 * The compiled selection collection can be passed to evaluate() to
286 * evaluate the selection for a frame.
287 * Before the compiled selection is evaluated, the selections indicate
288 * the maximal set of atoms/positions to which they can be evaluated;
289 * see \ref Selection.
291 * If an error occurs, the collection is cleared.
293 * The covered fraction information is initialized to ::CFRAC_NONE for
298 * Evaluates selections in the collection.
300 * \param[in] fr Frame for which the evaluation should be carried out.
301 * \param[in] pbc PBC data, or NULL if no PBC should be used.
302 * \throws unspeficied Multiple possible exceptions to indicate
303 * evaluation failure (TODO: enumerate).
305 void evaluate(t_trxframe *fr, t_pbc *pbc);
307 * Evaluates the largest possible index groups from dynamic selections.
309 * \param[in] nframes Total number of frames.
311 * This method restores the selections to the state they were after
314 * \p nframes should equal the number of times evaluate() has been
319 void evaluateFinal(int nframes);
322 * Prints a human-readable version of the internal selection element
325 * \param[in] fp File handle to receive the output.
326 * \param[in] bValues If true, the evaluated values of selection
327 * elements are printed as well.
329 * The output is very techical, and intended for debugging purposes.
333 void printTree(FILE *fp, bool bValues) const;
335 * Prints the selection strings into an XVGR file as comments.
337 * \param[in] fp Output file.
338 * \param[in] oenv Output options structure.
342 void printXvgrInfo(FILE *fp, output_env_t oenv) const;
347 PrivateImplPointer<Impl> _impl;
350 * Needed for the compiler to freely modify the collection.
352 friend class SelectionCompiler;
354 * Needed for the evaluator to freely modify the collection.
356 friend class SelectionEvaluator;