2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 2010,2011,2012,2013, by the GROMACS development team, led by
5 * David van der Spoel, Berk Hess, Erik Lindahl, and including many
6 * others, as listed in the AUTHORS file in the top-level source
7 * 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.
37 * Declares gmx::AbstractAnalysisArrayData and gmx::AnalysisArrayData.
39 * \author Teemu Murtola <teemu.murtola@gmail.com>
41 * \ingroup module_analysisdata
43 #ifndef GMX_ANALYSISDATA_ARRAYDATA_H
44 #define GMX_ANALYSISDATA_ARRAYDATA_H
48 #include "../utility/gmxassert.h"
50 #include "abstractdata.h"
51 #include "dataframe.h"
57 * Abstract base class for data objects that present in-memory data.
59 * This class implements a subclass of AbstractAnalysisData that presents an
60 * in-memory array through the AbstractAnalysisData interface. Subclasses
61 * should initialize the in-memory array through the provided protected member
62 * functions. This class provides public accessor methods for read access to
65 * Public accessor methods in this class do not throw, but assert if data is
66 * accessed before it is available.
69 * Add methods to take full advantage of AnalysisDataValue features.
72 * Add support for multiple data sets.
75 * \ingroup module_analysisdata
77 class AbstractAnalysisArrayData : public AbstractAnalysisData
80 virtual ~AbstractAnalysisArrayData();
83 * Returns the number of rows in the data array.
85 * This function is identical to frameCount(), except that frameCount()
86 * returns 0 before valuesReady() has been called.
88 int rowCount() const { return rowCount_; }
89 //! Returns true if values have been allocated.
90 bool isAllocated() const { return !value_.empty(); }
91 //! Returns the x value of the first frame.
92 real xstart() const { return xstart_; }
93 //! Returns the step between frame x values.
94 real xstep() const { return xstep_; }
95 //! Returns the x value of a row.
96 real xvalue(int row) const
98 GMX_ASSERT(row >= 0 && row < rowCount(), "Row index out of range");
99 return xstart() + row * xstep();
101 //! Returns a given array element.
102 real value(int row, int col) const
104 GMX_ASSERT(row >= 0 && row < rowCount(), "Row index out of range");
105 GMX_ASSERT(col >= 0 && col < columnCount(), "Column index out of range");
106 GMX_ASSERT(isAllocated(), "Data array not allocated");
107 return value_[row * columnCount() + col].value();
112 * Initializes an empty array data object.
114 * \throws std::bad_alloc if out of memory.
116 AbstractAnalysisArrayData();
119 * Sets the number of columns in the data array.
121 * \param[in] ncols Number of columns in the data.
123 * Cannot be called after allocateValues().
125 * See AbstractAnalysisData::setColumnCount() for exception behavior.
127 void setColumnCount(int ncols);
129 * Sets the number of rows in the data array.
131 * \param[in] rowCount Number of rows in the data.
133 * Cannot be called after allocateValues().
137 void setRowCount(int rowCount);
139 * Allocates memory for the values.
141 * \throws std::bad_alloc if memory allocation fails.
143 * setColumnCount() and setRowCount() must have been called.
145 * Strong exception safety guarantee.
147 void allocateValues();
149 * Sets the values reported as x values for frames.
151 * \param[in] start x value for the first frame.
152 * \param[in] step Step between x values of successive frames.
154 * Must not be called after valuesReady().
158 void setXAxis(real start, real step);
159 //! Returns a reference to a given array element.
160 real &value(int row, int col)
162 GMX_ASSERT(row >= 0 && row < rowCount(), "Row index out of range");
163 GMX_ASSERT(col >= 0 && col < columnCount(), "Column index out of range");
164 GMX_ASSERT(isAllocated(), "Data array not allocated");
165 return value_[row * columnCount() + col].value();
168 * Sets the value of an element in the array.
170 * \param[in] row Zero-based row index for the value.
171 * \param[in] col Zero-based column index for the value.
172 * \param[in] val Value to set in the given location.
176 void setValue(int row, int col, real val)
178 value(row, col) = val;
181 * Notifies modules of the data.
183 * \throws unspecified Any exception thrown by attached data modules
184 * in data notification methods.
186 * This function should be called once the values in the array
187 * have been initialized. The values should not be changed after this
188 * function has been called.
193 * Copies the contents into a new object.
195 * \param[in] src Object to copy data from.
196 * \param[in,out] dest Empty array data object to copy data to.
197 * \throws std::bad_alloc if memory allocation for \p dest fails.
199 * \p dest should not have previous contents.
201 static void copyContents(const AbstractAnalysisArrayData *src,
202 AbstractAnalysisArrayData *dest);
205 virtual AnalysisDataFrameRef tryGetDataFrameInternal(int index) const;
206 virtual bool requestStorageInternal(int nframes);
209 AnalysisDataPointSetInfo pointSetInfo_;
210 std::vector<AnalysisDataValue> value_;
215 // Copy and assign disallowed by base.
219 * Simple in-memory data array.
221 * This class is a simple alternative to AnalysisData for in-memory data arrays
222 * that are constructed in-place.
224 * Public accessor methods in this class do not throw, but assert if data is
225 * accessed before it is available.
228 * This class exposes the protected functions of AbstractAnalysisArrayData for
233 * \ingroup module_analysisdata
235 class AnalysisArrayData : public AbstractAnalysisArrayData
239 * Initializes an empty array data object.
241 * \throws std::bad_alloc if out of memory.
243 AnalysisArrayData() {}
245 // TODO: These statements cause Doxygen to generate confusing
247 using AbstractAnalysisArrayData::setColumnCount;
248 using AbstractAnalysisArrayData::setRowCount;
249 using AbstractAnalysisArrayData::allocateValues;
250 using AbstractAnalysisArrayData::setXAxis;
251 using AbstractAnalysisArrayData::value;
252 using AbstractAnalysisArrayData::setValue;
253 using AbstractAnalysisArrayData::valuesReady;
255 // Copy and assign disallowed by base.