Gromacs  2022.2
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Classes | Typedefs | Enumerations | Functions | Directories | Files
Parsing and Evaluation of Analysis Selections (selection)
+ Collaboration diagram for Parsing and Evaluation of Analysis Selections (selection):

Description

Provides functionality for initializing and evaluating selections.

The core of the selection engine is accessed through gmx::SelectionCollection, which manages a set of selections. Documentation for that class explains the general selection mechanisms.

For each selection that is parsed using a gmx::SelectionCollection, a gmx::Selection handle is returned and can be used to access information about that selection. gmx::SelectionPosition is a helper class used to access information about individual positions in a selection. These classes refer to internal state within the gmx::SelectionCollection, and their contents update automatically when the gmx::SelectionCollection is compiled or evaluated.

This module also provides gmx::SelectionOption and gmx::SelectionOptionInfo classes for declaring options that evaluate to selections (see Extensible Handling of Options (options) for general explanation of the options mechanism). These classes provide the main interface to obtain gmx::Selection objects in trajectory analysis using gmx::TrajectoryAnalysisModule. To use these classes outside the trajectory analysis framework, a gmx::SelectionOptionManager or a gmx::SelectionOptionBehavior needs to be created to serve as a bridge between the selection option classes and the gmx::SelectionCollection object. gmx::SelectionFileOption can be used to implement generic file input for selection options (done internally within gmx::SelectionOptionBehavior).

The selection module contains some lower-level functionality that is currently internal to it (centerofmass.h, indexutil.h, poscalc.h, position.h), but could possibly be useful also outside the module. It should be considered whether they should be moved somewhere else.

Author
Teemu Murtola teemu.nosp@m..mur.nosp@m.tola@.nosp@m.gmai.nosp@m.l.com

Classes

class  gmx::FileNameOptionManager
 Handles interaction of file name options with global options. More...
 
class  anonymous_namespace{evaluate.cpp}::MempoolSelelemReserver
 Reserves memory for a selection element from the evaluation memory pool. More...
 
class  anonymous_namespace{evaluate.cpp}::MempoolGroupReserver
 Reserves memory for an index group from the evaluation memory pool. More...
 
class  anonymous_namespace{evaluate.cpp}::SelelemTemporaryValueAssigner
 Assigns a temporary value for a selection element. More...
 
class  gmx::AnalysisNeighborhoodPositions
 Input positions for neighborhood searching. More...
 
class  gmx::AnalysisNeighborhood
 Neighborhood searching for analysis tools. More...
 
class  gmx::AnalysisNeighborhoodPair
 Value type to represent a pair of positions found in neighborhood searching. More...
 
class  gmx::AnalysisNeighborhoodSearch
 Initialized neighborhood search with a fixed set of reference positions. More...
 
class  gmx::AnalysisNeighborhoodPairSearch
 Initialized neighborhood pair search with a fixed set of positions. More...
 
class  gmx::SelectionParserValue
 Describes a parsed value, possibly resulting from expression evaluation. More...
 
class  gmx::SelectionParserParameter
 Describes a parsed method parameter. More...
 
class  gmx::PositionCalculationCollection::Impl
 Private implementation class for PositionCalculationCollection. More...
 
class  gmx::PositionCalculationCollection
 Collection of gmx_ana_poscalc_t structures for the same topology. More...
 
class  gmx::internal::SelectionData
 Internal data for a single selection. More...
 
class  gmx::Selection
 Provides access to a single selection. More...
 
class  gmx::SelectionPosition
 Provides access to information about a single selected position. More...
 
class  gmx::SelectionCollection
 Collection of selections. More...
 
struct  gmx_ana_selcollection_t
 Information for a collection of selections. More...
 
class  gmx::SelectionEvaluator
 Implements selection evaluation. More...
 
struct  gmx::SelectionTopologyProperties
 Describes topology properties required for selection evaluation. More...
 
class  gmx::SelectionFileOption
 Specifies a special option that provides selections from a file. More...
 
class  gmx::SelectionFileOptionInfo
 Wrapper class for accessing and modifying selection file option information. More...
 
class  gmx::SelectionFileOptionStorage
 Implementation for a special option for reading selections from files. More...
 
class  gmx::SelectionOption
 Specifies an option that provides selection(s). More...
 
class  gmx::SelectionOptionInfo
 Wrapper class for accessing and modifying selection option information. More...
 
class  gmx::ITopologyProvider
 Provides topology information to SelectionOptionBehavior. More...
 
class  gmx::SelectionOptionBehavior
 Options behavior to allow using SelectionOptions. More...
 
class  gmx::SelectionOptionManager
 Handles interaction of selection options with other options and user input. More...
 
class  gmx::SelectionOptionStorage
 Converts, validates, and stores selection values. More...
 
class  gmx::anonymous_namespace{selhelp.cpp}::KeywordDetailsHelpTopic
 Help topic implementation for an individual selection method. More...
 
class  gmx::anonymous_namespace{selhelp.cpp}::KeywordsHelpTopic
 Custom help topic for printing a list of selection keywords. More...
 
struct  gmx::SelMethodEvalContext
 Evaluation context for selection methods. More...
 
struct  t_methoddata_distance
 Data structure for distance-based selection method. More...
 
struct  t_partition_item
 Internal data structure for the insolidangle selection method. More...
 
struct  partition
 Internal data structure for the insolidangle selection method. More...
 
struct  spheresurfacebin
 Internal data structure for the insolidangle selection method. More...
 
struct  methoddata_insolidangle
 Data structure for the insolidangle selection method. More...
 
class  anonymous_namespace{sm_keywords.cpp}::StringKeywordMatchItem
 Single item in the list of strings/regular expressions to match. More...
 
struct  t_methoddata_same
 Data structure for the same selection method. More...
 
class  gmx::SelectionParserSymbol
 Single symbol for the selection parser. More...
 
class  gmx::SelectionParserSymbolIterator
 Forward iterator for iterating symbols of a given type. More...
 
class  gmx::SelectionParserSymbolTable
 Symbol table for the selection parser. More...
 

Typedefs

typedef struct partition t_partition
 Internal data structure for the insolidangle selection method. More...
 
typedef struct spheresurfacebin t_spheresurfacebin
 Internal data structure for the insolidangle selection method. More...
 
typedef struct
methoddata_insolidangle 
t_methoddata_insolidangle
 Data structure for the insolidangle selection method. More...
 

Enumerations

enum  gmx::SelectionStringMatchType { gmx::eStringMatchType_Auto, gmx::eStringMatchType_Exact, gmx::eStringMatchType_Wildcard, gmx::eStringMatchType_RegularExpression }
 String matching mode for string keyword expressions. More...
 

Functions

void gmx::compileSelection (SelectionCollection *coll)
 Implements selection compilation. More...
 
static bool next_group_index (int atomIndex, const gmx_mtop_t *top, e_index_t type, int *id)
 Helper for splitting a sequence of atom indices into groups. More...
 
HelpTopicPointer gmx::createSelectionHelpTopic ()
 */ More...
 

Directories

directory selection
 Parsing and Evaluation of Analysis Selections (selection)
 
directory tests
 Unit tests for Parsing and Evaluation of Analysis Selections (selection).
 

Files

file  centerofmass.cpp
 Implements functions in centerofmass.h.
 
file  centerofmass.h
 API for calculation of centers of mass/geometry.
 
file  compiler.cpp
 Selection compilation and optimization.
 
file  compiler.h
 Declares gmx::SelectionCompiler.
 
file  evaluate.cpp
 Implements functions in evaluate.h.
 
file  evaluate.h
 Evaluation functions for sel_evalfunc().
 
file  indexutil.cpp
 Implements functions in indexutil.h.
 
file  indexutil.h
 API for handling index files and index groups.
 
file  keywords.h
 Definitions of generic keyword evaluation structures.
 
file  mempool.cpp
 Implements functions in mempool.h.
 
file  mempool.h
 Declarations for memory pooling functions.
 
file  nbsearch.cpp
 Implements neighborhood searching for analysis (from nbsearch.h).
 
file  nbsearch.h
 API for neighborhood searching for analysis.
 
file  params.cpp
 Implements functions in selparam.h.
 
file  parser_internal.h
 Helper functions for the selection parser.
 
file  parsetree.cpp
 Implements functions in parsetree.h.
 
file  parsetree.h
 Handling of intermediate selection parser data.
 
file  poscalc.cpp
 Implements gmx::PositionCalculationCollection and functions in poscalc.h.
 
file  poscalc.h
 API for structured and optimized calculation of positions.
 
file  position.cpp
 Implements functions in position.h.
 
file  position.h
 API for handling positions.
 
file  scanner.h
 Parser/scanner interaction functions.
 
file  scanner_internal.cpp
 Helper functions for the selection tokenizer.
 
file  scanner_internal.h
 Internal header file used by the selection tokenizer.
 
file  selection.cpp
 Implements classes in selection.h.
 
file  selection.h
 Declares gmx::Selection and supporting classes.
 
file  selectioncollection.cpp
 Implements gmx::SelectionCollection.
 
file  selectioncollection.h
 Declares gmx::SelectionCollection.
 
file  selectioncollection_impl.h
 Declares private implementation class for gmx::SelectionCollection.
 
