src/gromacs/analysisdata/analysisdata.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::AnalysisData and related classes.
  34  *
  35  * \author Teemu Murtola <teemu.murtola@cbr.su.se>
  36  * \inpublicapi
  37  * \ingroup module_analysisdata
  38  */
  39 #ifndef GMX_ANALYSISDATA_ANALYSISDATA_H
  40 #define GMX_ANALYSISDATA_ANALYSISDATA_H
  41
  42 #include "abstractdata.h"
  43
  44 namespace gmx
  45 {
  46
  47 class AnalysisDataHandle;
  48 class AnalysisDataParallelOptions;
  49
  50 /*! \brief
  51  * Parallelizable data container for raw data.
  52  *
  53  * \if internal
  54  * Special note for MPI implementation: assuming that the initialization of
  55  * data objects is identical in all processes, associating the data objects
  56  * in different MPI processes should be possible without changes in the
  57  * interface.
  58  * Alternative, more robust implementation could get a unique ID as parameter
  59  * to the constructor or a separate function, but would require all tools to
  60  * provide it.
  61  * \endif
  62  *
  63  * \inpublicapi
  64  * \ingroup module_analysisdata
  65  */
  66 class AnalysisData : public AbstractAnalysisData
  67 {
  68     public:
  69         //! Creates an empty analysis data object.
  70         AnalysisData();
  71         virtual ~AnalysisData();
  72
  73         /*! \brief
  74          * Sets the number of columns in the data.
  75          */
  76         void setColumnCount(int ncol);
  77         /*! \brief
  78          * Sets whether the data contains multiple points per column per frame.
  79          *
  80          * \see isMultipoint()
  81          */
  82         void setMultipoint(bool bMultipoint);
  83
  84         /*! \brief
  85          * Create a handle for adding data.
  86          *
  87          * \param[in]  opt     Options for setting how this handle will be
  88          *     used.
  89          * \returns The created handle.
  90          *
  91          * The caller should retain the returned handle (or a copy of it), and
  92          * pass it to finishData() after successfully adding all data.
  93          * The caller should discard the returned handle if an error occurs;
  94          * memory allocated for the handle will be freed when the AnalysisData
  95          * object is destroyed.
  96          */
  97         AnalysisDataHandle startData(const AnalysisDataParallelOptions &opt);
  98         /*! \brief
  99          * Destroy a handle after all data has been added.
 100          *
 101          * \param[in]  handle  Handle to destroy.
 102          *
 103          * The \p handle (and any copies) are invalid after the call.
 104          */
 105         void finishData(AnalysisDataHandle handle);
 106
 107     private:
 108         virtual AnalysisDataFrameRef tryGetDataFrameInternal(int index) const;
 109         virtual bool requestStorageInternal(int nframes);
 110
 111         class Impl;
 112
 113         PrivateImplPointer<Impl> impl_;
 114
 115         friend class AnalysisDataHandle;
 116 };
 117
 118 namespace internal
 119 {
 120 class AnalysisDataHandleImpl;
 121 } // namespace internal
 122
 123 /*! \brief
 124  * Handle for inserting data into AnalysisData.
 125  *
 126  * This class works like a pointer type: copying and assignment is lightweight,
 127  * and all copies work interchangeably, accessing the same internal handle.
 128  *
 129  * Several handles can exist concurrently.
 130  *
 131  * \inpublicapi
 132  * \ingroup module_analysisdata
 133  */
 134 class AnalysisDataHandle
 135 {
 136     public:
 137         /*! \brief
 138          * Constructs an invalid data handle.
 139          *
 140          * This constructor is provided for convenience in cases where it is
 141          * easiest to declare an AnalysisDataHandle without immediately
 142          * assigning a value to it.  Any attempt to call methods without first
 143          * assigning a value from AnalysisData::startData() to the handle
 144          * causes an assert.
 145          */
 146         AnalysisDataHandle();
 147
 148         //! Start data for a new frame.
 149         void startFrame(int index, real x, real dx = 0.0);
 150         //! Set a value for a single column for the current frame.
 151         void setPoint(int col, real y, real dy = 0.0, bool present = true);
 152         //! Set values for consecutive columns for the current frame.
 153         void setPoints(int firstcol, int n, const real *y);
 154         //! Finish data for the current point set.
 155         void finishPointSet();
 156         //! Finish data for the current frame.
 157         void finishFrame();
 158         //! Calls AnalysisData::finishData() for this handle.
 159         void finishData();
 160
 161     private:
 162         /*! \brief
 163          * Creates a new data handle associated with \p data.
 164          *
 165          * \param  data Data to associate the handle with.
 166          *
 167          * The constructor is private because data handles should only be
 168          * constructed through AnalysisData::startData().
 169          */
 170         explicit AnalysisDataHandle(internal::AnalysisDataHandleImpl *impl);
 171
 172         /*! \brief
 173          * Pointer to the internal implementation class.
 174          *
 175          * The memory for this object is managed by the AnalysisData object,
 176          * and AnalysisDataHandle simply provides a public interface for
 177          * accessing the implementation.
 178          */
 179         internal::AnalysisDataHandleImpl *impl_;
 180
 181         friend class AnalysisData;
 182 };
 183
 184 } // namespace gmx
 185
 186 #endif