1 Framework for trajectory analysis {#page_analysisframework}
2 =================================
4 \Gromacs provides a framework for implementing flexible trajectory analysis
5 routines. It consists of a few components that can also be used individually,
6 but in most cases it is desirable to use features from all of them to get most
7 out of the framework. The main features are:
9 - Support for flexible selections that can be used to provide the set of
10 coordinates to analyze. They can be dynamic, i.e., select different atoms
11 for different trajectory frames, and also support evaluation of
12 center-of-mass/center-of-geometry coordinates for a group of atoms.
13 The latter means that a tool written to use the framework can automatically
14 analyze also center-of-mass positions (or a mixture of center-of-mass and
15 atomic positions) in addition to real atomic positions.
16 - Support for per-frame parallelization. The framework is designed to
17 support running the analysis in parallel for multiple frames for cases where
18 different frames can be analyzed (mostly) independently. At this time, the
19 actual parallelization is not implemented, but tools written to use the
20 framework should be able to take advantage of it as soon as it materializes
21 with no or minimal changes.
22 - Access to a library of basic analysis routines. Things such as computing
23 averages and histogramming are provided as reusable modules.
24 - Tool code can focus on the actual analysis. Tools are implemented by
25 subclassing an abstract class and providing an implementation for selected
26 pure virtual methods. The framework takes care of initialization tasks,
27 loading the trajectory and looping over it, evaluating selections, and also
28 provides basic features like making molecules whole before passing the frame
30 This approach also makes it possible to reuse the same tool code from a
31 scripting language such as Python simply by implementing general support for
32 such language bindings in the framework (no such integration is implemented
33 at this time, though).
35 For a crash course on how to implement an analysis tool using the framework, see
36 \subpage page_analysistemplate.
42 The \ref module_trajectoryanalysis module provides the high-level framework
43 that integrates all the pieces together.
44 It provides the abstract base class for analysis tool modules
45 (gmx::TrajectoryAnalysisModule), and the code that runs such a module as a
46 command-line tool (gmx::TrajectoryAnalysisCommandLineRunner).
47 See the [analysis template](\ref page_analysistemplate) and the
48 [trajectoryanalysis module documentation](\ref module_trajectoryanalysis) for
55 The \ref module_selection module provides the support for selections.
56 Most of the work of managing the selections is taken care by the command-line
57 runner and the framework, and the analysis tool code only sees two main
60 - gmx::SelectionOption and associated classes are used to declare the
61 number and type of selections the tool accepts (see below for
62 [details of the option support](#section_analysisframework_options)).
63 - The tool receives a set of gmx::Selection objects as a value of the
64 selection option. These classes provide the evaluated values for the
65 selections during the analysis. The framework evaluates them for each
66 frame such that when the tool is called, it can access the selections for
67 the current frame in the gmx::Selection objects it owns.
69 A conceptual overview of the selection engine is available on a separate page:
70 \subpage page_selections. In the full internal documentation, this page
71 also provides an overview of the implementation of the selections.
73 More technical details of the selection engine are also available in the
74 [selection module documentation](\ref module_selection).
75 This is useful in particular for understanding how the selections work in
76 detail, or if you want to use the selection code outside the trajectory
79 The selection module also provides functionality to do neighborhood searching
80 in analysis tools. For the most common case of full 3D periodic boundary
81 conditions, grid-based searching is implemented. See gmx::AnalysisNeighborhood
82 for more details. This class can be used independently of other selection
89 The \ref module_analysisdata module provides two things:
91 - Support for uniformly providing output data from analysis tools.
92 Tools compute their output values and place them into a
93 _data object_ for further processing. This allows two things:
94 - Reusable data modules can be applied across different tools to do common
96 - The data object provides parallelization support.
97 - Set of reusable data modules for post-processing the data. These include
98 functionality like averaging data, computing histograms, and plotting the
99 data into a file. Many of these modules also provide their output as a data
100 object, allowing further data modules to be attached to them.
102 The general concept is explained in more detail on a separate page:
103 \subpage page_analysisdata.
104 The [analysisdata module documentation](\ref module_analysisdata) provides more
108 Input options {#section_analysisframework_options}
111 To declare input data for the tool (typically, command-line options, including
112 input files and selections), \ref module_options module is used.
113 The analysis tool code receives a pre-initialized gmx::Options object in one of
114 its initialization methods, and fills it with its input options.
115 Basic options are declared in basicoptions.h, and also gmx::SelectionOption is
116 used in the same manner. For each option, the tool declares a local variable
117 that will receive the value for that option. After the options are parsed from
118 the command line (by the framework), the tool code can read the values from
119 these variables. The option declarations, and other information filled into
120 the gmx::Options object, are also used to provide help to the user (also
121 handled by the framework).
122 See the documentation for gmx::TrajectoryAnalysisModule and the
123 [options module documentation](\ref module_options) for more details.