docs/doxygen/user/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 There are also some reusable analysis routines that can be used independent of
  36 the framework:
  37  - \subpage page_analysisnbsearch
  38
  39 For a crash course on how to implement an analysis tool using the framework, see
  40 \subpage page_analysistemplate.
  41
  42
  43 High-level framework
  44 ====================
  45
  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
  53 more details.
  54
  55
  56 Selections
  57 ==========
  58
  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
  62 classes:
  63
  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.
  72
  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.
  76
  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
  81 analysis framework.
  82
  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
  87 functionality.
  88
  89
  90 Output data handling
  91 ====================
  92
  93 The \ref module_analysisdata module provides two things:
  94
  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
  99        post-processing.
 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.
 105
 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
 109 technical details.
 110
 111
 112 Input options {#section_analysisframework_options}
 113 =============
 114
 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.