Gromacs  2024.4
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
List of all members | Public Member Functions | Friends

#include <gromacs/selection/selection.h>

Description

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.

See Also
SelectionPosition
Examples:
template.cpp.

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 rveccoordinates () const
 Returns coordinates for this selection as a continuous array.
 
bool hasVelocities () const
 Returns whether velocities are available for this selection.
 
ArrayRef< const rvecvelocities () const
 Returns velocities for this selection as a continuous array. More...
 
bool hasForces () const
 Returns whether forces are available for this selection.
 
ArrayRef< const rvecforces () const
 Returns forces for this selection as a continuous array. More...
 
ArrayRef< const realmasses () const
 Returns masses for this selection as a continuous array.
 
ArrayRef< const realcharges () 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.
 

Constructor & Destructor Documentation

gmx::Selection::Selection ( )
inline

Creates a selection wrapper that has no associated selection.

Any attempt to call methods in the object before a selection is assigned results in undefined behavior. isValid() returns false for the selection until it is initialized.

gmx::Selection::Selection ( internal::SelectionData *  sel)
inlineexplicit

Creates a new selection object.

Parameters
selSelection data to wrap.

Only for internal use by the selection module.

Member Function Documentation

ArrayRef<const rvec> gmx::Selection::forces ( ) const
inline

Returns forces for this selection as a continuous array.

Must not be called if hasForces() returns false.

bool gmx::Selection::initCoveredFraction ( e_coverfrac_t  type)
inline

Initializes information about covered fractions.

Parameters
[in]typeType of covered fraction required.
Returns
true if the covered fraction can be calculated for the selection.
int gmx::Selection::initOriginalIdsToGroup ( const gmx_mtop_t *  top,
e_index_t  type 
)

Inits the IDs for use with SelectionPosition::mappedId() for grouping.

Parameters
[in]topTopology information (can be NULL if not required for type).
[in]typeType of groups to generate.
Returns
Number of groups that were present in the selection.
Exceptions
InconsistentInputErrorif 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.

See Also
setOriginalId()
SelectionPosition::mappedId()
ArrayRef<const int> gmx::Selection::mappedIds ( ) const
inline

Returns mapped IDs for this selection as a continuous array.

See Also
SelectionPosition::mappedId()
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.

Parameters
[in]fpWhere to print the information.
[in]nmaxindMaximum 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.

Parameters
[in]fpWhere 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.

ArrayRef<const int> gmx::Selection::refIds ( ) const
inline

Returns reference IDs for this selection as a continuous array.

See Also
SelectionPosition::refId()
void gmx::Selection::setEvaluateForces ( bool  bEnabled)
inline

Sets whether this selection evaluates forces for positions.

Parameters
[in]bEnabledIf 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.

void gmx::Selection::setEvaluateVelocities ( bool  bEnabled)
inline

Sets whether this selection evaluates velocities for positions.

Parameters
[in]bEnabledIf 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.

Todo:
Implement it such that in the above case, hasVelocities() will return false for such frames.

Does not throw.

void gmx::Selection::setOriginalId ( int  i,
int  id 
)

Sets the ID for the i'th position for use with SelectionPosition::mappedId().

Parameters
[in]iZero-based index
[in]idIdentifier 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.

See Also
SelectionPosition::mappedId()
ArrayRef<const rvec> gmx::Selection::velocities ( ) const
inline

Returns velocities for this selection as a continuous array.

Must not be called if hasVelocities() returns false.


The documentation for this class was generated from the following files: