src/gromacs/analysisdata/abstractdata.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::AbstractAnalysisData.
  34  *
  35  * \author Teemu Murtola <teemu.murtola@cbr.su.se>
  36  * \inlibraryapi
  37  * \ingroup module_analysisdata
  38  */
  39 #ifndef GMX_ANALYSISDATA_ABSTRACTDATA_H
  40 #define GMX_ANALYSISDATA_ABSTRACTDATA_H
  41
  42 #include <boost/shared_ptr.hpp>
  43
  44 #include "../legacyheaders/types/simple.h"
  45
  46 #include "../utility/common.h"
  47
  48 namespace gmx
  49 {
  50
  51 class AnalysisDataModuleInterface;
  52 class AnalysisDataFrameHeader;
  53 class AnalysisDataFrameRef;
  54 class AnalysisDataPointSetRef;
  55 class AnalysisDataStorage;
  56
  57 //! Smart pointer for managing a generic analysis data module.
  58 typedef boost::shared_ptr<AnalysisDataModuleInterface> AnalysisDataModulePointer;
  59
  60 /*! \brief
  61  * Abstract base class for all objects that provide data.
  62  *
  63  * The public interface includes methods for querying the data (isMultipoint(),
  64  * columnCount(), frameCount(), tryGetDataFrame(), getDataFrame(),
  65  * requestStorage()) and methods for using modules for processing the data
  66  * (addModule(), addColumnModule(), applyModule()).
  67  *
  68  * Notice that even for non-const objects, the interface does not provide any
  69  * means of altering the data.  It is only possible to add modules, making it
  70  * relatively safe to return a non-const pointer of this type pointing to an
  71  * internal data structure without worrying about possible modifications of the
  72  * data.
  73  *
  74  * \if libapi
  75  * This class also provides protected methods for use in derived classes.
  76  * The properties returned by isMultipoint() and columnCount() must be set using
  77  * setMultipoint() and setColumnCount(), and notify*() methods must be used to
  78  * report when data becomes available for modules to process it.
  79  * There are also two protected pure virtual methods that need to be
  80  * implemented to provide access to stored data: requestStorageInternal() and
  81  * tryGetDataFrameInternal().
  82  *
  83  * It is up to subclasses to ensure that the protected methods are called in a
  84  * correct sequence (the methods will assert in most incorrect use cases), and
  85  * that the data provided through the public interface matches that passed to
  86  * the modules with the notify methods.
  87  * Helper class AnalysisDataStorage provides a default implementation for
  88  * storing data (calls to the pure virtual methods can simply be forwarded to
  89  * appropriate methods in the helper class), and takes care of correctly
  90  * calling the notification methods when new data is added to the storage.
  91  * In most cases, it should be used to implement the derived classes.
  92  * \endif
  93  *
  94  * Currently, it is not possible to continue using the data object if an
  95  * attached module throws an exception during data processing; it is only safe
  96  * to destroy such data object.
  97  *
  98  * \todo
  99  * Improve the exception-handling semantics.  In most cases, it doesn't make
 100  * much sense to continue data processing after one module fails, but having
 101  * the alternative would not hurt.
 102  *
 103  * \inlibraryapi
 104  * \ingroup module_analysisdata
 105  */
 106 class AbstractAnalysisData
 107 {
 108     public:
 109         virtual ~AbstractAnalysisData();
 110
 111         /*! \brief
 112          * Whether the data can have multiple points in the same column
 113          * in the same frame.
 114          *
 115          * \returns \c true if multiple points in the same column are
 116          *     allowed within a single frame.
 117          *
 118          * This kind of data can appear in many histogramming applications
 119          * (e.g., RDFs), where each trajectory frame has several data points
 120          * (possibly a different number for each frame). The current interface
 121          * doesn't support storing such data, but this should rarely be
 122          * necessary.
 123          *
 124          * The returned value does not change after modules have been notified
 125          * of data start.
 126          * \if libapi
 127          * Derived classes can change the type by calling setMultipoint()
 128          * subject to the above restriction.
 129          * If this is not done, the function always returns false.
 130          * \endif
 131          *
 132          * Does not throw.
 133          */
 134         bool isMultipoint() const { return bMultiPoint_; }
 135         /*! \brief
 136          * Returns the number of columns in the data.
 137          *
 138          * \returns The number of columns in the data.
 139          *
 140          * If the number of columns is yet known, returns 0.
 141          * The returned value does not change after modules have been notified
 142          * of data start, but may change multiple times before that, depending
 143          * on the actual data class.
 144          * \if libapi
 145          * Derived classes should set the number of columns with
 146          * setColumnCount(), within the above limitations.
 147          * \endif
 148          *
 149          * Does not throw.
 150          */
 151         int columnCount() const { return columnCount_; }
 152         /*! \brief
 153          * Returns the total number of frames in the data.
 154          *
 155          * \returns The total number of frames in the data.
 156          *
 157          * This function returns the number of frames that the object has
 158          * produced.  If requestStorage() has been successfully called,
 159          * tryGetDataframe() or getDataFrame() can be used to access some or
 160          * all of these frames.
 161          *
 162          * Does not throw.
 163          */
 164         int frameCount() const;
 165         /*! \brief
 166          * Access stored data.
 167          *
 168          * \param[in] index  Zero-based frame index to access.
 169          * \returns   Frame reference to frame \p index, or an invalid
 170          *      reference if no such frame is available.
 171          *
 172          * Does not throw.  Failure to access a frame with the given index is
 173          * indicated through the return value.  Negative \p index is allowed,
 174          * and will always result in an invalid reference being returned.
 175          *
 176          * \see requestStorage()
 177          * \see getDataFrame()
 178          */
 179         AnalysisDataFrameRef tryGetDataFrame(int index) const;
 180         /*! \brief
 181          * Access stored data.
 182          *
 183          * \param[in] index  Zero-based frame index to access.
 184          * \returns   Frame reference to frame \p index.
 185          * \throws    APIError if the requested frame is not accessible.
 186          *
 187          * If the data is not certainly available, use tryGetDataFrame().
 188          *
 189          * \see requestStorage()
 190          * \see tryGetDataFrame()
 191          */
 192         AnalysisDataFrameRef getDataFrame(int index) const;
 193         /*! \brief
 194          * Request storage of frames.
 195          *
 196          * \param[in] nframes  Request storing at least \c nframes previous
 197          *     frames (-1 = request storing all). Must be >= -1.
 198          * \returns true if the request could be satisfied.
 199          *
 200          * If called multiple times, the largest request is honored.
 201          *
 202          * Does not throw.  Failure to honor the request is indicated through
 203          * the return value.
 204          *
 205          * \see getDataFrame()
 206          * \see tryGetDataFrame()
 207          */
 208         bool requestStorage(int nframes);
 209
 210         /*! \brief
 211          * Adds a module to process the data.
 212          *
 213          * \param     module  Module to add.
 214          * \throws    APIError if
 215          *      - \p module is not compatible with the data object
 216          *      - data has already been added to the data object and everything
 217          *        is not available through getDataFrame().
 218          *
 219          * If data has already been added to the module, the new module
 220          * immediately processes all existing data.  APIError is thrown
 221          * if all data is not available through getDataFrame().
 222          *
 223          * The caller can keep a copy of the module pointer if it requires
 224          * later access to the module.
 225          *
 226          * If the method throws, the state of the data object is not changed.
 227          * The state of the data module is indeterminate.
 228          */
 229         void addModule(AnalysisDataModulePointer module);
 230         /*! \brief
 231          * Adds a module that processes only a subset of the columns.
 232          *
 233          * \param[in] col     First column.
 234          * \param[in] span    Number of columns.
 235          * \param     module  Module to add.
 236          * \throws    APIError in same situations as addModule().
 237          *
 238          * \see addModule()
 239          */
 240         void addColumnModule(int col, int span, AnalysisDataModulePointer module);
 241         /*! \brief
 242          * Applies a module to process data that is ready.
 243          *
 244          * \param     module  Module to apply.
 245          * \throws    APIError in same situations as addModule().
 246          *
 247          * This function works as addModule(), except that it does not keep a
 248          * reference to \p module within the data object after it returns.
 249          * Also, it can only be called after the data is ready, and only if
 250          * getDataFrame() gives access to all of the data.
 251          * It is provided for additional flexibility in postprocessing
 252          * in-memory data.
 253          *
 254          * \todo
 255          * Currently, this method may not work correctly if \p module requests
 256          * storage (addModule() has the same problem if called after data is
 257          * started).
 258          */
 259         void applyModule(AnalysisDataModuleInterface *module);
 260
 261     protected:
 262         /*! \cond libapi */
 263         /*! \brief
 264          * Initializes a new analysis data object.
 265          *
 266          * \throws std::bad_alloc if out of memory.
 267          */
 268         AbstractAnalysisData();
 269
 270         /*! \brief
 271          * Sets the number of columns.
 272          *
 273          * \param[in] columnCount  Number of columns in the data (must be > 0).
 274          *
 275          * Can be called only before notifyDataStart(), otherwise asserts.
 276          * Multiple calls are only allowed if all of them occur before
 277          * addModule() has been called, otherwise asserts (a single call
 278          * can occur after addModule() if no calls have been made earlier).
 279          *
 280          * Does not throw, but this may change with the below todo item.
 281          *
 282          * \todo
 283          * Consider whether the semantics with respect to addModule() and
 284          * notifyDataStart(), and the performed checks, are suitable for all
 285          * purposes.
 286          *
 287          * \see columnCount()
 288          */
 289         void setColumnCount(int columnCount);
 290         /*! \brief
 291          * Sets whether the data has multiple points per column in a frame.
 292          *
 293          * \param[in] multipoint  Whether multiple points per column are
 294          *     possible.
 295          *
 296          * Can be called only before addModule() or notifyDataStart(),
 297          * otherwise asserts.
 298          *
 299          * Does not throw, but this may change with the todo item in
 300          * setColumnCount().
 301          *
 302          * \see isMultipoint()
 303          */
 304         void setMultipoint(bool multipoint);
 305
 306         /*! \brief
 307          * Implements access to data frames.
 308          *
 309          * \param[in] index  Zero-based frame index to access.
 310          * \returns   Frame reference to frame \p index, or an invalid
 311          *      reference if no such frame is available.
 312          *
 313          * Must not throw.  Failure to access a frame with the given index is
 314          * indicated through the return value.
 315          *
 316          * Code in derived classes can assume that \p index is non-negative and
 317          * less than frameCount().
 318          *
 319          * Derived classes can choose to return an invalid reference if
 320          * requestStorageInternal() has not been called at all, or if the frame
 321          * is too old (compared to the value given to requestStorageInternal()).
 322          *
 323          * This method is called internally by tryGetDataFrame() and
 324          * getDataFrame().
 325          *
 326          * \see AnalysisDataStorage
 327          */
 328         virtual AnalysisDataFrameRef tryGetDataFrameInternal(int index) const = 0;
 329         /*! \brief
 330          * Implements storage requests.
 331          *
 332          * \param[in] nframes  Request storing at least \c nframes previous
 333          *     frames (-1 = request storing all). Will be either -1 or >0.
 334          * \returns   true if the request could be satisfied.
 335          *
 336          * Must not throw.  Failure to access a frame with the given index is
 337          * indicated through the return value.
 338          *
 339          * Derived classes should be prepared for any number of calls to this
 340          * method before notifyDataStart() is called (and during that call).
 341          *
 342          * This method is called internally by requestStorage().
 343          *
 344          * \see AnalysisDataStorage
 345          */
 346         virtual bool requestStorageInternal(int nframes) = 0;
 347
 348         /*! \brief
 349          * Notifies attached modules of the start of data.
 350          *
 351          * \throws    APIError if any attached data module is not compatible.
 352          * \throws    unspecified Any exception thrown by attached data modules
 353          *      in AnalysisDataModuleInterface::dataStarted().
 354          *
 355          * Should be called once, after data properties have been set with
 356          * setColumnCount() and isMultipoint(), and before any of the
 357          * notification functions.  The derived class should prepare for
 358          * requestStorage() calls from the attached modules.
 359          */
 360         void notifyDataStart();
 361         /*! \brief
 362          * Notifies attached modules of the start of a frame.
 363          *
 364          * \param[in] header  Header information for the frame that is starting.
 365          * \throws    unspecified Any exception thrown by attached data modules
 366          *      in AnalysisDataModuleInterface::frameStarted().
 367          *
 368          * Should be called once for each frame, before notifyPointsAdd() calls
 369          * for that frame.
 370          */
 371         void notifyFrameStart(const AnalysisDataFrameHeader &header) const;
 372         /*! \brief
 373          * Notifies attached modules of the addition of points to the
 374          * current frame.
 375          *
 376          * \param[in] points  Set of points added (also provides access to
 377          *      frame-level data).
 378          * \throws    APIError if any attached data module is not compatible.
 379          * \throws    unspecified Any exception thrown by attached data modules
 380          *      in AnalysisDataModuleInterface::pointsAdded().
 381          *
 382          * Can be called zero or more times for each frame.
 383          * The caller should ensure that any column occurs at most once in the
 384          * calls, unless the data is multipoint.
 385          * For efficiency reasons, calls to this method should be aggregated
 386          * whenever possible, i.e., it's better to handle multiple columns or
 387          * even the whole frame in a single call rather than calling the method
 388          * for each column separately.
 389          */
 390         void notifyPointsAdd(const AnalysisDataPointSetRef &points) const;
 391         /*! \brief
 392          * Notifies attached modules of the end of a frame.
 393          *
 394          * \param[in] header  Header information for the frame that is ending.
 395          * \throws    unspecified Any exception thrown by attached data modules
 396          *      in AnalysisDataModuleInterface::frameFinished().
 397          *
 398          * Should be called once for each call of notifyFrameStart(), after any
 399          * notifyPointsAdd() calls for the frame.
 400          * \p header should be identical to that used in the corresponding
 401          * notifyFrameStart() call.
 402          */
 403         void notifyFrameFinish(const AnalysisDataFrameHeader &header);
 404         /*! \brief
 405          * Notifies attached modules of the end of data.
 406          *
 407          * \throws    unspecified Any exception thrown by attached data modules
 408          *      in AnalysisDataModuleInterface::dataFinished().
 409          *
 410          * Should be called once, after all the other notification calls.
 411          */
 412         void notifyDataFinish() const;
 413         //! \endcond
 414
 415     private:
 416         class Impl;
 417
 418         PrivateImplPointer<Impl> impl_;
 419         int                     columnCount_;
 420         bool                    bMultiPoint_;
 421
 422         /*! \brief
 423          * Needed to provide access to notification methods.
 424          */
 425         friend class AnalysisDataStorage;
 426 };
 427
 428 } // namespace gmx
 429
 430 #endif