src/gromacs/analysisdata/abstractdata.h

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