2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 2010,2011,2012,2013,2014 by the GROMACS development team.
5 * Copyright (c) 2018,2019,2020, by the GROMACS development team, led by
6 * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
7 * and including many others, as listed in the AUTHORS file in the
8 * top-level source directory and at http://www.gromacs.org.
10 * GROMACS is free software; you can redistribute it and/or
11 * modify it under the terms of the GNU Lesser General Public License
12 * as published by the Free Software Foundation; either version 2.1
13 * of the License, or (at your option) any later version.
15 * GROMACS is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 * Lesser General Public License for more details.
20 * You should have received a copy of the GNU Lesser General Public
21 * License along with GROMACS; if not, see
22 * http://www.gnu.org/licenses, or write to the Free Software Foundation,
23 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
25 * If you want to redistribute modifications to GROMACS, please
26 * consider that scientific software is very special. Version
27 * control is crucial - bugs must be traceable. We will be happy to
28 * consider code for inclusion in the official distribution, but
29 * derived work must not be called official GROMACS. Details are found
30 * in the README & COPYING files - if they are missing, get the
31 * official version at http://www.gromacs.org.
33 * To help us fund GROMACS development, we humbly ask that you cite
34 * the research papers on the package. Check out http://www.gromacs.org.
38 * Declares gmx::AbstractAnalysisArrayData and gmx::AnalysisArrayData.
40 * \author Teemu Murtola <teemu.murtola@gmail.com>
42 * \ingroup module_analysisdata
44 #ifndef GMX_ANALYSISDATA_ARRAYDATA_H
45 #define GMX_ANALYSISDATA_ARRAYDATA_H
49 #include "gromacs/analysisdata/abstractdata.h"
50 #include "gromacs/analysisdata/dataframe.h"
51 #include "gromacs/utility/gmxassert.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 support for multiple data sets.
72 * \ingroup module_analysisdata
74 class AbstractAnalysisArrayData : public AbstractAnalysisData
77 ~AbstractAnalysisArrayData() override;
79 int frameCount() const override { return bReady_ ? rowCount_ : 0; }
82 * Returns the number of rows in the data array.
84 * This function is identical to frameCount(), except that frameCount()
85 * returns 0 before valuesReady() has been called.
87 int rowCount() const { return rowCount_; }
88 //! Returns true if values have been allocated.
89 bool isAllocated() const { return !value_.empty(); }
90 //! Returns the x value of the first frame.
91 real xstart() const { return xvalue_[0]; }
92 //! Returns the step between frame x values.
95 GMX_ASSERT(bUniformX_, "Accessing x step for non-uniform data");
98 //! Returns the x value of a row.
99 real xvalue(int row) const
101 GMX_ASSERT(row >= 0 && row < rowCount(), "Row index out of range");
104 //! Returns a given array element.
105 const AnalysisDataValue& value(int row, int col) const
107 GMX_ASSERT(row >= 0 && row < rowCount(), "Row index out of range");
108 GMX_ASSERT(col >= 0 && col < columnCount(), "Column index out of range");
109 GMX_ASSERT(isAllocated(), "Data array not allocated");
110 return value_[row * columnCount() + col];
115 * Initializes an empty array data object.
117 * \throws std::bad_alloc if out of memory.
119 AbstractAnalysisArrayData();
122 * Sets the number of columns in the data array.
124 * \param[in] ncols Number of columns in the data.
126 * Cannot be called after allocateValues().
128 * See AbstractAnalysisData::setColumnCount() for exception behavior.
130 void setColumnCount(int ncols);
132 * Sets the number of rows in the data array.
134 * \param[in] rowCount Number of rows in the data.
136 * Cannot be called after allocateValues().
140 void setRowCount(int rowCount);
142 * Allocates memory for the values.
144 * \throws std::bad_alloc if memory allocation fails.
146 * setColumnCount() and setRowCount() must have been called.
148 * Strong exception safety guarantee.
150 void allocateValues();
152 * Sets the values reported as x values for frames.
154 * \param[in] start x value for the first frame.
155 * \param[in] step Step between x values of successive frames.
157 * Must not be called after valuesReady().
158 * Any values set with setXAxisValue() are overwritten.
162 void setXAxis(real start, real step);
164 * Sets a single value reported as x value for frames.
166 * \param[in] row Row/frame for which to set the value.
167 * \param[in] value x value for the frame specified by \p row.
169 * Must not be called after valuesReady().
173 void setXAxisValue(int row, real value);
174 //! Returns a reference to a given array element.
175 AnalysisDataValue& value(int row, int col)
177 GMX_ASSERT(row >= 0 && row < rowCount(), "Row index out of range");
178 GMX_ASSERT(col >= 0 && col < columnCount(), "Column index out of range");
179 GMX_ASSERT(isAllocated(), "Data array not allocated");
180 return value_[row * columnCount() + col];
183 * Notifies modules of the data.
185 * \throws unspecified Any exception thrown by attached data modules
186 * in data notification methods.
188 * This function should be called once the values in the array
189 * have been initialized. The values should not be changed after this
190 * function has been called.
195 * Copies the contents into a new object.
197 * \param[in] src Object to copy data from.
198 * \param[in,out] dest Empty array data object to copy data to.
199 * \throws std::bad_alloc if memory allocation for \p dest fails.
201 * \p dest should not have previous contents.
203 static void copyContents(const AbstractAnalysisArrayData* src, AbstractAnalysisArrayData* dest);
206 AnalysisDataFrameRef tryGetDataFrameInternal(int index) const override;
207 bool requestStorageInternal(int nframes) override;
210 AnalysisDataPointSetInfo pointSetInfo_;
211 std::vector<AnalysisDataValue> value_;
212 std::vector<real> xvalue_;
217 // Copy and assign disallowed by base.
221 * Simple in-memory data array.
223 * This class is a simple alternative to AnalysisData for in-memory data arrays
224 * that are constructed in-place.
226 * Public accessor methods in this class do not throw, but assert if data is
227 * accessed before it is available.
230 * This class exposes the protected functions of AbstractAnalysisArrayData for
235 * \ingroup module_analysisdata
237 class AnalysisArrayData : public AbstractAnalysisArrayData
241 * Initializes an empty array data object.
243 * \throws std::bad_alloc if out of memory.
245 AnalysisArrayData() {}
247 // TODO: These statements cause Doxygen to generate confusing
249 using AbstractAnalysisArrayData::allocateValues;
250 using AbstractAnalysisArrayData::setColumnCount;
251 using AbstractAnalysisArrayData::setRowCount;
252 using AbstractAnalysisArrayData::setXAxis;
253 using AbstractAnalysisArrayData::setXAxisValue;
254 using AbstractAnalysisArrayData::value;
255 using AbstractAnalysisArrayData::valuesReady;
257 // Copy and assign disallowed by base.