src/gromacs/analysisdata/abstractdata.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2010,2011,2012,2013, 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          * \todo
 243          * This method doesn't currently work in all cases with multipoint
 244          * data.  In particular, if the added module requests storage and uses
 245          * getDataFrame(), it will behave unpredictably (most likely asserts).
 246          *
 247          * \see addModule()
 248          */
 249         void addColumnModule(int col, int span, AnalysisDataModulePointer module);
 250         /*! \brief
 251          * Applies a module to process data that is ready.
 252          *
 253          * \param     module  Module to apply.
 254          * \throws    APIError in same situations as addModule().
 255          *
 256          * This function works as addModule(), except that it does not keep a
 257          * reference to \p module within the data object after it returns.
 258          * Also, it can only be called after the data is ready, and only if
 259          * getDataFrame() gives access to all of the data.
 260          * It is provided for additional flexibility in postprocessing
 261          * in-memory data.
 262          *
 263          * \todo
 264          * Currently, this method may not work correctly if \p module requests
 265          * storage (addModule() has the same problem if called after data is
 266          * started).
 267          */
 268         void applyModule(AnalysisDataModuleInterface *module);
 269
 270     protected:
 271         /*! \cond libapi */
 272         /*! \brief
 273          * Initializes a new analysis data object.
 274          *
 275          * \throws std::bad_alloc if out of memory.
 276          */
 277         AbstractAnalysisData();
 278
 279         /*! \brief
 280          * Sets the number of columns.
 281          *
 282          * \param[in] columnCount  Number of columns in the data (must be > 0).
 283          *
 284          * Can be called only before notifyDataStart(), otherwise asserts.
 285          * Multiple calls are only allowed if all of them occur before
 286          * addModule() has been called, otherwise asserts (a single call
 287          * can occur after addModule() if no calls have been made earlier).
 288          *
 289          * Does not throw, but this may change with the below todo item.
 290          *
 291          * \todo
 292          * Consider whether the semantics with respect to addModule() and
 293          * notifyDataStart(), and the performed checks, are suitable for all
 294          * purposes.
 295          *
 296          * \see columnCount()
 297          */
 298         void setColumnCount(int columnCount);
 299         /*! \brief
 300          * Sets whether the data has multiple points per column in a frame.
 301          *
 302          * \param[in] multipoint  Whether multiple points per column are
 303          *     possible.
 304          *
 305          * Can be called only before addModule() or notifyDataStart(),
 306          * otherwise asserts.
 307          *
 308          * Does not throw, but this may change with the todo item in
 309          * setColumnCount().
 310          *
 311          * \see isMultipoint()
 312          */
 313         void setMultipoint(bool multipoint);
 314
 315         /*! \brief
 316          * Implements access to data frames.
 317          *
 318          * \param[in] index  Zero-based frame index to access.
 319          * \returns   Frame reference to frame \p index, or an invalid
 320          *      reference if no such frame is available.
 321          *
 322          * Must not throw.  Failure to access a frame with the given index is
 323          * indicated through the return value.
 324          *
 325          * Code in derived classes can assume that \p index is non-negative and
 326          * less than frameCount().
 327          *
 328          * Derived classes can choose to return an invalid reference if
 329          * requestStorageInternal() has not been called at all, or if the frame
 330          * is too old (compared to the value given to requestStorageInternal()).
 331          *
 332          * This method is called internally by tryGetDataFrame() and
 333          * getDataFrame().
 334          *
 335          * \see AnalysisDataStorage
 336          */
 337         virtual AnalysisDataFrameRef tryGetDataFrameInternal(int index) const = 0;
 338         /*! \brief
 339          * Implements storage requests.
 340          *
 341          * \param[in] nframes  Request storing at least \c nframes previous
 342          *     frames (-1 = request storing all). Will be either -1 or >0.
 343          * \returns   true if the request could be satisfied.
 344          *
 345          * Must not throw.  Failure to access a frame with the given index is
 346          * indicated through the return value.
 347          *
 348          * Derived classes should be prepared for any number of calls to this
 349          * method before notifyDataStart() is called (and during that call).
 350          *
 351          * This method is called internally by requestStorage().
 352          *
 353          * \see AnalysisDataStorage
 354          */
 355         virtual bool requestStorageInternal(int nframes) = 0;
 356
 357         /*! \brief
 358          * Notifies attached modules of the start of data.
 359          *
 360          * \throws    APIError if any attached data module is not compatible.
 361          * \throws    unspecified Any exception thrown by attached data modules
 362          *      in AnalysisDataModuleInterface::dataStarted().
 363          *
 364          * Should be called once, after data properties have been set with
 365          * setColumnCount() and isMultipoint(), and before any of the
 366          * notification functions.  The derived class should prepare for
 367          * requestStorage() calls from the attached modules.
 368          */
 369         void notifyDataStart();
 370         /*! \brief
 371          * Notifies attached modules of the start of a frame.
 372          *
 373          * \param[in] header  Header information for the frame that is starting.
 374          * \throws    unspecified Any exception thrown by attached data modules
 375          *      in AnalysisDataModuleInterface::frameStarted().
 376          *
 377          * Should be called once for each frame, before notifyPointsAdd() calls
 378          * for that frame.
 379          */
 380         void notifyFrameStart(const AnalysisDataFrameHeader &header) const;
 381         /*! \brief
 382          * Notifies attached modules of the addition of points to the
 383          * current frame.
 384          *
 385          * \param[in] points  Set of points added (also provides access to
 386          *      frame-level data).
 387          * \throws    APIError if any attached data module is not compatible.
 388          * \throws    unspecified Any exception thrown by attached data modules
 389          *      in AnalysisDataModuleInterface::pointsAdded().
 390          *
 391          * Can be called zero or more times for each frame.
 392          * The caller should ensure that any column occurs at most once in the
 393          * calls, unless the data is multipoint.
 394          * For efficiency reasons, calls to this method should be aggregated
 395          * whenever possible, i.e., it's better to handle multiple columns or
 396          * even the whole frame in a single call rather than calling the method
 397          * for each column separately.
 398          */
 399         void notifyPointsAdd(const AnalysisDataPointSetRef &points) const;
 400         /*! \brief
 401          * Notifies attached modules of the end of a frame.
 402          *
 403          * \param[in] header  Header information for the frame that is ending.
 404          * \throws    unspecified Any exception thrown by attached data modules
 405          *      in AnalysisDataModuleInterface::frameFinished().
 406          *
 407          * Should be called once for each call of notifyFrameStart(), after any
 408          * notifyPointsAdd() calls for the frame.
 409          * \p header should be identical to that used in the corresponding
 410          * notifyFrameStart() call.
 411          */
 412         void notifyFrameFinish(const AnalysisDataFrameHeader &header);
 413         /*! \brief
 414          * Notifies attached modules of the end of data.
 415          *
 416          * \throws    unspecified Any exception thrown by attached data modules
 417          *      in AnalysisDataModuleInterface::dataFinished().
 418          *
 419          * Should be called once, after all the other notification calls.
 420          */
 421         void notifyDataFinish() const;
 422         //! \endcond
 423
 424     private:
 425         class Impl;
 426
 427         PrivateImplPointer<Impl> impl_;
 428         int                      columnCount_;
 429         bool                     bMultiPoint_;
 430
 431         /*! \brief
 432          * Needed to provide access to notification methods.
 433          */
 434         friend class AnalysisDataStorage;
 435 };
 436
 437 } // namespace gmx
 438
 439 #endif