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

#include <gromacs/selection/selectioncollection.h>

Description

Collection of selections.

This class is the main interface to the core of the selection engine. It is used to initialize and manage a collection of selections that share the same topology. Selections within one collection can share variables and can be optimized together. Selections from two different collections do not interact.

The constructor creates an empty selection collection object. To initialize the object, either call initOptions(), or both setReferencePosType() and setOutputPosType(). See these methods for more details on the initialization options.

SelectionCollections can be copied. Copies retain the same pointers to external indices (if set) and the topology (if set), and are compiled if the copied collection is compiled. Selection objects created from a given SelectionCollection are tied only to the original collection, so a copy of a SelectionCollection will not update pre-existing Selections on evaluate() calls.

After setting the default values, one or more selections can be parsed with one or more calls to parseInteractive(), parseFromStdin(), parseFromFile(), and/or parseFromString(). After all selections are parsed, the topology must be set with setTopology() unless requiresTopology() returns false (the topology can also be set earlier). setIndexGroups() must also be called if external index group references are used in the selections; it can be called at any point before compile(). Once all selections are parsed, they must be compiled all at once using compile().

After compilation, dynamic selections have the maximum number of atoms they can evaluate to, but positions have undefined values (see Selection and SelectionPosition). evaluate() can be used to update the selections for a new frame. evaluateFinal() can be called after all the frames have been processed to restore the selection values back to the ones they were after compile().

At any point, requiresTopology() can be called to see whether the information provided so far requires loading the topology. Similarly, requiresIndexGroups() tells whether external index groups are requires. printTree() can be used to print the internal representation of the selections (mostly useful for debugging).

Note that for trajectory analysis using TrajectoryAnalysisModule, the SelectionCollection object is managed by Gromacs, and Selection objects are obtained from SelectionOption.

Classes

class  Impl
 Private implemention class for SelectionCollection. More...
 

Public Types

enum  SelectionTypeOption { IncludeSelectionTypeOption, AlwaysAtomSelections }
 Flag for initOptions() to select how to behave with -seltype option. More...
 

Public Member Functions

 SelectionCollection ()
 Creates an empty selection collection. More...
 
 SelectionCollection (const SelectionCollection &rhs)
 
SelectionCollectionoperator= (SelectionCollection rhs)
 
void swap (SelectionCollection &rhs)
 
void initOptions (IOptionsContainer *options, SelectionTypeOption selectionTypeOption)
 Initializes options for setting global properties on the collection. More...
 
void setReferencePosType (const char *type)
 Sets the default reference position handling for a selection collection. More...
 
void setOutputPosType (const char *type)
 Sets the default reference position handling for a selection collection. More...
 
void setDebugLevel (int debugLevel)
 Sets the debugging level for the selection collection. More...
 
SelectionTopologyProperties requiredTopologyProperties () const
 Returns what topology information is required for evaluation. More...
 
bool requiresIndexGroups () const
 Returns true if the collection requires external index groups. More...
 
void setTopology (const gmx_mtop_t *top, int natoms)
 Sets the topology for the collection. More...
 
void setIndexGroups (gmx_ana_indexgrps_t *grps)
 Sets the external index groups to use for the selections. More...
 
SelectionList parseFromStdin (int count, bool bInteractive, const std::string &context)
 Parses selection(s) from standard input. More...
 
SelectionList parseInteractive (int count, TextInputStream *inputStream, TextOutputStream *outputStream, const std::string &context)
 Parses selection(s) interactively using provided streams. More...
 
SelectionList parseFromFile (const std::string &filename)
 Parses selection(s) from a file. More...
 
SelectionList parseFromString (const std::string &str)
 Parses selection(s) from a string. More...
 
void compile ()
 Prepares the selections for evaluation and performs optimizations. More...
 
void evaluate (t_trxframe *fr, t_pbc *pbc)
 Evaluates selections in the collection. More...
 
void evaluateFinal (int nframes)
 Evaluates the largest possible index groups from dynamic selections. More...
 
std::optional< Selectionselection (std::string_view selName) const
 Retrieves a Selection handle for the selection with the given name. More...
 
void printTree (FILE *fp, bool bValues) const
 Prints a human-readable version of the internal selection element tree. More...
 
void printXvgrInfo (FILE *fp) const
 Prints the selection strings into an XVGR file as comments. More...
 

Friends

class SelectionEvaluator
 
void compileSelection (SelectionCollection *coll)
 Implements selection compilation. More...
 

Member Enumeration Documentation

Flag for initOptions() to select how to behave with -seltype option.

Enumerator
IncludeSelectionTypeOption 

