Gromacs
2024.3
|
#include <gromacs/selection/selection.h>
Provides access to a single selection.
This class provides a public interface for accessing selection information. General information about the selection can be accessed with methods name(), selectionText(), isDynamic(), and type(). The first three can be accessed any time after the selection has been parsed, and type() can be accessed after the selection has been compiled.
There are a few methods that can be used to change the behavior of the selection. setEvaluateVelocities() and setEvaluateForces() can be called before the selection is compiled to request evaluation of velocities and/or forces in addition to coordinates.
Each selection is made of a set of positions. Each position has associated coordinates, and possibly velocities and forces if they have been requested and are available. It also has a set of atoms associated with it; typically the coordinates are the center-of-mass or center-of-geometry coordinates for that set of atoms. To access the number of positions in the selection, use posCount(). To access individual positions, use position(). See SelectionPosition for details of how to use individual positions. setOriginalId() can be used to adjust the return value of SelectionPosition::mappedId(); see that method for details.
It is also possible to access the list of atoms that make up all the positions directly: atomCount() returns the total number of atoms in the selection and atomIndices() an array of their indices. Similarly, it is possible to access the coordinates and other properties of the positions as continuous arrays through coordinates(), velocities(), forces(), masses(), charges(), refIds(), and mappedIds().
Both positions and atoms can be accessed after the selection has been compiled. For dynamic selections, the return values of these methods change after each evaluation to reflect the situation for the current frame. Before any frame has been evaluated, these methods return the maximal set to which the selection can evaluate.
There are two possible modes for how positions for dynamic selections are handled. In the default mode, posCount() can change, and for each frame, only the positions that are selected in that frame can be accessed. In a masked mode, posCount() remains constant, i.e., the positions are always evaluated for the maximal set, and SelectionPosition::selected() is used to determine whether a position is selected for a frame. The masked mode can be requested with SelectionOption::dynamicMask().
The class also provides methods for printing out information: printInfo() and printDebugInfo(). These are mainly for internal use by Gromacs.
This class works like a pointer type: copying and assignment is lightweight, and all copies work interchangeably, accessing the same internal data.
Methods in this class do not throw.
Public Member Functions | |
Selection () | |
Creates a selection wrapper that has no associated selection. More... | |
Selection (internal::SelectionData *sel) | |
Creates a new selection object. More... | |
bool | isValid () const |
Returns whether the selection object is initialized. | |
bool | operator== (const Selection &other) const |
Returns whether two selection objects wrap the same selection. | |
bool | operator!= (const Selection &other) const |
Returns whether two selection objects wrap different selections. | |
const char * | name () const |
Returns the name of the selection. | |
const char * | selectionText () const |
Returns the string that was parsed to produce this selection. | |
bool | isDynamic () const |
Returns true if the size of the selection (posCount()) is dynamic. | |
e_index_t | type () const |
Returns the type of positions in the selection. | |
bool | hasOnlyAtoms () const |
Returns true if the selection only contains positions with a single atom each. | |
bool | hasSortedAtomIndices () const |
Returns true if the atom indices in the selection are in ascending order. | |
int | atomCount () const |
Total number of atoms in the selection. | |
ArrayRef< const int > | atomIndices () const |
Returns atom indices of all atoms in the selection. | |
int | posCount () const |
Number of positions in the selection. | |
SelectionPosition | position (int i) const |
Access a single position. | |
ArrayRef< const rvec > | coordinates () const |
Returns coordinates for this selection as a continuous array. | |
bool | hasVelocities () const |
Returns whether velocities are available for this selection. | |
ArrayRef< const rvec > | velocities () const |
Returns velocities for this selection as a continuous array. More... | |
bool | hasForces () const |
Returns whether forces are available for this selection. | |
ArrayRef< const rvec > | forces () const |
Returns forces for this selection as a continuous array. More... | |
ArrayRef< const real > | masses () const |
Returns masses for this selection as a continuous array. | |
ArrayRef< const real > | charges () const |
Returns charges for this selection as a continuous array. | |
ArrayRef< const int > | refIds () const |
Returns reference IDs for this selection as a continuous array. More... | |
ArrayRef< const int > | mappedIds () const |
Returns mapped IDs for this selection as a continuous array. More... | |
bool | isCoveredFractionDynamic () const |
Returns whether the covered fraction can change between frames. | |
real | coveredFraction () const |
Returns the covered fraction for the current frame. | |
operator AnalysisNeighborhoodPositions () const | |
Allows passing a selection directly to neighborhood searching. More... | |
bool | initCoveredFraction (e_coverfrac_t type) |
Initializes information about covered fractions. More... | |
void | setEvaluateVelocities (bool bEnabled) |
Sets whether this selection evaluates velocities for positions. More... | |
void | setEvaluateForces (bool bEnabled) |
Sets whether this selection evaluates forces for positions. More... | |
void | setOriginalId (int i, int id) |
Sets the ID for the i'th position for use with SelectionPosition::mappedId(). More... | |
int | initOriginalIdsToGroup (const gmx_mtop_t *top, e_index_t type) |
Inits the IDs for use with SelectionPosition::mappedId() for grouping. More... | |
void | printInfo (FILE *fp) const |
Prints out one-line description of the selection. More... | |
void | printDebugInfo (FILE *fp, int nmaxind) const |
Prints out extended information about the selection for debugging. More... | |
Friends | |
class | SelectionOptionStorage |
Needed to access the data to adjust flags. | |
|
inline |
|
inlineexplicit |
Creates a new selection object.
sel | Selection data to wrap. |
Only for internal use by the selection module.
Returns forces for this selection as a continuous array.
Must not be called if hasForces() returns false.
|
inline |
Initializes information about covered fractions.
[in] | type | Type of covered fraction required. |
int gmx::Selection::initOriginalIdsToGroup | ( | const gmx_mtop_t * | top, |
e_index_t | type | ||
) |
Inits the IDs for use with SelectionPosition::mappedId() for grouping.
[in] | top | Topology information (can be NULL if not required for type ). |
[in] | type | Type of groups to generate. |
InconsistentInputError | if the selection positions cannot be assigned to groups of the given type. |
If type == INDEX_ATOM
, the IDs are initialized to 0, 1, 2, ..., and the return value is the number of positions. If type == INDEX_ALL
, all the IDs are initialized to 0, and the return value is one. If type == INDEX_RES
or type == INDEX_MOL
, the first position will get ID 0, and all following positions that belong to the same residue/molecule will get the same ID. The first position that belongs to a different residue/molecule will get ID 1, and so on. If some position contains atoms from multiple residues/molecules, i.e., the mapping is ambiguous, an exception is thrown. The return value is the number of residues/molecules that are present in the selection positions.
This method is useful if the calling code needs to group the selection, e.g., for computing aggregate properties for each residue or molecule. It can then use this method to initialize the appropriate grouping, use the return value to allocate a sufficiently sized buffer to store the aggregated values, and then use SelectionPosition::mappedId() to identify the location where to aggregate to.
|
inline |
Returns mapped IDs for this selection as a continuous array.
gmx::Selection::operator AnalysisNeighborhoodPositions | ( | ) | const |
Allows passing a selection directly to neighborhood searching.
When initialized this way, AnalysisNeighborhoodPair objects return indices that can be used to index the selection positions with position().
Works exactly like if AnalysisNeighborhoodPositions had a constructor taking a Selection object as a parameter. See AnalysisNeighborhoodPositions for rationale and additional discussion.
void gmx::Selection::printDebugInfo | ( | FILE * | fp, |
int | nmaxind | ||
) | const |
Prints out extended information about the selection for debugging.
[in] | fp | Where to print the information. |
[in] | nmaxind | Maximum number of values to print in lists (-1 = print all). |
void gmx::Selection::printInfo | ( | FILE * | fp | ) | const |
Prints out one-line description of the selection.
[in] | fp | Where to print the information. |
The output contains the name of the selection, the number of atoms and the number of positions, and indication of whether the selection is dynamic.
|
inline |
Returns reference IDs for this selection as a continuous array.
|
inline |
Sets whether this selection evaluates forces for positions.
[in] | bEnabled | If true, forces are evaluated. |
If you request the evaluation, but then evaluate the selection for a frame that does not contain force information, results are undefined.
Does not throw.
|
inline |
Sets whether this selection evaluates velocities for positions.
[in] | bEnabled | If true, velocities are evaluated. |
If you request the evaluation, but then evaluate the selection for a frame that does not contain velocity information, results are undefined.
Does not throw.
void gmx::Selection::setOriginalId | ( | int | i, |
int | id | ||
) |
Sets the ID for the i'th
position for use with SelectionPosition::mappedId().
[in] | i | Zero-based index |
[in] | id | Identifier to set. |
This method is not part of SelectionPosition because that interface only provides access to const data by design.
This method can only be called after compilation, before the selection has been evaluated for any frame.
Returns velocities for this selection as a continuous array.
Must not be called if hasVelocities() returns false.