2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 2009,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::Selection and supporting classes.
39 * \author Teemu Murtola <teemu.murtola@gmail.com>
41 * \ingroup module_selection
43 #ifndef GMX_SELECTION_SELECTION_H
44 #define GMX_SELECTION_SELECTION_H
49 #include "gromacs/selection/position.h"
50 #include "gromacs/selection/selectionenums.h"
51 #include "gromacs/utility/arrayref.h"
52 #include "gromacs/utility/common.h"
53 #include "gromacs/utility/gmxassert.h"
60 class SelectionOptionStorage;
61 class SelectionTreeElement;
63 class AnalysisNeighborhoodPositions;
65 class SelectionPosition;
67 //! Container of selections used in public selection interfaces.
68 typedef std::vector<Selection> SelectionList;
75 * Internal data for a single selection.
77 * This class is internal to the selection module, but resides in a public
78 * header because of efficiency reasons: it allows frequently used access
79 * methods in \ref Selection to be inlined.
81 * Methods in this class do not throw unless otherwise specified.
83 * \ingroup module_selection
89 * Creates a new selection object.
91 * \param[in] elem Root of the evaluation tree for this selection.
92 * \param[in] selstr String that was parsed to produce this selection.
93 * \throws std::bad_alloc if out of memory.
95 SelectionData(SelectionTreeElement *elem, const char *selstr);
98 //! Returns the name for this selection.
99 const char *name() const { return name_.c_str(); }
100 //! Returns the string that was parsed to produce this selection.
101 const char *selectionText() const { return selectionText_.c_str(); }
102 //! Returns true if the size of the selection (posCount()) is dynamic.
103 bool isDynamic() const { return bDynamic_; }
104 //! Returns the type of positions in the selection.
105 e_index_t type() const { return rawPositions_.m.type; }
106 //! Returns true if the selection only contains positions with a single atom each.
107 bool hasOnlyAtoms() const { return type() == INDEX_ATOM; }
109 //! Number of positions in the selection.
110 int posCount() const { return rawPositions_.count(); }
111 //! Returns the root of the evaluation tree for this selection.
112 SelectionTreeElement &rootElement() { return rootElement_; }
114 //! Returns whether the covered fraction can change between frames.
115 bool isCoveredFractionDynamic() const { return bDynamicCoveredFraction_; }
117 //! Returns true if the given flag is set.
118 bool hasFlag(SelectionFlag flag) const { return flags_.test(flag); }
119 //! Sets the flags for this selection.
120 void setFlags(SelectionFlags flags) { flags_ = flags; }
122 //! \copydoc Selection::initCoveredFraction()
123 bool initCoveredFraction(e_coverfrac_t type);
126 * Updates the name of the selection if missing.
128 * \throws std::bad_alloc if out of memory.
130 * If selections get their value from a group reference that cannot be
131 * resolved during parsing, the name is final only after group
132 * references have been resolved.
134 * This function is called by SelectionCollection::setIndexGroups().
138 * Computes total masses and charges for all selection positions.
140 * \param[in] top Topology information.
141 * \throws std::bad_alloc if out of memory.
143 * For dynamic selections, the values need to be updated after each
144 * evaluation with refreshMassesAndCharges().
145 * This is done by SelectionEvaluator.
147 * This function is called by SelectionCompiler.
149 * Strong exception safety guarantee.
151 void initializeMassesAndCharges(const t_topology *top);
153 * Updates masses and charges after dynamic selection has been
156 * \param[in] top Topology information.
158 * Called by SelectionEvaluator.
160 void refreshMassesAndCharges(const t_topology *top);
162 * Updates the covered fraction after a selection has been evaluated.
164 * Called by SelectionEvaluator.
166 void updateCoveredFractionForFrame();
168 * Computes average covered fraction after all frames have been evaluated.
170 * \param[in] nframes Number of frames that have been evaluated.
172 * \p nframes should be equal to the number of calls to
173 * updateCoveredFractionForFrame().
174 * Called by SelectionEvaluator::evaluateFinal().
176 void computeAverageCoveredFraction(int nframes);
178 * Restores position information to state it was in after compilation.
180 * \param[in] top Topology information.
182 * Depends on SelectionCompiler storing the original atoms in the
183 * \a rootElement_ object.
184 * Called by SelectionEvaluator::evaluateFinal().
186 void restoreOriginalPositions(const t_topology *top);
189 //! Name of the selection.
191 //! The actual selection string.
192 std::string selectionText_;
193 //! Low-level representation of selected positions.
194 gmx_ana_pos_t rawPositions_;
195 //! Total masses for the current positions.
196 std::vector<real> posMass_;
197 //! Total charges for the current positions.
198 std::vector<real> posCharge_;
199 SelectionFlags flags_;
200 //! Root of the selection evaluation tree.
201 SelectionTreeElement &rootElement_;
202 //! Type of the covered fraction.
203 e_coverfrac_t coveredFractionType_;
204 //! Covered fraction of the selection for the current frame.
205 real coveredFraction_;
206 //! The average covered fraction (over the trajectory).
207 real averageCoveredFraction_;
208 //! true if the value can change as a function of time.
210 //! true if the covered fraction depends on the frame.
211 bool bDynamicCoveredFraction_;
214 * Needed to wrap access to information.
216 friend class gmx::Selection;
218 * Needed for proper access to position information.
220 friend class gmx::SelectionPosition;
222 GMX_DISALLOW_COPY_AND_ASSIGN(SelectionData);
225 } // namespace internal
228 * Provides access to a single selection.
230 * This class provides a public interface for accessing selection information.
231 * General information about the selection can be accessed with methods name(),
232 * selectionText(), isDynamic(), and type(). The first three can be accessed
233 * any time after the selection has been parsed, and type() can be accessed
234 * after the selection has been compiled.
236 * There are a few methods that can be used to change the behavior of the
237 * selection. setEvaluateVelocities() and setEvaluateForces() can be called
238 * before the selection is compiled to request evaluation of velocities and/or
239 * forces in addition to coordinates.
241 * Each selection is made of a set of positions. Each position has associated
242 * coordinates, and possibly velocities and forces if they have been requested
243 * and are available. It also has a set of atoms associated with it; typically
244 * the coordinates are the center-of-mass or center-of-geometry coordinates for
245 * that set of atoms. To access the number of positions in the selection, use
246 * posCount(). To access individual positions, use position().
247 * See SelectionPosition for details of how to use individual positions.
248 * setOriginalId() can be used to adjust the return value of
249 * SelectionPosition::mappedId(); see that method for details.
251 * It is also possible to access the list of atoms that make up all the
252 * positions directly: atomCount() returns the total number of atoms in the
253 * selection and atomIndices() an array of their indices.
254 * Similarly, it is possible to access the coordinates and other properties
255 * of the positions as continuous arrays through coordinates(), velocities(),
256 * forces(), masses(), charges(), refIds(), and mappedIds().
258 * Both positions and atoms can be accessed after the selection has been
259 * compiled. For dynamic selections, the return values of these methods change
260 * after each evaluation to reflect the situation for the current frame.
261 * Before any frame has been evaluated, these methods return the maximal set
262 * to which the selection can evaluate.
264 * There are two possible modes for how positions for dynamic selections are
265 * handled. In the default mode, posCount() can change, and for each frame,
266 * only the positions that are selected in that frame can be accessed. In a
267 * masked mode, posCount() remains constant, i.e., the positions are always
268 * evaluated for the maximal set, and SelectionPosition::selected() is used to
269 * determine whether a position is selected for a frame. The masked mode can
270 * be requested with SelectionOption::dynamicMask().
272 * The class also provides methods for printing out information: printInfo()
273 * and printDebugInfo(). These are mainly for internal use by Gromacs.
275 * This class works like a pointer type: copying and assignment is lightweight,
276 * and all copies work interchangeably, accessing the same internal data.
278 * Methods in this class do not throw.
280 * \see SelectionPosition
283 * \ingroup module_selection
289 * Creates a selection wrapper that has no associated selection.
291 * Any attempt to call methods in the object before a selection is
292 * assigned results in undefined behavior.
293 * isValid() returns `false` for the selection until it is initialized.
295 Selection() : sel_(NULL) {}
297 * Creates a new selection object.
299 * \param sel Selection data to wrap.
301 * Only for internal use by the selection module.
303 explicit Selection(internal::SelectionData *sel) : sel_(sel) {}
305 //! Returns whether the selection object is initialized.
306 bool isValid() const { return sel_ != NULL; }
308 //! Returns whether two selection objects wrap the same selection.
309 bool operator==(const Selection &other) const
311 return sel_ == other.sel_;
313 //! Returns whether two selection objects wrap different selections.
314 bool operator!=(const Selection &other) const
316 return !operator==(other);
319 //! Returns the name of the selection.
320 const char *name() const { return data().name(); }
321 //! Returns the string that was parsed to produce this selection.
322 const char *selectionText() const { return data().selectionText(); }
323 //! Returns true if the size of the selection (posCount()) is dynamic.
324 bool isDynamic() const { return data().isDynamic(); }
325 //! Returns the type of positions in the selection.
326 e_index_t type() const { return data().type(); }
327 //! Returns true if the selection only contains positions with a single atom each.
328 bool hasOnlyAtoms() const { return data().hasOnlyAtoms(); }
330 //! Total number of atoms in the selection.
331 int atomCount() const
333 return data().rawPositions_.m.mapb.nra;
335 //! Returns atom indices of all atoms in the selection.
336 ConstArrayRef<int> atomIndices() const
338 return constArrayRefFromArray(sel_->rawPositions_.m.mapb.a,
339 sel_->rawPositions_.m.mapb.nra);
341 //! Number of positions in the selection.
342 int posCount() const { return data().posCount(); }
343 //! Access a single position.
344 SelectionPosition position(int i) const;
345 //! Returns coordinates for this selection as a continuous array.
346 ConstArrayRef<rvec> coordinates() const
348 return constArrayRefFromArray(data().rawPositions_.x, posCount());
350 //! Returns whether velocities are available for this selection.
351 bool hasVelocities() const { return data().rawPositions_.v != NULL; }
353 * Returns velocities for this selection as a continuous array.
355 * Must not be called if hasVelocities() returns false.
357 ConstArrayRef<rvec> velocities() const
359 GMX_ASSERT(hasVelocities(), "Velocities accessed, but unavailable");
360 return constArrayRefFromArray(data().rawPositions_.v, posCount());
362 //! Returns whether forces are available for this selection.
363 bool hasForces() const { return sel_->rawPositions_.f != NULL; }
365 * Returns forces for this selection as a continuous array.
367 * Must not be called if hasForces() returns false.
369 ConstArrayRef<rvec> forces() const
371 GMX_ASSERT(hasForces(), "Forces accessed, but unavailable");
372 return constArrayRefFromArray(data().rawPositions_.f, posCount());
374 //! Returns masses for this selection as a continuous array.
375 ConstArrayRef<real> masses() const
377 // posMass_ may have more entries than posCount() in the case of
378 // dynamic selections that don't have a topology
379 // (and thus the masses and charges are fixed).
380 GMX_ASSERT(data().posMass_.size() >= static_cast<size_t>(posCount()),
381 "Internal inconsistency");
382 return constArrayRefFromVector<real>(data().posMass_.begin(),
383 data().posMass_.begin() + posCount());
385 //! Returns charges for this selection as a continuous array.
386 ConstArrayRef<real> charges() const
388 // posCharge_ may have more entries than posCount() in the case of
389 // dynamic selections that don't have a topology
390 // (and thus the masses and charges are fixed).
391 GMX_ASSERT(data().posCharge_.size() >= static_cast<size_t>(posCount()),
392 "Internal inconsistency");
393 return constArrayRefFromVector<real>(data().posCharge_.begin(),
394 data().posCharge_.begin() + posCount());
397 * Returns reference IDs for this selection as a continuous array.
399 * \see SelectionPosition::refId()
401 ConstArrayRef<int> refIds() const
403 return constArrayRefFromArray(data().rawPositions_.m.refid, posCount());
406 * Returns mapped IDs for this selection as a continuous array.
408 * \see SelectionPosition::mappedId()
410 ConstArrayRef<int> mappedIds() const
412 return constArrayRefFromArray(data().rawPositions_.m.mapid, posCount());
415 //! Returns whether the covered fraction can change between frames.
416 bool isCoveredFractionDynamic() const { return data().isCoveredFractionDynamic(); }
417 //! Returns the covered fraction for the current frame.
418 real coveredFraction() const { return data().coveredFraction_; }
421 * Allows passing a selection directly to neighborhood searching.
423 * When initialized this way, AnalysisNeighborhoodPair objects return
424 * indices that can be used to index the selection positions with
427 * Works exactly like if AnalysisNeighborhoodPositions had a
428 * constructor taking a Selection object as a parameter.
429 * See AnalysisNeighborhoodPositions for rationale and additional
432 operator AnalysisNeighborhoodPositions() const;
435 * Initializes information about covered fractions.
437 * \param[in] type Type of covered fraction required.
438 * \returns true if the covered fraction can be calculated for the
441 bool initCoveredFraction(e_coverfrac_t type)
443 return data().initCoveredFraction(type);
446 * Sets whether this selection evaluates velocities for positions.
448 * \param[in] bEnabled If true, velocities are evaluated.
450 * If you request the evaluation, but then evaluate the selection for
451 * a frame that does not contain velocity information, results are
455 * Implement it such that in the above case, hasVelocities() will
456 * return false for such frames.
460 void setEvaluateVelocities(bool bEnabled)
462 data().flags_.set(efSelection_EvaluateVelocities, bEnabled);
465 * Sets whether this selection evaluates forces for positions.
467 * \param[in] bEnabled If true, forces are evaluated.
469 * If you request the evaluation, but then evaluate the selection for
470 * a frame that does not contain force information, results are
475 void setEvaluateForces(bool bEnabled)
477 data().flags_.set(efSelection_EvaluateForces, bEnabled);
481 * Sets the ID for the \p i'th position for use with
482 * SelectionPosition::mappedId().
484 * \param[in] i Zero-based index
485 * \param[in] id Identifier to set.
487 * This method is not part of SelectionPosition because that interface
488 * only provides access to const data by design.
490 * This method can only be called after compilation, before the
491 * selection has been evaluated for any frame.
493 * \see SelectionPosition::mappedId()
495 void setOriginalId(int i, int id) { data().rawPositions_.m.orgid[i] = id; }
498 * Prints out one-line description of the selection.
500 * \param[in] fp Where to print the information.
502 * The output contains the name of the selection, the number of atoms
503 * and the number of positions, and indication of whether the selection
506 void printInfo(FILE *fp) const;
508 * Prints out extended information about the selection for debugging.
510 * \param[in] fp Where to print the information.
511 * \param[in] nmaxind Maximum number of values to print in lists
514 void printDebugInfo(FILE *fp, int nmaxind) const;
517 internal::SelectionData &data()
519 GMX_ASSERT(sel_ != NULL,
520 "Attempted to access uninitialized selection");
523 const internal::SelectionData &data() const
525 GMX_ASSERT(sel_ != NULL,
526 "Attempted to access uninitialized selection");
531 * Pointer to internal data for the selection.
533 * The memory for this object is managed by a SelectionCollection
534 * object, and the \ref Selection class simply provides a public
535 * interface for accessing the data.
537 internal::SelectionData *sel_;
540 * Needed to access the data to adjust flags.
542 friend class SelectionOptionStorage;
546 * Provides access to information about a single selected position.
548 * Each position has associated coordinates, and possibly velocities and forces
549 * if they have been requested and are available. It also has a set of atoms
550 * associated with it; typically the coordinates are the center-of-mass or
551 * center-of-geometry coordinates for that set of atoms. It is possible that
552 * there are not atoms associated if the selection has been provided as a fixed
555 * After the selection has been compiled, but not yet evaluated, the contents
556 * of the coordinate, velocity and force vectors are undefined.
558 * Default copy constructor and assignment operators are used, and work as
559 * intended: the copy references the same position and works identically.
561 * Methods in this class do not throw.
566 * \ingroup module_selection
568 class SelectionPosition
572 * Constructs a wrapper object for given selection position.
574 * \param[in] sel Selection from which the position is wrapped.
575 * \param[in] index Zero-based index of the position to wrap.
577 * Asserts if \p index is out of range.
579 * Only for internal use of the library. To obtain a SelectionPosition
580 * object in other code, use Selection::position().
582 SelectionPosition(const internal::SelectionData &sel, int index)
583 : sel_(&sel), i_(index)
585 GMX_ASSERT(index >= 0 && index < sel.posCount(),
586 "Invalid selection position index");
590 * Returns type of this position.
592 * Currently always returns the same as Selection::type().
594 e_index_t type() const { return sel_->type(); }
595 //! Returns coordinates for this position.
596 const rvec &x() const
598 return sel_->rawPositions_.x[i_];
601 * Returns velocity for this position.
603 * Must not be called if Selection::hasVelocities() returns false.
605 const rvec &v() const
607 GMX_ASSERT(sel_->rawPositions_.v != NULL,
608 "Velocities accessed, but unavailable");
609 return sel_->rawPositions_.v[i_];
612 * Returns force for this position.
614 * Must not be called if Selection::hasForces() returns false.
616 const rvec &f() const
618 GMX_ASSERT(sel_->rawPositions_.f != NULL,
619 "Velocities accessed, but unavailable");
620 return sel_->rawPositions_.f[i_];
623 * Returns total mass for this position.
625 * Returns the total mass of atoms that make up this position.
626 * If there are no atoms associated or masses are not available,
631 return sel_->posMass_[i_];
634 * Returns total charge for this position.
636 * Returns the sum of charges of atoms that make up this position.
637 * If there are no atoms associated or charges are not available,
642 return sel_->posCharge_[i_];
644 //! Returns the number of atoms that make up this position.
645 int atomCount() const
647 return sel_->rawPositions_.m.mapb.index[i_ + 1]
648 - sel_->rawPositions_.m.mapb.index[i_];
650 //! Return atom indices that make up this position.
651 ConstArrayRef<int> atomIndices() const
653 const int *atoms = sel_->rawPositions_.m.mapb.a;
656 return ConstArrayRef<int>();
658 const int first = sel_->rawPositions_.m.mapb.index[i_];
659 return constArrayRefFromArray(&atoms[first], atomCount());
662 * Returns whether this position is selected in the current frame.
664 * The return value is equivalent to \c refid() == -1. Returns always
665 * true if SelectionOption::dynamicMask() has not been set.
669 bool selected() const
674 * Returns reference ID for this position.
676 * For dynamic selections, this provides means to associate positions
677 * across frames. After compilation, these IDs are consequently
678 * numbered starting from zero. For each frame, the ID then reflects
679 * the location of the position in the original array of positions.
680 * If SelectionOption::dynamicMask() has been set for the parent
681 * selection, the IDs for positions not present in the current
682 * selection are set to -1, otherwise they are removed completely.
685 * If a dynamic selection consists of at most three positions, after
686 * compilation refId() will return 0, 1, 2 for them, respectively.
687 * If for a particular frame, only the first and the third are present,
688 * refId() will return 0, 2.
689 * If SelectionOption::dynamicMask() has been set, all three positions
690 * can be accessed also for that frame and refId() will return 0, -1,
695 return sel_->rawPositions_.m.refid[i_];
698 * Returns mapped ID for this position.
700 * Returns ID of the position that corresponds to that set with
701 * Selection::setOriginalId().
703 * If for an array \c id, \c setOriginalId(i, id[i]) has been called
704 * for each \c i, then it always holds that
705 * \c mappedId()==id[refId()].
707 * Selection::setOriginalId() has not been called, the default values
708 * are dependent on type():
709 * - ::INDEX_ATOM: atom indices
710 * - ::INDEX_RES: residue numbers
711 * - ::INDEX_MOL: molecule numbers
713 * All the default values are zero-based
717 return sel_->rawPositions_.m.mapid[i_];
721 * Allows passing a selection position directly to neighborhood searching.
723 * When initialized this way, AnalysisNeighborhoodPair objects return
724 * the index that can be used to access this position using
725 * Selection::position().
727 * Works exactly like if AnalysisNeighborhoodPositions had a
728 * constructor taking a SelectionPosition object as a parameter.
729 * See AnalysisNeighborhoodPositions for rationale and additional
732 operator AnalysisNeighborhoodPositions() const;
735 const internal::SelectionData *sel_;
740 inline SelectionPosition
741 Selection::position(int i) const
743 return SelectionPosition(data(), i);