src/gromacs/analysisdata/arraydata.h

   1 /*
   2  *
   3  *                This source code is part of
   4  *
   5  *                 G   R   O   M   A   C   S
   6  *
   7  *          GROningen MAchine for Chemical Simulations
   8  *
   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.
  13
  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.
  18  *
  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.
  25  *
  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.
  28  *
  29  * For more info, check our website at http://www.gromacs.org
  30  */
  31 /*! \file
  32  * \brief
  33  * Declares gmx::AbstractAnalysisArrayData and gmx::AnalysisArrayData.
  34  *
  35  * \author Teemu Murtola <teemu.murtola@cbr.su.se>
  36  * \inpublicapi
  37  * \ingroup module_analysisdata
  38  */
  39 #ifndef GMX_ANALYSISDATA_ARRAYDATA_H
  40 #define GMX_ANALYSISDATA_ARRAYDATA_H
  41
  42 #include <cstddef>
  43
  44 #include <vector>
  45
  46 #include "../fatalerror/gmxassert.h"
  47
  48 #include "abstractdata.h"
  49
  50 namespace gmx
  51 {
  52
  53 /*! \brief
  54  * Abstract base class for data objects that present in-memory data.
  55  *
  56  * This class implements a subclass of AbstractAnalysisData that presents an
  57  * in-memory array through the AbstractAnalysisData interface.  Subclasses
  58  * should initialize the in-memory array through the provided protected member
  59  * functions.
  60  *
  61  * \inlibraryapi
  62  * \ingroup module_analysisdata
  63  */
  64 class AbstractAnalysisArrayData : public AbstractAnalysisData
  65 {
  66     public:
  67         virtual ~AbstractAnalysisArrayData();
  68
  69         /*! \brief
  70          * Returns the number of rows in the data array.
  71          *
  72          * This function is identical to frameCount(), except that frameCount()
  73          * returns 0 before valuesReady() has been called.
  74          */
  75         int rowCount() const { return _nrows; }
  76         //! Returns true if values have been allocated.
  77         bool isAllocated() const { return !_value.empty(); }
  78         //! Returns the x value of the first frame.
  79         real xstart() const { return _xstart; }
  80         //! Returns the step between frame x values.
  81         real xstep() const { return _xstep; }
  82         //! Returns the x value of a row.
  83         real xvalue(int row) const
  84         {
  85             GMX_ASSERT(row >= 0 && row < rowCount(), "Row index out of range");
  86             return xstart() + row * xstep();
  87         }
  88         //! Returns a given array element.
  89         real value(int row, int col) const
  90         {
  91             GMX_ASSERT(row >= 0 && row < rowCount(), "Row index out of range");
  92             GMX_ASSERT(col >= 0 && col < columnCount(), "Column index out of range");
  93             GMX_ASSERT(isAllocated(), "Data array not allocated");
  94             return _value[row * columnCount() + col];
  95         }
  96
  97     protected:
  98         AbstractAnalysisArrayData();
  99
 100         /*! \brief
 101          * Sets the number of columns in the data array.
 102          *
 103          * Cannot be called after allocateValues().
 104          */
 105         void setColumnCount(int ncols);
 106         /*! \brief
 107          * Sets the number of rows in the data array.
 108          *
 109          * Cannot be called after allocateValues().
 110          */
 111         void setRowCount(int nrows);
 112         /*! \brief
 113          * Allocates memory for the values.
 114          *
 115          * setColumnCount() and setRowCount() must have been called.
 116          */
 117         void allocateValues();
 118         /*! \brief
 119          * Sets the values reported as x values for frames.
 120          */
 121         void setXAxis(real start, real step);
 122         //! Returns a reference to a given array element.
 123         real &value(int row, int col)
 124         {
 125             GMX_ASSERT(row >= 0 && row < rowCount(), "Row index out of range");
 126             GMX_ASSERT(col >= 0 && col < columnCount(), "Column index out of range");
 127             GMX_ASSERT(isAllocated(), "Data array not allocated");
 128             return _value[row * columnCount() + col];
 129         }
 130         /*! \brief
 131          * Sets the value of an element in the array.
 132          */
 133         void setValue(int row, int col, real val)
 134         {
 135             value(row, col) = val;
 136         }
 137         /*! \brief
 138          * Notifies modules of the data.
 139          *
 140          * This function should be called once the values in the array
 141          * have been initialized. The values should not be changed after this
 142          * function has been called.
 143          */
 144         void valuesReady();
 145
 146         /*! \brief
 147          * Copies the contents into a new object.
 148          *
 149          * \param[in]     src  Object to copy data from.
 150          * \param[in,out] dest Empty array data object to copy data to.
 151          *
 152          * \p dest should not have previous contents.
 153          */
 154         static void copyContents(const AbstractAnalysisArrayData *src,
 155                                  AbstractAnalysisArrayData *dest);
 156
 157     private:
 158         virtual AnalysisDataFrameRef tryGetDataFrameInternal(int index) const;
 159         virtual bool requestStorageInternal(int nframes);
 160
 161         int                  _nrows;
 162         std::vector<real>    _value;
 163         real                 _xstart;
 164         real                 _xstep;
 165         bool                 _bReady;
 166
 167         // Copy and assign disallowed by base.
 168 };
 169
 170 /*! \brief
 171  * Simple in-memory data array.
 172  *
 173  * This class simply exposes the protected functions of
 174  * AbstractAnalysisArrayData to allow construction of simple in-memory data
 175  * arrays for input into data modules.
 176  *
 177  * \inpublicapi
 178  * \ingroup module_analysisdata
 179  */
 180 class AnalysisArrayData : public AbstractAnalysisArrayData
 181 {
 182     public:
 183         AnalysisArrayData() {}
 184
 185         // TODO: These statements cause Doxygen to generate confusing
 186         // documentation.
 187         using AbstractAnalysisArrayData::setColumnCount;
 188         using AbstractAnalysisArrayData::setRowCount;
 189         using AbstractAnalysisArrayData::allocateValues;
 190         using AbstractAnalysisArrayData::setXAxis;
 191         using AbstractAnalysisArrayData::value;
 192         using AbstractAnalysisArrayData::setValue;
 193         using AbstractAnalysisArrayData::valuesReady;
 194
 195         // Copy and assign disallowed by base.
 196 };
 197
 198 } // namespace gmx
 199
 200 #endif