src/gromacs/analysisdata.h

   1 /*
   2  *
   3  *                This source code is part of
   4  *
   5  *                 G   R   O   M   A   C   S
   6  *
   7  *          GROningen MAchine for Chemical Simulations
   8  *
   9  * Written by David van der Spoel, Erik Lindahl, Berk Hess, and others.
  10  * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
  11  * Copyright (c) 2001-2009, The GROMACS development team,
  12  * check out http://www.gromacs.org for more information.
  13
  14  * This program is free software; you can redistribute it and/or
  15  * modify it under the terms of the GNU General Public License
  16  * as published by the Free Software Foundation; either version 2
  17  * of the License, or (at your option) any later version.
  18  *
  19  * If you want to redistribute modifications, please consider that
  20  * scientific software is very special. Version control is crucial -
  21  * bugs must be traceable. We will be happy to consider code for
  22  * inclusion in the official distribution, but derived work must not
  23  * be called official GROMACS. Details are found in the README & COPYING
  24  * files - if they are missing, get the official version at www.gromacs.org.
  25  *
  26  * To help us fund GROMACS development, we humbly ask that you cite
  27  * the papers on the package - you can find them in the top README file.
  28  *
  29  * For more info, check our website at http://www.gromacs.org
  30  */
  31 /*! \defgroup module_analysisdata Parallelizable Handling of Output Data
  32  * \ingroup group_analysismodules
  33  * \brief
  34  * Provides functionality for handling and processing output data from
  35  * analysis.
  36  *
  37  * <H3>Overview</H3>
  38  *
  39  * This module provides functionality to do common processing for tabular data
  40  * in analysis tools.  In addition to providing this common functionality, one
  41  * major driver for this module is to make it simple to write analysis tools
  42  * that process frames in parallel: the functionality in this module takes care
  43  * of necessary synchronization and communication such that output from the
  44  * frames is collected and output in the correct order.
  45  *
  46  * This module consists of two main parts.  The first is formed by the
  47  * AbstractAnalysisData class and classes that derive from it:
  48  * AnalysisData and AnalysisArrayData.  These classes are used to process and
  49  * store raw data as produced by the analysis tool.  They also provide an
  50  * interface to attach data modules that implement AnalysisDataModuleInterface.
  51  * Modules that implement this interface form the second part of the module,
  52  * and they provide functionality to do processing operations on the data.
  53  * These modules can also derive from AbstractAnalysisData, allowing other
  54  * modules to be attached to them to form a processing chain that best suits
  55  * the analysis tool.  Typically, such a processing chain ends in a plotting
  56  * module that writes the data into a file, but the final module can also
  57  * provide direct access to the processed data, allowing the analysis tool to
  58  * do custom postprocessing outside the module framework.
  59  *
  60  * <H3>Using Data Objects and Modules</H3>
  61  *
  62  * To use the functionality in this module, you typically declare one or more
  63  * AnalysisData objects and set its properties.  You then create some module
  64  * objects and set their properties (see the list of classes that implement
  65  * AnalysisDataModuleInterface) and attach them to the data objects or to one
  66  * another using AbstractAnalysisData::addModule().  Then you add the actual
  67  * data values to the AnalysisData object, which automatically passes it on to
  68  * the modules.  After all data is added, you may optionally access some
  69  * results directly from the module objects.  However, in many cases it is
  70  * sufficient to initially add a plotting module to the processing chain, which
  71  * will then automatically write the results into a file.
  72  *
  73  * For simple processing needs with a small amount of data, an
  74  * AnalysisArrayData class is also provided, which keeps all the data in an
  75  * in-memory array and allows you to manipulate the data as you wish before you
  76  * pass the data to the attached modules.
  77  *
  78  * \if libapi
  79  * <H3>Writing New Data and Module Objects</H3>
  80  *
  81  * New data modules can be implemented to perform custom operations that are
  82  * not supported by the modules provided in this module.  This is done by
  83  * creating a new class that implements AnalysisDataModuleInterface.
  84  * If the new module computes values that can be used as input for other
  85  * modules, the new class should also derive from AbstractAnalysisData, and
  86  * preferably use AnalysisDataStorage internally to implement storage of
  87  * values.  See the documentation of the mentioned classes for more details on
  88  * how to implement custom modules.
  89  * When implementing a new module, it should be considered whether it can be of
  90  * more general use, and if so, it should be added to this module.
  91  *
  92  * It is also possible to implement new data source objects by deriving a class
  93  * from AbstractAnalysisData.  This should not normally be necessary, since
  94  * this module provides general data source objects for most typical uses.
  95  * If the classes in this module are not suitable for some specific use, it
  96  * should be considered whether a new generic class could be added (or an
  97  * existing extended) instead of implementing a local custom solution.
  98  * \endif
  99  *
 100  * \author Teemu Murtola <teemu.murtola@cbr.su.se>
 101  */
 102 /*! \file
 103  * \brief
 104  * Public API convenience header for analysis data handling.
 105  *
 106  * \author Teemu Murtola <teemu.murtola@cbr.su.se>
 107  * \inpublicapi
 108  * \ingroup module_analysisdata
 109  */
 110 #ifndef GMX_ANALYSISDATA_H
 111 #define GMX_ANALYSISDATA_H
 112
 113 #include "analysisdata/analysisdata.h"
 114 #include "analysisdata/arraydata.h"
 115 #include "analysisdata/dataframe.h"
 116 #include "analysisdata/modules/average.h"
 117 #include "analysisdata/modules/displacement.h"
 118 #include "analysisdata/modules/histogram.h"
 119 #include "analysisdata/modules/plot.h"
 120
 121 #endif