3 * This source code is part of
7 * GROningen MAchine for Chemical Simulations
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.
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.
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.
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.
29 * For more info, check our website at http://www.gromacs.org
33 * Declares gmx::AbstractAnalysisData.
35 * \author Teemu Murtola <teemu.murtola@cbr.su.se>
37 * \ingroup module_analysisdata
39 #ifndef GMX_ANALYSISDATA_ABSTRACTDATA_H
40 #define GMX_ANALYSISDATA_ABSTRACTDATA_H
42 #include <boost/shared_ptr.hpp>
44 #include "../legacyheaders/types/simple.h"
46 #include "../utility/common.h"
51 class AnalysisDataModuleInterface;
52 class AnalysisDataFrameHeader;
53 class AnalysisDataFrameRef;
54 class AnalysisDataPointSetRef;
55 class AnalysisDataStorage;
57 //! Smart pointer for managing a generic analysis data module.
58 typedef boost::shared_ptr<AnalysisDataModuleInterface> AnalysisDataModulePointer;
61 * Abstract base class for all objects that provide data.
63 * The public interface includes methods for querying the data (isMultipoint(),
64 * columnCount(), frameCount(), tryGetDataFrame(), getDataFrame(),
65 * requestStorage()) and methods for using modules for processing the data
66 * (addModule(), addColumnModule(), applyModule()).
68 * Notice that even for non-const objects, the interface does not provide any
69 * means of altering the data. It is only possible to add modules, making it
70 * relatively safe to return a non-const pointer of this type pointing to an
71 * internal data structure without worrying about possible modifications of the
75 * This class also provides protected methods for use in derived classes.
76 * The properties returned by isMultipoint() and columnCount() must be set using
77 * setMultipoint() and setColumnCount(), and notify*() methods must be used to
78 * report when data becomes available for modules to process it.
79 * There are also two protected pure virtual methods that need to be
80 * implemented to provide access to stored data: requestStorageInternal() and
81 * tryGetDataFrameInternal().
83 * It is up to subclasses to ensure that the protected methods are called in a
84 * correct sequence (the methods will assert in most incorrect use cases), and
85 * that the data provided through the public interface matches that passed to
86 * the modules with the notify methods.
87 * Helper class AnalysisDataStorage provides a default implementation for
88 * storing data (calls to the pure virtual methods can simply be forwarded to
89 * appropriate methods in the helper class), and takes care of correctly
90 * calling the notification methods when new data is added to the storage.
91 * In most cases, it should be used to implement the derived classes.
94 * Currently, it is not possible to continue using the data object if an
95 * attached module throws an exception during data processing; it is only safe
96 * to destroy such data object.
99 * Improve the exception-handling semantics. In most cases, it doesn't make
100 * much sense to continue data processing after one module fails, but having
101 * the alternative would not hurt.
104 * \ingroup module_analysisdata
106 class AbstractAnalysisData
109 virtual ~AbstractAnalysisData();
112 * Whether the data can have multiple points in the same column
115 * \returns \c true if multiple points in the same column are
116 * allowed within a single frame.
118 * This kind of data can appear in many histogramming applications
119 * (e.g., RDFs), where each trajectory frame has several data points
120 * (possibly a different number for each frame). The current interface
121 * doesn't support storing such data, but this should rarely be
124 * The returned value does not change after modules have been notified
127 * Derived classes can change the type by calling setMultipoint()
128 * subject to the above restriction.
129 * If this is not done, the function always returns false.
134 bool isMultipoint() const { return bMultiPoint_; }
136 * Returns the number of columns in the data.
138 * \returns The number of columns in the data.
140 * If the number of columns is yet known, returns 0.
141 * The returned value does not change after modules have been notified
142 * of data start, but may change multiple times before that, depending
143 * on the actual data class.
145 * Derived classes should set the number of columns with
146 * setColumnCount(), within the above limitations.
151 int columnCount() const { return columnCount_; }
153 * Returns the total number of frames in the data.
155 * \returns The total number of frames in the data.
157 * This function returns the number of frames that the object has
158 * produced. If requestStorage() has been successfully called,
159 * tryGetDataframe() or getDataFrame() can be used to access some or
160 * all of these frames.
164 int frameCount() const;
166 * Access stored data.
168 * \param[in] index Zero-based frame index to access.
169 * \returns Frame reference to frame \p index, or an invalid
170 * reference if no such frame is available.
172 * Does not throw. Failure to access a frame with the given index is
173 * indicated through the return value. Negative \p index is allowed,
174 * and will always result in an invalid reference being returned.
176 * \see requestStorage()
177 * \see getDataFrame()
179 AnalysisDataFrameRef tryGetDataFrame(int index) const;
181 * Access stored data.
183 * \param[in] index Zero-based frame index to access.
184 * \returns Frame reference to frame \p index.
185 * \throws APIError if the requested frame is not accessible.
187 * If the data is not certainly available, use tryGetDataFrame().
189 * \see requestStorage()
190 * \see tryGetDataFrame()
192 AnalysisDataFrameRef getDataFrame(int index) const;
194 * Request storage of frames.
196 * \param[in] nframes Request storing at least \c nframes previous
197 * frames (-1 = request storing all). Must be >= -1.
198 * \returns true if the request could be satisfied.
200 * If called multiple times, the largest request is honored.
202 * Does not throw. Failure to honor the request is indicated through
205 * \see getDataFrame()
206 * \see tryGetDataFrame()
208 bool requestStorage(int nframes);
211 * Adds a module to process the data.
213 * \param module Module to add.
214 * \throws APIError if
215 * - \p module is not compatible with the data object
216 * - data has already been added to the data object and everything
217 * is not available through getDataFrame().
219 * If data has already been added to the module, the new module
220 * immediately processes all existing data. APIError is thrown
221 * if all data is not available through getDataFrame().
223 * The caller can keep a copy of the module pointer if it requires
224 * later access to the module.
226 * If the method throws, the state of the data object is not changed.
227 * The state of the data module is indeterminate.
229 void addModule(AnalysisDataModulePointer module);
231 * Adds a module that processes only a subset of the columns.
233 * \param[in] col First column.
234 * \param[in] span Number of columns.
235 * \param module Module to add.
236 * \throws APIError in same situations as addModule().
240 void addColumnModule(int col, int span, AnalysisDataModulePointer module);
242 * Applies a module to process data that is ready.
244 * \param module Module to apply.
245 * \throws APIError in same situations as addModule().
247 * This function works as addModule(), except that it does not keep a
248 * reference to \p module within the data object after it returns.
249 * Also, it can only be called after the data is ready, and only if
250 * getDataFrame() gives access to all of the data.
251 * It is provided for additional flexibility in postprocessing
255 * Currently, this method may not work correctly if \p module requests
256 * storage (addModule() has the same problem if called after data is
259 void applyModule(AnalysisDataModuleInterface *module);
264 * Initializes a new analysis data object.
266 * \throws std::bad_alloc if out of memory.
268 AbstractAnalysisData();
271 * Sets the number of columns.
273 * \param[in] columnCount Number of columns in the data (must be > 0).
275 * Can be called only before notifyDataStart(), otherwise asserts.
276 * Multiple calls are only allowed if all of them occur before
277 * addModule() has been called, otherwise asserts (a single call
278 * can occur after addModule() if no calls have been made earlier).
280 * Does not throw, but this may change with the below todo item.
283 * Consider whether the semantics with respect to addModule() and
284 * notifyDataStart(), and the performed checks, are suitable for all
289 void setColumnCount(int columnCount);
291 * Sets whether the data has multiple points per column in a frame.
293 * \param[in] multipoint Whether multiple points per column are
296 * Can be called only before addModule() or notifyDataStart(),
299 * Does not throw, but this may change with the todo item in
302 * \see isMultipoint()
304 void setMultipoint(bool multipoint);
307 * Implements access to data frames.
309 * \param[in] index Zero-based frame index to access.
310 * \returns Frame reference to frame \p index, or an invalid
311 * reference if no such frame is available.
313 * Must not throw. Failure to access a frame with the given index is
314 * indicated through the return value.
316 * Code in derived classes can assume that \p index is non-negative and
317 * less than frameCount().
319 * Derived classes can choose to return an invalid reference if
320 * requestStorageInternal() has not been called at all, or if the frame
321 * is too old (compared to the value given to requestStorageInternal()).
323 * This method is called internally by tryGetDataFrame() and
326 * \see AnalysisDataStorage
328 virtual AnalysisDataFrameRef tryGetDataFrameInternal(int index) const = 0;
330 * Implements storage requests.
332 * \param[in] nframes Request storing at least \c nframes previous
333 * frames (-1 = request storing all). Will be either -1 or >0.
334 * \returns true if the request could be satisfied.
336 * Must not throw. Failure to access a frame with the given index is
337 * indicated through the return value.
339 * Derived classes should be prepared for any number of calls to this
340 * method before notifyDataStart() is called (and during that call).
342 * This method is called internally by requestStorage().
344 * \see AnalysisDataStorage
346 virtual bool requestStorageInternal(int nframes) = 0;
349 * Notifies attached modules of the start of data.
351 * \throws APIError if any attached data module is not compatible.
352 * \throws unspecified Any exception thrown by attached data modules
353 * in AnalysisDataModuleInterface::dataStarted().
355 * Should be called once, after data properties have been set with
356 * setColumnCount() and isMultipoint(), and before any of the
357 * notification functions. The derived class should prepare for
358 * requestStorage() calls from the attached modules.
360 void notifyDataStart();
362 * Notifies attached modules of the start of a frame.
364 * \param[in] header Header information for the frame that is starting.
365 * \throws unspecified Any exception thrown by attached data modules
366 * in AnalysisDataModuleInterface::frameStarted().
368 * Should be called once for each frame, before notifyPointsAdd() calls
371 void notifyFrameStart(const AnalysisDataFrameHeader &header) const;
373 * Notifies attached modules of the addition of points to the
376 * \param[in] points Set of points added (also provides access to
378 * \throws APIError if any attached data module is not compatible.
379 * \throws unspecified Any exception thrown by attached data modules
380 * in AnalysisDataModuleInterface::pointsAdded().
382 * Can be called zero or more times for each frame.
383 * The caller should ensure that any column occurs at most once in the
384 * calls, unless the data is multipoint.
385 * For efficiency reasons, calls to this method should be aggregated
386 * whenever possible, i.e., it's better to handle multiple columns or
387 * even the whole frame in a single call rather than calling the method
388 * for each column separately.
390 void notifyPointsAdd(const AnalysisDataPointSetRef &points) const;
392 * Notifies attached modules of the end of a frame.
394 * \param[in] header Header information for the frame that is ending.
395 * \throws unspecified Any exception thrown by attached data modules
396 * in AnalysisDataModuleInterface::frameFinished().
398 * Should be called once for each call of notifyFrameStart(), after any
399 * notifyPointsAdd() calls for the frame.
400 * \p header should be identical to that used in the corresponding
401 * notifyFrameStart() call.
403 void notifyFrameFinish(const AnalysisDataFrameHeader &header);
405 * Notifies attached modules of the end of data.
407 * \throws unspecified Any exception thrown by attached data modules
408 * in AnalysisDataModuleInterface::dataFinished().
410 * Should be called once, after all the other notification calls.
412 void notifyDataFinish() const;
418 PrivateImplPointer<Impl> impl_;
423 * Needed to provide access to notification methods.
425 friend class AnalysisDataStorage;