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 gmx::AnalysisDataHandle.
  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  * This is the main class used to implement parallelizable data processing in
  54  * analysis tools.  It is used by first creating an object and setting its
  55  * properties using setColumnCount() and setMultipoint(), and attaching
  56  * necessary modules using addModule() etc.  Then one or more
  57  * AnalysisDataHandle objects can be created using startData().  Each data
  58  * handle can then be independently used to provide data frames (each frame
  59  * must be provided by a single handle, but different frames can be freely
  60  * mixed between the handles).  When all data has been provided, the handles
  61  * are destroyed using finishData() (or AnalysisDataHandle::finishData()).
  62  * The AnalysisData object takes care of internally sorting the frames and
  63  * passing them to the attached modules in the order in which the modules
  64  * expect them.
  65  *
  66  * \todo
  67  * Currently, multiple handles with multipoint data are not implemented.
  68  *
  69  * \todo
  70  * Parallel implementation is not complete.
  71  *
  72  * \if internal
  73  * Special note for MPI implementation: assuming that the initialization of
  74  * data objects is identical in all processes, associating the data objects
  75  * in different MPI processes should be possible without changes in the
  76  * interface.
  77  * Alternative, more robust implementation could get a unique ID as parameter
  78  * to the constructor or a separate function, but would require all tools to
  79  * provide it.  With the current registration mechanism in
  80  * TrajectoryAnalysisModule, this should be straightforward.
  81  * \endif
  82  *
  83  * \inpublicapi
  84  * \ingroup module_analysisdata
  85  */
  86 class AnalysisData : public AbstractAnalysisData
  87 {
  88     public:
  89         /*! \brief
  90          * Creates an empty analysis data object.
  91          *
  92          * \throws std::bad_alloc if out of memory.
  93          */
  94         AnalysisData();
  95         virtual ~AnalysisData();
  96
  97         /*! \brief
  98          * Sets the number of columns in the data.
  99          *
 100          * \param[in] ncol  Number of columns in the data (must be > 0).
 101          *
 102          * Must be called before startData(), and can be called multiple times
 103          * before modules are added.
 104          * Must not be called after startData() has been called.
 105          *
 106          * Does not currently throw, but this may change for the case that
 107          * modules have already been added.
 108          */
 109         void setColumnCount(int ncol);
 110         /*! \brief
 111          * Sets whether the data contains multiple points per column per frame.
 112          *
 113          * \param[in] bMultipoint  Whether the data will allow multiple points
 114          *      per column within a single frame.
 115          *
 116          * If this method is not called, the data is not multipoint.
 117          *
 118          * Must not be called after modules have been added or startData() has
 119          * been called.
 120          *
 121          * Does not currently throw, but this may change for the case that
 122          * modules have already been added.
 123          *
 124          * \see isMultipoint()
 125          */
 126         void setMultipoint(bool bMultipoint);
 127
 128         /*! \brief
 129          * Create a handle for adding data.
 130          *
 131          * \param[in]  opt     Options for setting how this handle will be
 132          *     used.
 133          * \returns The created handle.
 134          * \throws  std::bad_alloc if out of memory.
 135          * \throws  APIError if any attached data module is not compatible.
 136          * \throws  unspecified  Any exception thrown by attached data modules
 137          *      in AnalysisDataModuleInterface::dataStarted().
 138          *
 139          * The caller should retain the returned handle (or a copy of it), and
 140          * pass it to finishData() after successfully adding all data.
 141          * The caller should discard the returned handle if an error occurs;
 142          * memory allocated for the handle will be freed when the AnalysisData
 143          * object is destroyed.
 144          *
 145          * The \p opt options should be the same for all calls to this method,
 146          * and the number of calls should match the parallelization factor
 147          * defined in \p opt.
 148          */
 149         AnalysisDataHandle startData(const AnalysisDataParallelOptions &opt);
 150         /*! \brief
 151          * Destroy a handle after all data has been added.
 152          *
 153          * \param[in]  handle  Handle to destroy.
 154          * \throws  unspecified  Any exception thrown by attached data modules
 155          *      in AnalysisDataModuleInterface::dataFinished().
 156          *
 157          * \p handle must have been obtained from startData() of this object.
 158          * The order of the calls with respect to the corresponding startData()
 159          * calls is not important.
 160          *
 161          * The \p handle (and any copies) are invalid after the call.
 162          */
 163         void finishData(AnalysisDataHandle handle);
 164
 165     private:
 166         virtual AnalysisDataFrameRef tryGetDataFrameInternal(int index) const;
 167         virtual bool requestStorageInternal(int nframes);
 168
 169         class Impl;
 170
 171         PrivateImplPointer<Impl> impl_;
 172
 173         friend class AnalysisDataHandle;
 174 };
 175
 176 namespace internal
 177 {
 178 class AnalysisDataHandleImpl;
 179 } // namespace internal
 180
 181 /*! \brief
 182  * Handle for inserting data into AnalysisData.
 183  *
 184  * This class provides an interface for adding data frames into an AnalysisData
 185  * object.  After a handle is obtained from AnalysisData::startData(), new
 186  * frames can be added using startFrame().  Then values for that frame are set
 187  * using provided methods (see below), and finishFrame() is called.  After all
 188  * frames have been added, finishData() (or AnalysisData::finishData()) must be
 189  * called.
 190  *
 191  * For simple (non-multipoint) data, within a frame values can be set using
 192  * setPoint() and setPoints().  Setting the same column multiple times
 193  * overrides previously set values.  When the frame is finished, attached
 194  * modules are notified.
 195  *
 196  * Multipoint data works otherwise similarly, but requires finishPointSet() to
 197  * be called for each set of points for which the modules need to be notified.
 198  * Each point set starts empty (after startFrame() or finishPointSet()), and
 199  * values can be set using setPoint()/setPoints().  finishPointSet() must also
 200  * be called for the last point set just before finishFrame().
 201  *
 202  * This class works like a pointer type: copying and assignment is lightweight,
 203  * and all copies work interchangeably, accessing the same internal handle.
 204  * However, normally you should only keep one copy of a handle, i.e., treat
 205  * this type as movable.
 206  * Several handles created from the same AnalysisData object can exist
 207  * concurrently, but must currently operate on separate frames.
 208  *
 209  * \inpublicapi
 210  * \ingroup module_analysisdata
 211  */
 212 class AnalysisDataHandle
 213 {
 214     public:
 215         /*! \brief
 216          * Constructs an invalid data handle.
 217          *
 218          * This constructor is provided for convenience in cases where it is
 219          * easiest to declare an AnalysisDataHandle without immediately
 220          * assigning a value to it.  Any attempt to call methods without first
 221          * assigning a value from AnalysisData::startData() to the handle
 222          * causes an assert.
 223          *
 224          * Does not throw.
 225          */
 226         AnalysisDataHandle();
 227
 228         /*! \brief
 229          * Start data for a new frame.
 230          *
 231          * \param[in] index  Zero-based index for the frame to start.
 232          * \param[in] x      x value for the frame.
 233          * \param[in] dx     Error in x for the frame if applicable.
 234          *
 235          * \throws    unspecified  Any exception thrown by attached data
 236          *      modules in AnalysisDataModuleInterface::frameStarted().
 237          *
 238          * Each \p index value 0, 1, ..., N (where N is the total number of
 239          * frames) should be started exactly once by exactly one handle of an
 240          * AnalysisData object.  The frames may be started out of order, but
 241          * currently the implementation places some limitations on how far
 242          * the index can be in the future (as counted from the first frame that
 243          * is not finished).
 244          */
 245         void startFrame(int index, real x, real dx = 0.0);
 246         /*! \brief
 247          * Set a value for a single column for the current frame.
 248          *
 249          * \param[in] column  Zero-based column index.
 250          * \param[in] value   Value to set for the column.
 251          * \param[in] bPresent Present flag to set for the column.
 252          *
 253          * If called multiple times for a column (within one point set for
 254          * multipoint data), old values are overwritten.
 255          *
 256          * Does not throw.
 257          */
 258         void setPoint(int column, real value, bool bPresent = true);
 259         /*! \brief
 260          * Set a value and its error estimate for a single column for the
 261          * current frame.
 262          *
 263          * \param[in] column  Zero-based column index.
 264          * \param[in] value   Value to set for the column.
 265          * \param[in] error   Error estimate to set for the column.
 266          * \param[in] bPresent Present flag to set for the column.
 267          *
 268          * If called multiple times for a column (within one point set for
 269          * multipoint data), old values are overwritten.
 270          *
 271          * Does not throw.
 272          */
 273         void setPoint(int column, real value, real error, bool bPresent = true);
 274         /*! \brief
 275          * Set values for consecutive columns for the current frame.
 276          *
 277          * \param[in] firstColumn  Zero-based column index.
 278          * \param[in] count        Number of columns to set.
 279          * \param[in] values       Value array of \p column items.
 280          *
 281          * Equivalent to calling setPoint(firstColumn + i, values[i]) for
 282          * i from 0 to count.
 283          *
 284          * Does not throw.
 285          */
 286         void setPoints(int firstColumn, int count, const real *values);
 287         /*! \brief
 288          * Finish data for the current point set.
 289          *
 290          * \throws    APIError if any attached data module is not compatible.
 291          * \throws    unspecified  Any exception thrown by attached data
 292          *      modules in AnalysisDataModuleInterface::pointsAdded().
 293          *
 294          * Must be called after each point set for multipoint data, including
 295          * the last (i.e., no values must be set between the last call to this
 296          * method and AnalysisDataStorage::finishFrame()).
 297          * Must not be called for non-multipoint data.
 298          */
 299         void finishPointSet();
 300         /*! \brief
 301          * Finish data for the current frame.
 302          *
 303          * \throws    APIError if any attached data module is not compatible.
 304          * \throws    unspecified  Any exception thrown by attached data
 305          *      modules in frame notification methods.
 306          */
 307         void finishFrame();
 308         //! Calls AnalysisData::finishData() for this handle.
 309         void finishData();
 310
 311     private:
 312         /*! \brief
 313          * Creates a new data handle associated with \p data.
 314          *
 315          * \param  data Data to associate the handle with.
 316          *
 317          * The constructor is private because data handles should only be
 318          * constructed through AnalysisData::startData().
 319          *
 320          * Does not throw.
 321          */
 322         explicit AnalysisDataHandle(internal::AnalysisDataHandleImpl *impl);
 323
 324         /*! \brief
 325          * Pointer to the internal implementation class.
 326          *
 327          * The memory for this object is managed by the AnalysisData object,
 328          * and AnalysisDataHandle simply provides a public interface for
 329          * accessing the implementation.
 330          */
 331         internal::AnalysisDataHandleImpl *impl_;
 332
 333         /*! \brief
 334          * Needed to access the non-public implementation.
 335          */
 336         friend class AnalysisData;
 337 };
 338
 339 } // namespace gmx
 340
 341 #endif