Add the option for the user to select default value for setOutputPosType().

AlwaysAtomSelections 

Do not add the option, selections will always select atoms by default.

Constructor & Destructor Documentation

gmx::SelectionCollection::SelectionCollection ( )

Creates an empty selection collection.

Exceptions
std::bad_allocif out of memory.

Member Function Documentation

void gmx::SelectionCollection::compile ( )

Prepares the selections for evaluation and performs optimizations.

Exceptions
InconsistentInputErrorif topology is required but not set.
InvalidInputErrorif setIndexGroups() has not been called and there are index group references.
unspecifiedif compilation fails (TODO: list/reduce these).

Before compilation, selections should have been added to the collection using the parseFrom*() functions. The compiled selection collection can be passed to evaluate() to evaluate the selection for a frame. Before the compiled selection is evaluated, the selections indicate the maximal set of atoms/positions to which they can be evaluated; see Selection.

If an error occurs, the collection is cleared.

The covered fraction information is initialized to CFRAC_NONE for all selections.

void gmx::SelectionCollection::evaluate ( t_trxframe *  fr,
t_pbc pbc 
)

Evaluates selections in the collection.

Parameters
[in]frFrame for which the evaluation should be carried out.
[in]pbcPBC data, or NULL if no PBC should be used.
Exceptions
unspeficiedMultiple possible exceptions to indicate evaluation failure (TODO: enumerate).
void gmx::SelectionCollection::evaluateFinal ( int  nframes)

Evaluates the largest possible index groups from dynamic selections.

Parameters
[in]nframesTotal number of frames.

This method restores the selections to the state they were after compile().

nframes should equal the number of times evaluate() has been called.

Does not throw.

void gmx::SelectionCollection::initOptions ( IOptionsContainer options,
SelectionTypeOption  selectionTypeOption 
)

Initializes options for setting global properties on the collection.

Parameters
[in,out]optionsOptions object to initialize.
[in]selectionTypeOptionWhether to add option to influence setOutputPosType().
Exceptions
std::bad_allocif out of memory.

Adds options to options that can be used to set the default position types (see setReferencePosType() and setOutputPosType()) and debugging flags.

SelectionList gmx::SelectionCollection::parseFromFile ( const std::string &  filename)

Parses selection(s) from a file.

Parameters
[in]filenameName of the file to parse selections from.
Returns
Vector of parsed selections.
Exceptions
std::bad_allocif out of memory.
InvalidInputErrorif there is a parsing error.

The returned objects remain valid for the lifetime of the selection collection. Some information about the selections only becomes available once compile() has been called; see Selection.

SelectionList gmx::SelectionCollection::parseFromStdin ( int  count,
bool  bInteractive,
const std::string &  context 
)

Parses selection(s) from standard input.

Parameters
[in]countNumber of selections to parse (if -1, parse as many as provided by the user).
[in]bInteractiveWhether the parser should behave interactively.
[in]contextContext to print for interactive input.
Returns
Vector of parsed selections.
Exceptions
std::bad_allocif out of memory.
InvalidInputErrorif there is a parsing error (an interactive parser only throws this if too few selections are provided and the user forced the end of input).

The returned objects remain valid for the lifetime of the selection collection. Some information about the selections only becomes available once compile() has been called; see Selection.

The string provided to context should be such that it can replace the three dots in "Specify selections ...:". It can be empty.

SelectionList gmx::SelectionCollection::parseFromString ( const std::string &  str)

Parses selection(s) from a string.

Parameters
[in]strString to parse selections from.
Returns
Vector of parsed selections.
Exceptions
std::bad_allocif out of memory.
InvalidInputErrorif there is a parsing error.

The returned objects remain valid for the lifetime of the selection collection. Some information about the selections only becomes available once compile() has been called; see Selection.

SelectionList gmx::SelectionCollection::parseInteractive ( int  count,
TextInputStream inputStream,
TextOutputStream outputStream,
const std::string &  context 
)

Parses selection(s) interactively using provided streams.

Parameters
[in]countNumber of selections to parse (if -1, parse as many as provided by the user).
[in]inputStreamStream to use for input.
[in]outputStreamStream to use for output (if NULL, the parser runs non-interactively and does not produce any status messages).
[in]contextContext to print for interactive input.
Returns
Vector of parsed selections.
Exceptions
std::bad_allocif out of memory.
InvalidInputErrorif there is a parsing error (an interactive parser only throws this if too few selections are provided and the user forced the end of input).

Works the same as parseFromStdin(), except that the caller can provide streams to use instead of stdin and stderr.

Mainly usable for unit testing interactive input.

