| blob | ac115b6593d8ffd71bcb3ef6a0fc434e016c4770 |
1 /*
2 * This file is part of the GROMACS molecular simulation package.
3 *
4 * Copyright (c) 2010,2012,2013,2014,2015, 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 * See \ref page_analysisdata for an overview of the high-level functionality
50 * and the terminology used.
51 *
52 * This module consists of two main parts. The first is formed by the
53 * gmx::AbstractAnalysisData class and classes that derive from it:
54 * gmx::AnalysisData and gmx::AnalysisArrayData. These classes are used to
55 * process and store raw data as produced by the analysis tool. They also
56 * provide an interface to attach data modules that implement
57 * gmx::IAnalysisDataModule.
58 *
59 * Modules that implement gmx::IAnalysisDataModule form the second part
60 * of the module, and they provide functionality to do processing on the data.
61 * These modules can also derive from gmx::AbstractAnalysisData, allowing other
62 * modules to be attached to them to form a processing chain that best suits
63 * the analysis tool. Typically, such a processing chain ends in a plotting
64 * module that writes the data into a file, but the final module can also
65 * provide direct access to the processed data, allowing the analysis tool to
66 * do custom postprocessing outside the module framework.
67 *
68 * <H3>Using Data Objects and Modules</H3>
69 *
70 * To use the functionality in this module, you typically declare one or more
71 * AnalysisData objects and set its properties. You then create some module
72 * objects and set their properties (see the list of classes that implement
73 * gmx::IAnalysisDataModule) and attach them to the data objects or to
74 * one another using gmx::AbstractAnalysisData::addModule(). Then you add the
75 * actual data values to the gmx::AnalysisData object, which automatically
76 * passes it on to the modules.
77 * After all data is added, you may optionally access some results directly
78 * from the module objects or from the gmx::AnalysisData object itself.
79 * However, in many cases it is sufficient to initially add a plotting module
80 * to the processing chain, which will then automatically write the results
81 * into a file.
82 *
83 * For simple processing needs with a small amount of data, an
84 * gmx::AnalysisArrayData class is also provided, which keeps all the data in an
85 * in-memory array and allows you to manipulate the data as you wish before you
86 * pass the data to the attached modules.
87 *
88 * <H3>Data Modules</H3>
89 *
90 * Modules that derive from gmx::IAnalysisDataModule can operate in two
91 * modes:
92 * - In _serial_ mode, the frames are presented to the module always in the
93 * order of increasing indices, even if they become ready in a different
94 * order in the attached data.
95 * - In _parallel_ mode, the frames are presented in the order that they
96 * become available in the input data, which may not be sequential.
97 * This mode allows the input data to optimize its behavior if it does not
98 * need to store and sort the frames.
99 *
100 * The figure below shows the sequence of callbacks that the module receives.
101 * Arrows show a dependency between callbacks: the event at the start of the
102 * arrow always occurs before the event at the end. The events in the box are
103 * repeated for each frame. Dashed lines within this box show dependencies
104 * between these frames:
105 * - In serial mode, all the events are called in a deterministic order, with
106 * each frame completely processed before the next starts.
107 * - In parallel mode, multiple frames can be in progress simultaneously, and
108 * the events for different frames can occur even concurrently on different
109 * threads. However, frameFinishSerial() events will always occur in
110 * deterministic, sequential order for the frames. Also, the number of
111 * concurrent frames is limited by the parallelization factor passed to
112 * parallelDataStarted(): only M frames after the last frame for which
113 * frameFinishSerial() has been called can be in progress
114 *
115 * \dot
116 * digraph datamodule_events {
117 * rankdir = LR
118 * node [ shape=box ]
119 *
120 * start [ label="dataStarted()",
121 * URL="\ref gmx::IAnalysisDataModule::dataStarted()" ]
122 * pstart [ label="parallelDataStarted()",
123 * URL="\ref gmx::IAnalysisDataModule::parallelDataStarted()" ]
124 * subgraph cluster_frame {
125 * label = "for each frame"
126 * framestart [ label="frameStarted()",
127 * URL="\ref gmx::IAnalysisDataModule::frameStarted()" ]
128 * pointsadd [ label="pointsAdded()",
129 * URL="\ref gmx::IAnalysisDataModule::pointsAdded()" ]
130 * framefinish [ label="frameFinished()",
131 * URL="\ref gmx::IAnalysisDataModule::frameFinished()" ]
132 * serialfinish [ label="frameFinishedSerial()",
133 * URL="\ref gmx::IAnalysisDataModule::frameFinishedSerial()" ]
134 * }
135 * finish [ label="dataFinished()",
136 * URL="\ref gmx::IAnalysisDataModule::dataFinished()" ]
137 *
138 * start -> framestart
139 * pstart -> framestart
140 * framestart -> pointsadd
141 * pointsadd -> pointsadd [ label="0..*", dir=back ]
142 * pointsadd -> framefinish
143 * framefinish -> serialfinish
144 * serialfinish -> finish
145 *
146 * framestart:se -> serialfinish:sw [ dir=back, style=dashed, weight=0,
147 * label="serial: frame n+1\nparallel: frame n+M" ]
148 * serialfinish -> serialfinish [ dir=back, style=dashed,
149 * label="frame n+1" ]
150 * }
151 * \enddot
152 *
153 * If the input data supports parallel mode, it calls parallelDataStarted().
154 * If the module returns `true` from this method, then it will process the
155 * frames in the parallel mode. If the module returns `false`, it will get the
156 * frames in serial order.
157 * If the input data does not support parallel mode, it calls dataStarted(),
158 * and the module will always get the frames in order.
159 *
160 * The sequence of when the module methods are called with respect to when data
161 * is added to the data object depends on the type of the module and the type
162 * of the data. However, generally the modules do not need to know the details
163 * of how this happens, as long as they work with the above state diagram.
164 *
165 * For parallel processing, the gmx::AnalysisData object itself only provides
166 * the infrastructure to support all of the above, including the reordering of
167 * the frames for serial processing. However, the caller is still responsible
168 * of the actual thread synchronization, and must call
169 * gmx::AnalysisData::finishFrameSerial() for each frame from a suitable
170 * context where the serial processing for that frame can be done. When using
171 * the data objects as part of the trajectory analysis framework
172 * (\ref page_analysisframework), these calls are handled by the framework.
173 *
174 * \if libapi
175 * <H3>Writing New Data and Module Objects</H3>
176 *
177 * New data modules can be implemented to perform custom operations that are
178 * not supported by the modules provided in this module. This is done by
179 * creating a new class that implements gmx::IAnalysisDataModule.
180 * If the new module computes values that can be used as input for other
181 * modules, the new class should also derive from gmx::AbstractAnalysisData, and
182 * preferably use gmx::AnalysisDataStorage internally to implement storage of
183 * values. See the documentation of the mentioned classes for more details on
184 * how to implement custom modules.
185 * When implementing a new module, it should be considered whether it can be of
186 * more general use, and if so, it should be added to this module.
187 *
188 * It is also possible to implement new data source objects by deriving a class
189 * from gmx::AbstractAnalysisData. This should not normally be necessary, since
190 * this module provides general data source objects for most typical uses.
191 * If the classes in this module are not suitable for some specific use, it
192 * should be considered whether a new generic class could be added (or an
193 * existing extended) instead of implementing a local custom solution.
194 * \endif
195 *
196 * \author Teemu Murtola <teemu.murtola@gmail.com>
197 */
198 /*! \file
199 * \brief
200 * Public API convenience header for analysis data handling.
201 *
202 * \author Teemu Murtola <teemu.murtola@gmail.com>
203 * \inpublicapi
204 * \ingroup module_analysisdata
205 */
206 #ifndef GMX_ANALYSISDATA_H
207 #define GMX_ANALYSISDATA_H
218 #endif