Collaboration diagram for Framework for Trajectory Analysis (trajectoryanalysis):

Description

Provides functionality for implementing trajectory analysis modules.

This module implements a framework for implementing flexible trajectory analysis routines. It provides a base class for implementing analysis as reusable modules that can be used from different contexts and can also support per-frame parallelization. It integrally uses functionality from the following modules:

The main interface of this module is the gmx::TrajectoryAnalysisModule class. Analysis modules should derive from this class, and override the necessary virtual methods to provide the actual initialization and analysis routines. Classes gmx::TrajectoryAnalysisSettings and gmx::TopologyInformation (in addition to classes declared in the above-mentioned modules) are used to pass information to and from these methods. gmx::TrajectoryAnalysisModuleData can be used in advanced scenarios where the tool requires custom thread-local data for parallel analysis.

The sequence charts below provides an overview of how the trajectory analysis modules typically interact with other components. The first chart provides an overview of the call sequence of the most important methods in gmx::TrajectoryAnalysisModule. There is a runner, which is responsible for doing the work that is shared between all trajectory analysis (such as reading the trajectory and processing selections). The runner then calls different methods in the analysis module at appropriate points to perform the module-specific tasks. The analysis module is responsible for creating and managing gmx::AnalysisData objects, and the chart shows the most important interactions with this module as well. However, the runner takes responsibility of calling gmx::AnalysisData::finishFrameSerial(). Interactions with options (for command-line option processing) and selections is not shown for brevity: see Extensible Handling of Options (options) for an overview of how options work, and the second chart for a more detailed view of how selections are accessed from an analysis module.

The second chart below shows the interaction with selections and options with focus on selection options. The gmx::TrajectoryAnalysisModule object creates one or more gmx::Selection variables, and uses gmx::SelectionOption to indicate them as the destination for selections. This happens in gmx::TrajectoryAnalysisModule::initOptions(). After the options have been parsed (includes parsing any options present on the command-line or read from files, but not those provided interactively), gmx::TrajectoryAnalysisModule::optionsFinished() can adjust the selections using gmx::SelectionOptionInfo. This is done like this to allow the analysis module to influence the interactive prompt of selections based on what command-line options were given. After optionsFinished() returns, the interactive selection prompt is presented if necessary. After this point, all access to selections from the analysis module is through the gmx::Selection variables: the runner is responsible for calling methods in the selection library, and these methods update the content referenced by the gmx::Selection variables. See documentation of gmx::TrajectoryAnalysisModule for details of what the selections contain at each point.

The final chart shows the flow within the frame loop in the case of parallel (threaded) execution and the interaction with the Parallelizable Handling of Output Data (analysisdata) module in this case. Although parallelization has not yet been implemented, it has influenced the design and needs to be understood if one wants to write modules that can take advantage of the parallelization once it gets implemented. The parallelization takes part over frames: analyzing a single frame is one unit of work. When the frame loop is started, gmx::TrajectoryAnalysisModule::startFrames() is called for each thread, and initializes an object that contains thread-local data needed during the analysis. This includes selection information, gmx::AnalysisDataHandle objects, and possibly other module-specific variables. Then, the runner reads the frames in sequence and passes the work into the different threads, together with the appropriate thread-local data object. The gmx::TrajectoryAnalysisModule::analyzeFrame() calls are only allowed to modify the thread-local data object; everything else is read-only. For any output, they pass the information to gmx::AnalysisData, which together with the runner takes care of ordering the data from different frames such that it gets processed in the right order. When all frames are analyzed, gmx::TrajectoryAnalysisModule::finishFrames() is called for each thread-local data object to destroy them and to accumulate possible results from them into the main gmx::TrajectoryAnalysisModule object. Note that in the diagram, some part of the work attributed for the runner (e.g., evaluating selections) will actually be carried out in the analysis threads before gmx::TrajectoryAnalysisModule::analyzeFrame() gets called.

In addition to the framework for defining analysis modules, this module also provides gmx::TrajectoryAnalysisCommandLineRunner, which implements a command-line program that runs a certain analysis module.

Internally, the module also defines a set of trajectory analysis modules that can currently be accessed only through gmx::registerTrajectoryAnalysisModules.

For an example of how to implement an analysis tool using the framework, see template.cpp.

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

Classes
class	gmx::TrajectoryAnalysisModuleData
	Base class for thread-local data storage during trajectory analysis. More...

class	gmx::TrajectoryAnalysisModule
	Base class for trajectory analysis modules. More...

class	gmx::TrajectoryAnalysisSettings
	Trajectory analysis module configuration object. More...

class	gmx::TrajectoryAnalysisCommandLineRunner
	Runner for command-line trajectory analysis tools. More...

class	gmx::UnionFinder
	Union-find data structure for keeping track of disjoint sets. More...

class	gmx::MappedUnionFinder
	Extension of UnionFind that supports non-consecutive integer indices as items. More...

class	gmx::TopologyInformation
	Topology information available to a trajectory analysis module. More...

Enumerations
enum	gmx::analysismodules::@1789::DistanceType : int { Min, Max, Count }
	Enum value to store the selected value for `-type`.

enum	gmx::analysismodules::@1789::GroupType : int { All, Residue, Molecule, None, Count }
	Enum value to store the selected value for `-refgrouping`/`-selgrouping`.

enum	gmx::analysismodules::@1791::Normalization : int { Rdf, NumberDensity, None, Count }
	Normalization for the computed distribution.

enum	gmx::analysismodules::@1791::SurfaceType : int { None, Molecule, Residue, Count }
	Whether to compute RDF wrt. surface of the reference group.

Functions
void	gmx::registerTrajectoryAnalysisModules (CommandLineModuleManager *manager)
	Registers all trajectory analysis command-line modules. More...

Directories
directory	trajectoryanalysis
	Framework for Trajectory Analysis (trajectoryanalysis)

directory	tests
	Unit tests for Framework for Trajectory Analysis (trajectoryanalysis).

Files
file	analysismodule.h
	Declares gmx::TrajectoryAnalysisModule and gmx::TrajectoryAnalysisModuleData.

file	analysissettings.h
	Declares gmx::TrajectoryAnalysisSettings.

file	cmdlinerunner.h
	Declares gmx::TrajectoryAnalysisCommandLineRunner.

file	unionfind.h
	Implements gmx::UnionFinder and gmx::MappedUnionFinder.

file	modules.h
	Generic interface for accessing trajectory analysis modules.

file	topologyinformation.h
	Declares gmx::TopologyInformation.

file	trajectoryanalysis.h
	Public API convenience header for trajectory analysis framework.

Function Documentation

void gmx::registerTrajectoryAnalysisModules ( CommandLineModuleManager * manager )

Registers all trajectory analysis command-line modules.

Parameters

[in] manager Command-line module manager to receive the modules.

Exceptions

std::bad_alloc if out of memory.

Registers all trajectory analysis modules declared in the library such that they can be run through manager.

Description

Classes

Enumerations

Functions

Directories

Files

Function Documentation