Gromacs  2022.2
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Classes | Enumerations | Functions | Directories | Files
Framework for Trajectory Analysis (trajectoryanalysis)
+ 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.

msc_inline_mscgraph_11

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.

msc_inline_mscgraph_12

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.

msc_inline_mscgraph_13

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]managerCommand-line module manager to receive the modules.
Exceptions
std::bad_allocif out of memory.

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