file  selectionenums.h
 Declares common types used in selections.
 
file  selectionfileoption.h
 Declares gmx::SelectionFileOption and gmx::SelectionFileOptionInfo.
 
file  selectionfileoptionstorage.h
 Declares gmx::SelectionFileOptionStorage.
 
file  selectionoption.cpp
 Implements classes in selectionoption.h and selectionoptionstorage.h.
 
file  selectionoption.h
 Declares gmx::SelectionOption and gmx::SelectionOptionInfo.
 
file  selectionoptionbehavior.cpp
 Implements gmx::SelectionOptionBehavior.
 
file  selectionoptionbehavior.h
 Declares gmx::SelectionOptionBehavior.
 
file  selectionoptionmanager.cpp
 Implements gmx::SelectionOptionManager.
 
file  selectionoptionmanager.h
 Declares gmx::SelectionOptionManager.
 
file  selectionoptionstorage.h
 Declares gmx::SelectionOptionStorage.
 
file  selelem.cpp
 Implements functions in selelem.h.
 
file  selelem.h
 Declares gmx::SelectionTreeElement and related things.
 
file  selhelp.cpp
 Implements functions in selhelp.h.
 
file  selhelp.h
 Functions for initializing online help for selections.
 
file  selmethod.cpp
 Implements functions in selmethod.h.
 
file  selmethod.h
 API for handling selection methods.
 
file  selparam.h
 API for handling parameters used in selections.
 
file  selvalue.cpp
 Implements functions in selvalue.h.
 
file  selvalue.h
 Declares gmx_ana_selvalue_t.
 
file  sm_compare.cpp
 Implements internal selection method for comparison expressions.
 
file  sm_distance.cpp
 Implements distance-based selection methods.
 
file  sm_insolidangle.cpp
 Implements the insolidangle selection method.
 
file  sm_keywords.cpp
 Implements internal selection methods for numeric and string keyword evaluation.
 
file  sm_merge.cpp
 Implements the merge and plus selection modifiers.
 
file  sm_permute.cpp
 Implements the permute selection modifier.
 
file  sm_position.cpp
 Implements position evaluation selection methods.
 
file  sm_same.cpp
 Implements the same selection method.
 
file  sm_simple.cpp
 Implements simple keyword selection methods.
 
file  symrec.cpp
 Implements classes in symrec.h.
 
file  symrec.h
 Handling of selection parser symbol table.
 
file  indexutil.cpp
 Tests the index group handling in the selection engine.
 
file  nbsearch.cpp
 Tests selection neighborhood searching.
 
file  poscalc.cpp
 Tests the position mapping engine.
 
file  selectioncollection.cpp
 Tests selection parsing and compilation.
 
file  selectionoption.cpp
 Tests handling of selection options.
 
file  toputils.cpp
 Implements test helper routines from toputils.h.
 
file  toputils.h
 Helper routines for constructing topologies for tests.
 
file  selection.h
 Public API convenience header for selection handling.
 

Typedef Documentation

Data structure for the insolidangle selection method.

All angle values are in the units of radians.

typedef struct partition t_partition

Internal data structure for the insolidangle selection method.

Describes the surface partitioning within one slice along the zenith angle. The slice from azimuthal angle p[i].left to p[i+1].left belongs to bin p[i].bin.

Internal data structure for the insolidangle selection method.

Contains the reference points that partially cover a certain region on the surface of the unit sphere. If n is -1, the whole region described by the bin is covered.

Enumeration Type Documentation

String matching mode for string keyword expressions.

Enumerator
eStringMatchType_Auto 

Deduce from the string.

eStringMatchType_Exact 

Match as a literal string.

eStringMatchType_Wildcard 

Match using ? and * as wildcards.

eStringMatchType_RegularExpression 

Match using regular expressions.

Function Documentation

void gmx::compileSelection ( SelectionCollection *  coll)

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.
HelpTopicPointer gmx::createSelectionHelpTopic ( )

*/

Creates a help tree for selections.

Exceptions
std::bad_allocif out of memory.
Returns
Root topic of the created selection tree.
static bool next_group_index ( int  atomIndex,
const gmx_mtop_t *  top,
e_index_t  type,
int *  id 
)
static

Helper for splitting a sequence of atom indices into groups.

Parameters
[in]atomIndexIndex of the next atom in the sequence.
[in]topTopology structure.
[in]typeType of group to split into.
[in,out]idVariable to receive the next group id.
Returns
true if atomIndex starts a new group in the sequence, i.e., if *id was changed.

*id should be initialized to -1 before first call of this function, and then each atom index in the sequence passed to the function in turn.