GROMACS Code Tutorial for Writing Trajectory Analysis

The GROMACS installation includes a template for writing trajectory analysis tools using the trajectory analysis framework.

It can be found in share/gromacs/template/ in the installation directory and share/template/ in the source code distribution.

The complete source code of this document is also included in this document: template.cpp. The rest of this article will introduce the code to explain the different parts.

Tutorial

Global definition

First include some common C++ header files:

And continue to include the header files of the analysis library:

This header file contains other header files, which together define all the basic data types required to write a trajectory analysis tool. For convenience, we also import all names in the gmx namespace into the global scope to avoid reusing the name anywhere:

Tool module

The analysis tool class comes from gmx::TrajectoryAnalysisModule. This interface has some convenient functions to interface with other code earlier interfaces. For a complete description of the available virtual methods and convenient functions, please refer to the documentation of gmx::TrajectoryAnalysisModule. The AnalysisNeighborhood object provides the neighborhood search used in the analysis. The last variable block is used to process the output data. For details on how to use them, please refer to initAnalysis(). For the template, we don't need any custom frame local data. If you think you need some more complex analysis requirements, please refer to the documentation of gmx::TrajectoryAnalysisModuleData for more details. You can simply declare all variables in the module class, initialize them in gmx::TrajectoryAnalysisModule::initAnalysis(), and do any post-processing in gmx::TrajectoryAnalysisModule::finishAnalysis()..

Constructor

The constructor of the analysis module is simple: the constructor should just initialize the default values, and the destructor should release any memory managed by the module. For templates, there are no properties in our class that need to be explicitly released, so we only declare a constructor:

{

AnalysisTemplate::AnalysisTemplate(): cutoff_(0.0)

{registerAnalysisDataset(&data_, "avedist");

}

Input options

The initialization of the module is divided into several methods, two of which are used in the template. gmx::TrajectoryAnalysisModule::initOptions() is used to set the options understood by the module, and to set different options through gmx::TrajectoryAnalysisSettings (for more details, please refer to the documentation of this class.

Analysis initialization

The actual analysis is initialized in gmx::TrajectoryAnalysisModule::initAnalysis():

Output

Finally, most programs need to output some values after the analysis is complete. In some cases, this can be achieved by linking the data modules correctly, but usually some custom processing is required. All these activities should be done in gmx::TrajectoryAnalysisModule::writeOutput().

Definition of main()

Now, the only thing left is to define the main() function. To implement a command line tool, it should create a module and use gmx::TrajectoryAnalysisCommandLineRunner to run it with the following boilerplate code:

intmain(int argc, char *argv[])

{return gmx::TrajectoryAnalysisCommandLineRunner::runAsMain(argc, argv);

}