src/gromacs/analysisdata.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2010,2012,2013,2014, by the GROMACS development team, led by
   5  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   6  * and including many others, as listed in the AUTHORS file in the
   7  * top-level source directory and at http://www.gromacs.org.
   8  *
   9  * GROMACS is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public License
  11  * as published by the Free Software Foundation; either version 2.1
  12  * of the License, or (at your option) any later version.
  13  *
  14  * GROMACS is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public
  20  * License along with GROMACS; if not, see
  21  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  22  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  23  *
  24  * If you want to redistribute modifications to GROMACS, please
  25  * consider that scientific software is very special. Version
  26  * control is crucial - bugs must be traceable. We will be happy to
  27  * consider code for inclusion in the official distribution, but
  28  * derived work must not be called official GROMACS. Details are found
  29  * in the README & COPYING files - if they are missing, get the
  30  * official version at http://www.gromacs.org.
  31  *
  32  * To help us fund GROMACS development, we humbly ask that you cite
  33  * the research papers on the package. Check out http://www.gromacs.org.
  34  */
  35 /*! \defgroup module_analysisdata Parallelizable Handling of Output Data (analysisdata)
  36  * \ingroup group_analysismodules
  37  * \brief
  38  * Provides functionality for handling and processing output data from
  39  * analysis.
  40  *
  41  * <H3>Overview</H3>
  42  *
  43  * This module provides functionality to do common processing for tabular data
  44  * in analysis tools.  In addition to providing this common functionality, one
  45  * major driver for this module is to make it simple to write analysis tools
  46  * that process frames in parallel: the functionality in this module takes care
  47  * of necessary synchronization and communication such that output from the
  48  * frames is collected and output in the correct order.
  49  *
  50  * This module consists of two main parts.  The first is formed by the
  51  * gmx::AbstractAnalysisData class and classes that derive from it:
  52  * gmx::AnalysisData and gmx::AnalysisArrayData.  These classes are used to
  53  * process and store raw data as produced by the analysis tool.  They also
  54  * provide an interface to attach data modules that implement
  55  * gmx::AnalysisDataModuleInterface.
  56  * Modules that implement this interface form the second part of the module,
  57  * and they provide functionality to do processing operations on the data.
  58  * These modules can also derive from gmx::AbstractAnalysisData, allowing other
  59  * modules to be attached to them to form a processing chain that best suits
  60  * the analysis tool.  Typically, such a processing chain ends in a plotting
  61  * module that writes the data into a file, but the final module can also
  62  * provide direct access to the processed data, allowing the analysis tool to
  63  * do custom postprocessing outside the module framework.
  64  *
  65  * The sequence chart below shows an overview of how analysis data objects
  66  * and modules interact (currently, multipoint data is an exception to this
  67  * diagram).
  68  * \msc
  69  *     caller,
  70  *     data [ label="AnalysisData", URL="\ref gmx::AnalysisData" ],
  71  *     module1 [ label="data module", URL="\ref gmx::AnalysisDataModuleInterface" ];
  72  *
  73  *     caller box module1 [ label="caller creates and initializes all objects" ];
  74  *     caller => data [ label="addModule(module1)",
  75  *                      URL="\ref gmx::AbstractAnalysisData::addModule() " ];
  76  *     caller => data [ label="startData()",
  77  *                      URL="\ref gmx::AnalysisData::startData()" ];
  78  *     data => module1 [ label="dataStarted()",
  79  *                       URL="\ref gmx::AnalysisDataModuleInterface::dataStarted()" ];
  80  *     caller << data [ label="handle",
  81  *                      URL="\ref gmx::AnalysisDataHandle" ];
  82  *     caller => data [ label="handle->startFrame(0)",
  83  *                      URL="\ref gmx::AnalysisDataHandle::startFrame()" ];
  84  *     caller => data [ label="add data for frame 0",
  85  *                      URL="\ref gmx::AnalysisDataHandle" ];
  86  *     caller => data [ label="handle->finishFrame() (frame 0)",
  87  *                      URL="\ref gmx::AnalysisDataHandle::finishFrame()" ];
  88  *     data => module1 [ label="frameStarted(0)",
  89  *                       URL="\ref gmx::AnalysisDataModuleInterface::frameStarted()" ];
  90  *     data => module1 [ label="pointsAdded()",
  91  *                       URL="\ref gmx::AnalysisDataModuleInterface::pointsAdded()" ];
  92  *     data => module1 [ label="frameFinished(0)",
  93  *                       URL="\ref gmx::AnalysisDataModuleInterface::frameFinished()" ];
  94  *     caller => data [ label="handle->startFrame(1)",
  95  *                      URL="\ref gmx::AnalysisDataHandle::startFrame()" ];
  96  *     caller => data [ label="add data for frame 1",
  97  *                      URL="\ref gmx::AnalysisDataHandle" ];
  98  *     caller => data [ label="handle2->finishFrame() (frame 1)",
  99  *                      URL="\ref gmx::AnalysisDataHandle::finishFrame()" ];
 100  *     data => module1 [ label="process frame 1" ];
 101  *     ... [ label="add more frames" ];
 102  *     caller => data [ label="handle->finishData()",
 103  *                      URL="\ref gmx::AnalysisDataHandle::finishData()" ];
 104  *     data => module1 [ label="dataFinished()",
 105  *                       URL="\ref gmx::AnalysisDataModuleInterface::dataFinished()" ];
 106  * \endmsc
 107  *
 108  * The second sequence chart below shows the interaction in the case of two
 109  * gmx::AnalysisDataHandle objects, which can be used to insert data
 110  * concurrently for multiple frames.  The gmx::AnalysisData object and the
 111  * handles take care to notify the module such that it always receives the
 112  * frames in the correct order.
 113  * \msc
 114  *     caller,
 115  *     handle1 [ label="handle1", URL="\ref gmx::AnalysisDataHandle" ],
 116  *     handle2 [ label="handle2", URL="\ref gmx::AnalysisDataHandle" ],
 117  *     module1 [ label="data module", URL="\ref gmx::AnalysisDataModuleInterface" ];
 118  *
 119  *     caller box handle2 [ label="caller has created both handles using startData()" ];
 120  *     caller => handle1 [ label="startFrame(0)",
 121  *                         URL="\ref gmx::AnalysisDataHandle::startFrame()" ];
 122  *     caller => handle2 [ label="startFrame(1)",
 123  *                         URL="\ref gmx::AnalysisDataHandle::startFrame()" ];
 124  *     caller => handle1 [ label="add data for frame 0",
 125  *                         URL="\ref gmx::AnalysisDataHandle" ];
 126  *     caller => handle2 [ label="add data for frame 1",
 127  *                         URL="\ref gmx::AnalysisDataHandle" ];
 128  *     caller => handle2 [ label="finishFrame() (frame 1)",
 129  *                         URL="\ref gmx::AnalysisDataHandle::finishFrame()" ];
 130  *     caller => handle2 [ label="startFrame(2)",
 131  *                         URL="\ref gmx::AnalysisDataHandle::startFrame()" ];
 132  *     caller => handle1 [ label="finishFrame() (frame 0)",
 133  *                         URL="\ref gmx::AnalysisDataHandle::finishFrame()" ];
 134  *     handle1 => module1 [ label="process frame 0" ];
 135  *     handle1 => module1 [ label="process frame 1" ];
 136  *     caller => handle2 [ label="add data for frame 2",
 137  *                         URL="\ref gmx::AnalysisDataHandle" ];
 138  *     caller => handle2 [ label="finishFrame() (frame 2)",
 139  *                         URL="\ref gmx::AnalysisDataHandle::finishFrame()" ];
 140  *     handle2 => module1 [ label="process frame 2" ];
 141  *     ...;
 142  *     caller => handle1 [ label="finishData()",
 143  *                         URL="\ref gmx::AnalysisDataHandle::finishData()" ];
 144  *     caller => handle2 [ label="finishData()",
 145  *                         URL="\ref gmx::AnalysisDataHandle::finishData()" ];
 146  *     handle2 => module1 [ label="dataFinished()",
 147  *                          URL="\ref gmx::AnalysisDataModuleInterface::dataFinished()" ];
 148  * \endmsc
 149  *
 150  * <H3>Using Data Objects and Modules</H3>
 151  *
 152  * To use the functionality in this module, you typically declare one or more
 153  * AnalysisData objects and set its properties.  You then create some module
 154  * objects and set their properties (see the list of classes that implement
 155  * gmx::AnalysisDataModuleInterface) and attach them to the data objects or to
 156  * one another using gmx::AbstractAnalysisData::addModule().  Then you add the
 157  * actual data values to the gmx::AnalysisData object, which automatically
 158  * passes it on to the modules.
 159  * After all data is added, you may optionally access some
 160  * results directly from the module objects.  However, in many cases it is
 161  * sufficient to initially add a plotting module to the processing chain, which
 162  * will then automatically write the results into a file.
 163  *
 164  * For simple processing needs with a small amount of data, an
 165  * gmx::AnalysisArrayData class is also provided, which keeps all the data in an
 166  * in-memory array and allows you to manipulate the data as you wish before you
 167  * pass the data to the attached modules.
 168  *
 169  * \if libapi
 170  * <H3>Writing New Data and Module Objects</H3>
 171  *
 172  * New data modules can be implemented to perform custom operations that are
 173  * not supported by the modules provided in this module.  This is done by
 174  * creating a new class that implements gmx::AnalysisDataModuleInterface.
 175  * If the new module computes values that can be used as input for other
 176  * modules, the new class should also derive from gmx::AbstractAnalysisData, and
 177  * preferably use gmx::AnalysisDataStorage internally to implement storage of
 178  * values.  See the documentation of the mentioned classes for more details on
 179  * how to implement custom modules.
 180  * When implementing a new module, it should be considered whether it can be of
 181  * more general use, and if so, it should be added to this module.
 182  *
 183  * It is also possible to implement new data source objects by deriving a class
 184  * from gmx::AbstractAnalysisData.  This should not normally be necessary, since
 185  * this module provides general data source objects for most typical uses.
 186  * If the classes in this module are not suitable for some specific use, it
 187  * should be considered whether a new generic class could be added (or an
 188  * existing extended) instead of implementing a local custom solution.
 189  * \endif
 190  *
 191  * \author Teemu Murtola <teemu.murtola@gmail.com>
 192  */
 193 /*! \file
 194  * \brief
 195  * Public API convenience header for analysis data handling.
 196  *
 197  * \author Teemu Murtola <teemu.murtola@gmail.com>
 198  * \inpublicapi
 199  * \ingroup module_analysisdata
 200  */
 201 #ifndef GMX_ANALYSISDATA_H
 202 #define GMX_ANALYSISDATA_H
 203
 204 #include "gromacs/analysisdata/analysisdata.h"
 205 #include "gromacs/analysisdata/arraydata.h"
 206 #include "gromacs/analysisdata/dataframe.h"
 207 #include "gromacs/analysisdata/modules/average.h"
 208 #include "gromacs/analysisdata/modules/displacement.h"
 209 #include "gromacs/analysisdata/modules/histogram.h"
 210 #include "gromacs/analysisdata/modules/lifetime.h"
 211 #include "gromacs/analysisdata/modules/plot.h"
 212
 213 #endif