2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 2010,2012,2013, 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.
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.
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.
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.
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.
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.
35 /*! \defgroup module_analysisdata Parallelizable Handling of Output Data (analysisdata)
36 * \ingroup group_analysismodules
38 * Provides functionality for handling and processing output data from
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.
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.
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
70 * data [ label="AnalysisData", URL="\ref gmx::AnalysisData" ],
71 * module1 [ label="data module", URL="\ref gmx::AnalysisDataModuleInterface" ];
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()" ];
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.
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" ];
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" ];
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()" ];
150 * <H3>Using Data Objects and Modules</H3>
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.
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.
170 * <H3>Writing New Data and Module Objects</H3>
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.
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.
191 * \author Teemu Murtola <teemu.murtola@gmail.com>
195 * Public API convenience header for analysis data handling.
197 * \author Teemu Murtola <teemu.murtola@gmail.com>
199 * \ingroup module_analysisdata
201 #ifndef GMX_ANALYSISDATA_H
202 #define GMX_ANALYSISDATA_H
204 #include "analysisdata/analysisdata.h"
205 #include "analysisdata/arraydata.h"
206 #include "analysisdata/dataframe.h"
207 #include "analysisdata/modules/average.h"
208 #include "analysisdata/modules/displacement.h"
209 #include "analysisdata/modules/histogram.h"
210 #include "analysisdata/modules/lifetime.h"
211 #include "analysisdata/modules/plot.h"