docs/doxygen/analysisframework.md

   1 Framework for trajectory analysis {#page_analysisframework}
   2 =================================
   3
   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:
   8
   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
  29    to the analysis code.
  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).
  34
  35 For a crash course on how to implement an analysis tool using the framework, see
  36 \subpage page_analysistemplate.
  37
  38
  39 High-level framework
  40 ====================
  41
  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
  49 more details.
  50
  51
  52 Selections
  53 ==========
  54
  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
  58 classes:
  59
  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.
  68
  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.
  72
  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
  77 analysis framework.
  78
  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
  83 functionality.
  84
  85
  86 Output data handling
  87 ====================
  88
  89 The \ref module_analysisdata module provides two things:
  90
  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
  95        post-processing.
  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.
 101
 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
 105 technical details.
 106
 107
 108 Input options {#section_analysisframework_options}
 109 =============
 110
 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.