Gromacs  2025.0-dev-20241014-f673b97
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Framework for trajectory analysis

GROMACS provides a framework for implementing flexible trajectory analysis routines. It consists of a few components that can also be used individually, but in most cases it is desirable to use features from all of them to get most out of the framework. The main features are:

There are also some reusable analysis routines that can be used independent of the framework:

For a crash course on how to implement an analysis tool using the framework, see Example code for writing trajectory analysis tools.

High-level framework

The Framework for Trajectory Analysis (trajectoryanalysis) module provides the high-level framework that integrates all the pieces together. It provides the abstract base class for analysis tool modules (gmx::TrajectoryAnalysisModule), and the code that runs such a module as a command-line tool (gmx::TrajectoryAnalysisCommandLineRunner). See the analysis template and the trajectoryanalysis module documentation for more details.

Selections

The Parsing and Evaluation of Analysis Selections (selection) module provides the support for selections. Most of the work of managing the selections is taken care by the command-line runner and the framework, and the analysis tool code only sees two main classes:

A conceptual overview of the selection engine is available on a separate page: Dynamic selections. In the full internal documentation, this page also provides an overview of the implementation of the selections.

More technical details of the selection engine are also available in the selection module documentation. This is useful in particular for understanding how the selections work in detail, or if you want to use the selection code outside the trajectory analysis framework.

The selection module also provides functionality to do neighborhood searching in analysis tools. For the most common case of full 3D periodic boundary conditions, grid-based searching is implemented. See gmx::AnalysisNeighborhood for more details. This class can be used independently of other selection functionality.

Output data handling

The Parallelizable Handling of Output Data (analysisdata) module provides two things:

The general concept is explained in more detail on a separate page: Analysis output data handling. The analysisdata module documentation provides more technical details.

Input options

To declare input data for the tool (typically, command-line options, including input files and selections), Extensible Handling of Options (options) module is used. The analysis tool code receives an instance of gmx::IOptionsContainer for one of its initialization methods, and uses it to provide its input options. Basic options are declared in basicoptions.h, and also gmx::SelectionOption is used in the same manner. For each option, the tool declares a local variable that will receive the value for that option. After the options are parsed from the command line (by the framework), the tool code can read the values from these variables. The option declarations filled into the gmx::IOptionsContainer object are also used to provide help to the user (also handled by the framework). See the documentation for gmx::TrajectoryAnalysisModule and the options module documentation for more details.

Coordinate data output

The Handling of writing new coordinate files module allows modules to output coordinate data used or generated during the analysis. It provides two main components:

More detailed information, as well as an interaction diagram can be found in the module documentation.