#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 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...

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

sel	Selection 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] type Type 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]	top	Topology information (can be NULL if not required for `type`).
[in]	type	Type of groups to generate.

Returns: Number of groups that were present in the selection.

Exceptions

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.

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]	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.

Parameters

[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.

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] 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.

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

inline

Sets whether this selection evaluates velocities for positions.

Parameters

[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.

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]	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.

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:

api/legacy/include/gromacs/selection/selection.h
src/gromacs/selection/selection.cpp

Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation