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 There are also some reusable analysis routines that can be used independent of
37 - \subpage page_analysisnbsearch
39 For a crash course on how to implement an analysis tool using the framework, see
40 \subpage page_analysistemplate.
46 The \ref module_trajectoryanalysis module provides the high-level framework
47 that integrates all the pieces together.
48 It provides the abstract base class for analysis tool modules
49 (gmx::TrajectoryAnalysisModule), and the code that runs such a module as a
50 command-line tool (gmx::TrajectoryAnalysisCommandLineRunner).
51 See the [analysis template](\ref page_analysistemplate) and the
52 [trajectoryanalysis module documentation](\ref module_trajectoryanalysis) for
59 The \ref module_selection module provides the support for selections.
60 Most of the work of managing the selections is taken care by the command-line
61 runner and the framework, and the analysis tool code only sees two main
64 - gmx::SelectionOption and associated classes are used to declare the
65 number and type of selections the tool accepts (see below for
66 [details of the option support](#section_analysisframework_options)).
67 - The tool receives a set of gmx::Selection objects as a value of the
68 selection option. These classes provide the evaluated values for the
69 selections during the analysis. The framework evaluates them for each
70 frame such that when the tool is called, it can access the selections for
71 the current frame in the gmx::Selection objects it owns.
73 A conceptual overview of the selection engine is available on a separate page:
74 \subpage page_selections. In the full internal documentation, this page
75 also provides an overview of the implementation of the selections.
77 More technical details of the selection engine are also available in the
78 [selection module documentation](\ref module_selection).
79 This is useful in particular for understanding how the selections work in
80 detail, or if you want to use the selection code outside the trajectory
83 The selection module also provides functionality to do neighborhood searching
84 in analysis tools. For the most common case of full 3D periodic boundary
85 conditions, grid-based searching is implemented. See gmx::AnalysisNeighborhood
86 for more details. This class can be used independently of other selection
93 The \ref module_analysisdata module provides two things:
95 - Support for uniformly providing output data from analysis tools.
96 Tools compute their output values and place them into a
97 _data object_ for further processing. This allows two things:
98 - Reusable data modules can be applied across different tools to do common
100 - The data object provides parallelization support.
101 - Set of reusable data modules for post-processing the data. These include
102 functionality like averaging data, computing histograms, and plotting the
103 data into a file. Many of these modules also provide their output as a data
104 object, allowing further data modules to be attached to them.
106 The general concept is explained in more detail on a separate page:
107 \subpage page_analysisdata.
108 The [analysisdata module documentation](\ref module_analysisdata) provides more
112 Input options {#section_analysisframework_options}
115 To declare input data for the tool (typically, command-line options, including
116 input files and selections), \ref module_options module is used.
117 The analysis tool code receives an instance of gmx::IOptionsContainer for one of
118 its initialization methods, and uses it to provide its input options.
119 Basic options are declared in basicoptions.h, and also gmx::SelectionOption is
120 used in the same manner. For each option, the tool declares a local variable
121 that will receive the value for that option. After the options are parsed from
122 the command line (by the framework), the tool code can read the values from
123 these variables. The option declarations filled into the
124 gmx::IOptionsContainer object are also used to provide help to the user (also
125 handled by the framework).
126 See the documentation for gmx::TrajectoryAnalysisModule and the
127 [options module documentation](\ref module_options) for more details.