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::AbstractAnalysisArrayData and gmx::AnalysisArrayData.
35 * \author Teemu Murtola <teemu.murtola@cbr.su.se>
37 * \ingroup module_analysisdata
39 #ifndef GMX_ANALYSISDATA_ARRAYDATA_H
40 #define GMX_ANALYSISDATA_ARRAYDATA_H
44 #include "../fatalerror/gmxassert.h"
46 #include "abstractdata.h"
47 #include "dataframe.h"
53 * Abstract base class for data objects that present in-memory data.
55 * This class implements a subclass of AbstractAnalysisData that presents an
56 * in-memory array through the AbstractAnalysisData interface. Subclasses
57 * should initialize the in-memory array through the provided protected member
58 * functions. This class provides public accessor methods for read access to
61 * Public accessor methods in this class do not throw, but assert if data is
62 * accessed before it is available.
65 * Add methods to take full advantage of AnalysisDataValue features.
68 * \ingroup module_analysisdata
70 class AbstractAnalysisArrayData : public AbstractAnalysisData
73 virtual ~AbstractAnalysisArrayData();
76 * Returns the number of rows in the data array.
78 * This function is identical to frameCount(), except that frameCount()
79 * returns 0 before valuesReady() has been called.
81 int rowCount() const { return _nrows; }
82 //! Returns true if values have been allocated.
83 bool isAllocated() const { return !_value.empty(); }
84 //! Returns the x value of the first frame.
85 real xstart() const { return _xstart; }
86 //! Returns the step between frame x values.
87 real xstep() const { return _xstep; }
88 //! Returns the x value of a row.
89 real xvalue(int row) const
91 GMX_ASSERT(row >= 0 && row < rowCount(), "Row index out of range");
92 return xstart() + row * xstep();
94 //! Returns a given array element.
95 real value(int row, int col) const
97 GMX_ASSERT(row >= 0 && row < rowCount(), "Row index out of range");
98 GMX_ASSERT(col >= 0 && col < columnCount(), "Column index out of range");
99 GMX_ASSERT(isAllocated(), "Data array not allocated");
100 return _value[row * columnCount() + col].value();
105 * Initializes an empty array data object.
107 * \throws std::bad_alloc if out of memory.
109 AbstractAnalysisArrayData();
112 * Sets the number of columns in the data array.
114 * \param[in] ncols Number of columns in the data.
116 * Cannot be called after allocateValues().
118 * See AbstractAnalysisData::setColumnCount() for exception behavior.
120 void setColumnCount(int ncols);
122 * Sets the number of rows in the data array.
124 * \param[in] nrows Number of rows in the data.
126 * Cannot be called after allocateValues().
130 void setRowCount(int nrows);
132 * Allocates memory for the values.
134 * \throws std::bad_alloc if memory allocation fails.
136 * setColumnCount() and setRowCount() must have been called.
138 * Strong exception safety guarantee.
140 void allocateValues();
142 * Sets the values reported as x values for frames.
144 * \param[in] start x value for the first frame.
145 * \param[in] step Step between x values of successive frames.
147 * Must not be called after valuesReady().
151 void setXAxis(real start, real step);
152 //! Returns a reference to a given array element.
153 real &value(int row, int col)
155 GMX_ASSERT(row >= 0 && row < rowCount(), "Row index out of range");
156 GMX_ASSERT(col >= 0 && col < columnCount(), "Column index out of range");
157 GMX_ASSERT(isAllocated(), "Data array not allocated");
158 return _value[row * columnCount() + col].value();
161 * Sets the value of an element in the array.
163 * \param[in] row Zero-based row index for the value.
164 * \param[in] col Zero-based column index for the value.
165 * \param[in] val Value to set in the given location.
169 void setValue(int row, int col, real val)
171 value(row, col) = val;
174 * Notifies modules of the data.
176 * \throws unspecified Any exception thrown by attached data modules
177 * in data notification methods.
179 * This function should be called once the values in the array
180 * have been initialized. The values should not be changed after this
181 * function has been called.
186 * Copies the contents into a new object.
188 * \param[in] src Object to copy data from.
189 * \param[in,out] dest Empty array data object to copy data to.
190 * \throws std::bad_alloc if memory allocation for \p dest fails.
192 * \p dest should not have previous contents.
194 static void copyContents(const AbstractAnalysisArrayData *src,
195 AbstractAnalysisArrayData *dest);
198 virtual AnalysisDataFrameRef tryGetDataFrameInternal(int index) const;
199 virtual bool requestStorageInternal(int nframes);
202 std::vector<AnalysisDataValue> _value;
207 // Copy and assign disallowed by base.
211 * Simple in-memory data array.
213 * This class is a simple alternative to AnalysisData for in-memory data arrays
214 * that are constructed in-place.
216 * Public accessor methods in this class do not throw, but assert if data is
217 * accessed before it is available.
220 * This class exposes the protected functions of AbstractAnalysisArrayData for
225 * \ingroup module_analysisdata
227 class AnalysisArrayData : public AbstractAnalysisArrayData
231 * Initializes an empty array data object.
233 * \throws std::bad_alloc if out of memory.
235 AnalysisArrayData() {}
237 // TODO: These statements cause Doxygen to generate confusing
239 using AbstractAnalysisArrayData::setColumnCount;
240 using AbstractAnalysisArrayData::setRowCount;
241 using AbstractAnalysisArrayData::allocateValues;
242 using AbstractAnalysisArrayData::setXAxis;
243 using AbstractAnalysisArrayData::value;
244 using AbstractAnalysisArrayData::setValue;
245 using AbstractAnalysisArrayData::valuesReady;
247 // Copy and assign disallowed by base.