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

typedef struct methoddata_insolidangle t_methoddata_insolidangle

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.

typedef struct spheresurfacebin t_spheresurfacebin

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

enum gmx::SelectionStringMatchType

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]

coll

Selection collection to work on.

HelpTopicPointer gmx::createSelectionHelpTopic

(

)

*/

Creates a help tree for selections.

Exceptions

std::bad_alloc

if 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]	atomIndex	Index of the next atom in the sequence.
[in]	top	Topology structure.
[in]	type	Type of group to split into.
[in,out]	id	Variable 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.