src/gromacs/analysisdata.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2010,2012, by the GROMACS development team, led by
   5  * David van der Spoel, Berk Hess, Erik Lindahl, and including many
   6  * others, as listed in the AUTHORS file in the top-level source
   7  * 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
  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  * AbstractAnalysisData class and classes that derive from it:
  52  * AnalysisData and AnalysisArrayData.  These classes are used to process and
  53  * store raw data as produced by the analysis tool.  They also provide an
  54  * interface to attach data modules that implement AnalysisDataModuleInterface.
  55  * Modules that implement this interface form the second part of the module,
  56  * and they provide functionality to do processing operations on the data.
  57  * These modules can also derive from AbstractAnalysisData, allowing other
  58  * modules to be attached to them to form a processing chain that best suits
  59  * the analysis tool.  Typically, such a processing chain ends in a plotting
  60  * module that writes the data into a file, but the final module can also
  61  * provide direct access to the processed data, allowing the analysis tool to
  62  * do custom postprocessing outside the module framework.
  63  *
  64  * <H3>Using Data Objects and Modules</H3>
  65  *
  66  * To use the functionality in this module, you typically declare one or more
  67  * AnalysisData objects and set its properties.  You then create some module
  68  * objects and set their properties (see the list of classes that implement
  69  * AnalysisDataModuleInterface) and attach them to the data objects or to one
  70  * another using AbstractAnalysisData::addModule().  Then you add the actual
  71  * data values to the AnalysisData object, which automatically passes it on to
  72  * the modules.  After all data is added, you may optionally access some
  73  * results directly from the module objects.  However, in many cases it is
  74  * sufficient to initially add a plotting module to the processing chain, which
  75  * will then automatically write the results into a file.
  76  *
  77  * For simple processing needs with a small amount of data, an
  78  * AnalysisArrayData class is also provided, which keeps all the data in an
  79  * in-memory array and allows you to manipulate the data as you wish before you
  80  * pass the data to the attached modules.
  81  *
  82  * \if libapi
  83  * <H3>Writing New Data and Module Objects</H3>
  84  *
  85  * New data modules can be implemented to perform custom operations that are
  86  * not supported by the modules provided in this module.  This is done by
  87  * creating a new class that implements AnalysisDataModuleInterface.
  88  * If the new module computes values that can be used as input for other
  89  * modules, the new class should also derive from AbstractAnalysisData, and
  90  * preferably use AnalysisDataStorage internally to implement storage of
  91  * values.  See the documentation of the mentioned classes for more details on
  92  * how to implement custom modules.
  93  * When implementing a new module, it should be considered whether it can be of
  94  * more general use, and if so, it should be added to this module.
  95  *
  96  * It is also possible to implement new data source objects by deriving a class
  97  * from AbstractAnalysisData.  This should not normally be necessary, since
  98  * this module provides general data source objects for most typical uses.
  99  * If the classes in this module are not suitable for some specific use, it
 100  * should be considered whether a new generic class could be added (or an
 101  * existing extended) instead of implementing a local custom solution.
 102  * \endif
 103  *
 104  * \author Teemu Murtola <teemu.murtola@gmail.com>
 105  */
 106 /*! \file
 107  * \brief
 108  * Public API convenience header for analysis data handling.
 109  *
 110  * \author Teemu Murtola <teemu.murtola@gmail.com>
 111  * \inpublicapi
 112  * \ingroup module_analysisdata
 113  */
 114 #ifndef GMX_ANALYSISDATA_H
 115 #define GMX_ANALYSISDATA_H
 116
 117 #include "analysisdata/analysisdata.h"
 118 #include "analysisdata/arraydata.h"
 119 #include "analysisdata/dataframe.h"
 120 #include "analysisdata/modules/average.h"
 121 #include "analysisdata/modules/displacement.h"
 122 #include "analysisdata/modules/histogram.h"
 123 #include "analysisdata/modules/plot.h"
 124
 125 #endif