void gmx::SelectionCollection::printTree ( FILE *  fp,
bool  bValues 
) const

Prints a human-readable version of the internal selection element tree.

Parameters
[in]fpFile handle to receive the output.
[in]bValuesIf true, the evaluated values of selection elements are printed as well.

The output is very techical, and intended for debugging purposes.

Does not throw.

void gmx::SelectionCollection::printXvgrInfo ( FILE *  fp) const

Prints the selection strings into an XVGR file as comments.

Parameters
[in]fpOutput file.

Does not throw.

SelectionTopologyProperties gmx::SelectionCollection::requiredTopologyProperties ( ) const

Returns what topology information is required for evaluation.

Returns
What topology information is required for compiling and/or evaluating the selections in the collection.

Before the parser functions have been called, the return value is based just on the position types set. After parser functions have been called, the return value also takes into account the selection keywords used. After the compiler has been called, the return value is final and also considers possible force evaluation requested for the selections.

Does not throw.

bool gmx::SelectionCollection::requiresIndexGroups ( ) const

Returns true if the collection requires external index groups.

Returns
true if any selection has an unresolved index group reference.

The return value is false after setIndexGroups() has been called.

Does not throw.

std::optional< Selection > gmx::SelectionCollection::selection ( std::string_view  selName) const

Retrieves a Selection handle for the selection with the given name.

Parameters
selNamename of the selection to return
Returns
The selection with the given name, or nullopt if no such selection exists.
void gmx::SelectionCollection::setDebugLevel ( int  debugLevel)

Sets the debugging level for the selection collection.

Parameters
[in]debugLevelDebug level to set (0 = no debug information).

initOptions() creates debugging options that can also be used to set the debug level. These are normally hidden, but if this method is called before initOptions() with a non-zero debugLevel, they are made visible.

Mostly useful for debugging tools.

Does not throw.

void gmx::SelectionCollection::setIndexGroups ( gmx_ana_indexgrps_t grps)

Sets the external index groups to use for the selections.

Parameters
[in]grpsIndex groups to use for the selections.
Exceptions
std::bad_allocif out of memory.
InconsistentInputErrorif a group reference cannot be resolved.

Only the first call to this method can have a non-NULL grps. At this point, any selections that have already been provided are searched for references to external groups, and the references are replaced by the contents of the groups. If any referenced group cannot be found in grps (or if grps is NULL and there are any references), InconsistentInputError is thrown.

The selection collection keeps a reference to grps until this method is called with a NULL grps. If this method is not called before compile(), it is automatically called as setIndexGroups(NULL).

void gmx::SelectionCollection::setOutputPosType ( const char *  type)

Sets the default reference position handling for a selection collection.

Parameters
[in]typeDefault selection output position type (one of the strings acceptable for PositionCalculationCollection::typeFromEnum()).
Exceptions
InternalErrorif type is invalid.

Should be called before calling the parser functions, unless initOptions() has been called. In the latter case, can still be used to override the default value (before initOptions() is called) and/or the value provided through the Options object.

Strong exception safety.

void gmx::SelectionCollection::setReferencePosType ( const char *  type)

Sets the default reference position handling for a selection collection.

Parameters
[in]typeDefault selection reference position type (one of the strings acceptable for PositionCalculationCollection::typeFromEnum()).
Exceptions
InternalErrorif type is invalid.

Should be called before calling the parser functions, unless initOptions() has been called. In the latter case, can still be used to override the default value (before initOptions() is called) and/or the value provided through the Options object.

Strong exception safety.

void gmx::SelectionCollection::setTopology ( const gmx_mtop_t *  top,
int  natoms 
)

Sets the topology for the collection.

Parameters
[in]topTopology data.
[in]natomsNumber of atoms. If <=0, the number of atoms in the topology is used.

Either the topology must be provided, or natoms must be > 0.

natoms determines the largest atom index that can be selected by the selection: even if the topology contains more atoms, they will not be selected.

Does not throw currently, but this is subject to change when more underlying code is converted to C++.

Friends And Related Function Documentation

void compileSelection ( SelectionCollection coll)
friend

Implements selection compilation.

This function is used to implement SelectionCollection::compile(). It prepares the selections in a selection collection for evaluation and performs some optimizations.

Before compilation, the selection collection should have been initialized with gmx_ana_selcollection_parse_*(). The compiled selection collection can be passed to gmx_ana_selcollection_evaluate() to evaluate the selection for a frame. If an error occurs, coll is cleared.

The covered fraction information in coll is initialized to CFRAC_NONE.

See Selection compilation.

Parameters
[in,out]collSelection collection to work on.

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