src/gromacs/trajectoryanalysis/analysismodule.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::TrajectoryAnalysisModule and
  34  * gmx::TrajectoryAnalysisModuleData.
  35  *
  36  * \author Teemu Murtola <teemu.murtola@cbr.su.se>
  37  * \inpublicapi
  38  * \ingroup module_trajectoryanalysis
  39  */
  40 #ifndef GMX_TRAJECTORYANALYSIS_ANALYSISMODULE_H
  41 #define GMX_TRAJECTORYANALYSIS_ANALYSISMODULE_H
  42
  43 #include <string>
  44 #include <vector>
  45
  46 #include "../legacyheaders/typedefs.h"
  47
  48 #include "../selection/selection.h" // For gmx::SelectionList
  49 #include "../utility/common.h"
  50 #include "../utility/uniqueptr.h"
  51
  52 namespace gmx
  53 {
  54
  55 class AbstractAnalysisData;
  56 class AnalysisData;
  57 class AnalysisDataHandle;
  58 class AnalysisDataParallelOptions;
  59 class Options;
  60 class SelectionCollection;
  61 class TopologyInformation;
  62 class TrajectoryAnalysisModule;
  63 class TrajectoryAnalysisSettings;
  64
  65 /*! \brief
  66  * Base class for thread-local data storage during trajectory analysis.
  67  *
  68  * Thread-local storage of data handles and selections is implemented in this
  69  * class; TrajectoryAnalysisModule instances can access the thread-local values
  70  * in their TrajectoryAnalysisModule::analyzeFrame() method using dataHandle()
  71  * and parallelSelection().
  72  *
  73  * \see TrajectoryAnalysisModule::startFrames()
  74  * \see TrajectoryAnalysisModule::analyzeFrame()
  75  * \see TrajectoryAnalysisModule::finishFrames()
  76  *
  77  * \inpublicapi
  78  * \ingroup module_trajectoryanalysis
  79  */
  80 class TrajectoryAnalysisModuleData
  81 {
  82     public:
  83         virtual ~TrajectoryAnalysisModuleData();
  84
  85         /*! \brief
  86          * Performs any finishing actions after all frames have been processed.
  87          *
  88          * \throws  unspecified Implementation may throw exceptions to indicate
  89          *      errors.
  90          *
  91          * This function is called immediately before the destructor, after
  92          * TrajectoryAnalysisModule::finishFrames().
  93          * Derived classes should implement any final operations that need to
  94          * be done after successful analysis.
  95          * All implementations should call finishDataHandles().
  96          */
  97         virtual void finish() = 0;
  98
  99         /*! \brief
 100          * Returns a data handle for a given dataset.
 101          *
 102          * \param[in] data  Analysis data object.
 103          * \returns   Data handle for \p data stored in this thread-local data.
 104          *
 105          * \p data should have previously been registered with
 106          * TrajectoryAnalysisModule::registerAnalysisDataset().
 107          *
 108          * Does not throw.
 109          */
 110         AnalysisDataHandle dataHandle(const AnalysisData &data);
 111         /*! \brief
 112          * Returns a selection that corresponds to the given selection.
 113          *
 114          * \param[in] selection Global selection object.
 115          * \returns   Selection object corresponding to this thread-local data.
 116          *
 117          * \p selection is the selection object that was obtained from
 118          * SelectionOption.  The return value is the corresponding selection
 119          * in the selection collection with which this data object was
 120          * constructed with.
 121          *
 122          * Does not throw.
 123          */
 124         Selection parallelSelection(const Selection &selection);
 125         /*! \brief
 126          * Returns a set of selection that corresponds to the given selections.
 127          *
 128          * \throws std::bad_alloc if out of memory.
 129          *
 130          * Works as parallelSelection(), but for a list of selections at once.
 131          *
 132          * \see parallelSelection()
 133          */
 134         SelectionList parallelSelections(const SelectionList &selections);
 135
 136     protected:
 137         /*! \brief
 138          * Initializes thread-local storage for data handles and selections.
 139          *
 140          * \param[in] module     Analysis module to use for data objects.
 141          * \param[in] opt        Data parallelization options.
 142          * \param[in] selections Thread-local selection collection.
 143          * \throws  std::bad_alloc if out of memory.
 144          * \throws  unspecified Can throw any exception thrown by
 145          *      AnalysisData::startData().
 146          *
 147          * Calls AnalysisData::startData() on all data objects registered with
 148          * TrajectoryAnalysisModule::registerAnalysisDataset() in \p module.
 149          * The handles are accessible through dataHandle().
 150          */
 151         TrajectoryAnalysisModuleData(TrajectoryAnalysisModule *module,
 152                                      const AnalysisDataParallelOptions &opt,
 153                                      const SelectionCollection &selections);
 154
 155         /*! \brief
 156          * Calls finishData() on all data handles.
 157          *
 158          * \throws  unspecified Can throw any exception thrown by
 159          *      AnalysisDataHandle::finishData().
 160          *
 161          * This function should be called from the implementation of finish()
 162          * in all subclasses.
 163          */
 164         void finishDataHandles();
 165
 166     private:
 167         class Impl;
 168
 169         PrivateImplPointer<Impl> _impl;
 170 };
 171
 172 //! Smart pointer to manage a TrajectoryAnalysisModuleData object.
 173 typedef gmx_unique_ptr<TrajectoryAnalysisModuleData>::type
 174         TrajectoryAnalysisModuleDataPointer;
 175
 176 /*! \brief
 177  * Base class for trajectory analysis modules.
 178  *
 179  * Trajectory analysis methods should derive from this class and override the
 180  * necessary virtual methods to implement initialization (initOptions(),
 181  * initOptionsDone(), initAnalysis(), initAfterFirstFrame()), per-frame analysis
 182  * (analyzeFrame()), and final processing (finishFrames(), finishAnalysis(),
 183  * writeOutput()).
 184  *
 185  * For parallel analysis using threads, only a single object is constructed,
 186  * but the methods startFrames(), analyzeFrame() and finishFrames() are called
 187  * in each thread.  Frame-local data should be initialized in startFrames() and
 188  * stored in a class derived from TrajectoryAnalysisModuleData that is passed
 189  * to the other methods.  The default implementation of startFrames() can be
 190  * used if only data handles and selections need to be thread-local.
 191  *
 192  * To get the full benefit from this class,
 193  * \ref module_analysisdata "analysis data objects" and
 194  * \ref module_selection "selections" should be used in the implementation.
 195  * See the corresponding modules' documentation for details of how they work.
 196  *
 197  * Typical way of using AnalysisData in derived classes is to have the
 198  * AnalysisData object as a member variable and register it using
 199  * registerAnalysisDataset().  Analysis modules are initialized in
 200  * initAnalysis() and the processing chain is initialized.  If any of the
 201  * modules is required, e.g., for post-processing in finishAnalysis(), it can
 202  * be stored in a member variable.  To add data to the data object in
 203  * analyzeFrame(), a data handle is obtained using
 204  * TrajectoryAnalysisModuleData::dataHandle().
 205  *
 206  * Typical way of using selections in derived classes is to have the required
 207  * \ref Selection objects (or ::SelectionList objects) as member variables, and
 208  * add the required selection options in initOptions().  These member variables
 209  * can be accessed in initAnalysis() to get general information about the
 210  * selections.  In analyzeFrame(), these selection objects should not be used
 211  * directly, but instead TrajectoryAnalysisModuleData::parallelSelection()
 212  * should be used to obtain a selection object that works correctly also for
 213  * parallel analysis.
 214  *
 215  * Derived classes should use exceptions to indicate errors in the virtual
 216  * methods.
 217  *
 218  * \inpublicapi
 219  * \ingroup module_trajectoryanalysis
 220  */
 221 class TrajectoryAnalysisModule
 222 {
 223     public:
 224         virtual ~TrajectoryAnalysisModule();
 225
 226         /*! \brief
 227          * Initializes options understood by the module.
 228          *
 229          * \param[in,out] settings Settings to pass to and from the module.
 230          * \returns  Reference to options that are accepted by the module.
 231          *
 232          * Typical implementation returns a reference to a member variable
 233          * after first adding necessary options to that object.  Output values
 234          * from options (including selections) should be stored in member
 235          * variables.
 236          *
 237          * In addition to initializing the options, this method can also
 238          * provide information about the module's requirements using the
 239          * \p settings object; see TrajectoryAnalysisSettings for more details.
 240          *
 241          * If settings depend on the option values provided by the user, see
 242          * initOptionsDone().
 243          */
 244         virtual Options &initOptions(TrajectoryAnalysisSettings *settings) = 0;
 245         /*! \brief
 246          * Called after all option values have been set.
 247          *
 248          * \param[in,out] settings Settings to pass to and from the module.
 249          *
 250          * This method is called after option values have been assigned (but
 251          * interactive selection input has not yet been performed).
 252          *
 253          * If the module needs to change settings that affect topology loading
 254          * (can be done using the \p settings object) or selection
 255          * initialization (can be done using SelectionOptionInfo) based on
 256          * option values, this method has to be overridden.
 257          *
 258          * The default implementation does nothing.
 259          */
 260         virtual void initOptionsDone(TrajectoryAnalysisSettings *settings);
 261         /*! \brief
 262          * Initializes the analysis.
 263          *
 264          * \param[in]    settings Settings to pass to and from the module.
 265          * \param[in]    top      Topology information.
 266          *
 267          * When this function is called, selections have been initialized based
 268          * on user input, and a topology has been loaded if provided by the
 269          * user.  For dynamic selections, the selections have been evaluated to
 270          * the largest possible selection, i.e., the selections passed to
 271          * analyzeFrame() are always a subset of the selections provided here.
 272          */
 273         virtual void initAnalysis(const TrajectoryAnalysisSettings &settings,
 274                                   const TopologyInformation &top) = 0;
 275         /*! \brief
 276          * Performs additional initialization after reading the first frame.
 277          *
 278          * When this function is called, selections are the same as in
 279          * initAnalysis(), i.e., they have not been evaluated for the first
 280          * frame.
 281          *
 282          * It is necessary to override this method only if the module needs to
 283          * do initialization for which it requires data from the first frame.
 284          *
 285          * The default implementation does nothing.
 286          */
 287         virtual void initAfterFirstFrame(const t_trxframe &fr);
 288
 289         /*! \brief
 290          * Starts the analysis of frames.
 291          *
 292          * \param[in]  opt
 293          * \param[in]  selections  Frame-local selection collection object.
 294          * \returns    Data structure for thread-local data.
 295          *
 296          * This function is necessary only for threaded parallelization.
 297          * It is called once for each thread and should initialize a class that
 298          * contains any required frame-local data in the returned value.
 299          * The default implementation creates a basic data structure that holds
 300          * thread-local data handles for all data objects registered with
 301          * registerAnalysisDataset(), as well as the thread-local selection
 302          * collection.  These can be accessed in analyzeFrame() using the
 303          * methods in TrajectoryAnalysisModuleData.
 304          * If other thread-local data is needed, this function should be
 305          * overridden and it should create an instance of a class derived from
 306          * TrajectoryAnalysisModuleData.
 307          *
 308          * \see TrajectoryAnalysisModuleData
 309          */
 310         virtual TrajectoryAnalysisModuleDataPointer startFrames(
 311                 const AnalysisDataParallelOptions &opt,
 312                 const SelectionCollection &selections);
 313         /*! \brief
 314          * Analyzes a single frame.
 315          *
 316          * \param[in]     frnr   Frame number, a zero-based index that
 317          *      uniquely identifies the frame.
 318          * \param[in]     fr     Current frame.
 319          * \param[in]     pbc    Periodic boundary conditions for \p fr.
 320          * \param[in,out] pdata  Data structure for frame-local data.
 321          *
 322          * This method is called once for each frame to be analyzed, and should
 323          * analyze the positions provided in the selections.  Data handles and
 324          * selections should be obtained from the \p pdata structure.
 325          *
 326          * For threaded analysis, this method is called asynchronously in
 327          * different threads to analyze different frames.  The \p pdata
 328          * structure is one of the structures created with startFrames(),
 329          * but no assumptions should be made about which of these data
 330          * structures is used.  It is guaranteed that two instances of
 331          * analyzeFrame() are not running concurrently with the same \p pdata
 332          * data structure.
 333          * Any access to data structures not stored in \p pdata should be
 334          * designed to be thread-safe.
 335          */
 336         virtual void analyzeFrame(int frnr, const t_trxframe &fr, t_pbc *pbc,
 337                                   TrajectoryAnalysisModuleData *pdata) = 0;
 338         /*! \brief
 339          * Finishes the analysis of frames.
 340          *
 341          * \param[in]  pdata    Data structure for thread-local data.
 342          *
 343          * This method is called once for each call of startFrames(), with the
 344          * data structure returned by the corresponding startFrames().
 345          * The \p pdata object should be destroyed by the caller after this
 346          * function has been called.
 347          *
 348          * You only need to override this method if you need custom
 349          * operations to combine data from the frame-local data structures
 350          * to get the final result.  In such cases, the data should be
 351          * aggregated in this function and stored in a member attribute.
 352          *
 353          * The default implementation does nothing.
 354          *
 355          * \see startFrames()
 356          */
 357         virtual void finishFrames(TrajectoryAnalysisModuleData *pdata);
 358
 359         /*! \brief
 360          * Postprocesses data after frames have been read.
 361          *
 362          * \param[in]  nframes  Total number of frames processed.
 363          *
 364          * This function is called after all finishFrames() calls have been
 365          * called.
 366          * \p nframes will equal the number of calls to analyzeFrame() that
 367          * have occurred.
 368          */
 369         virtual void finishAnalysis(int nframes) = 0;
 370         /*! \brief
 371          * Writes output into files and/or standard output/error.
 372          *
 373          * All output from the module, excluding data written out for each
 374          * frame during analyzeFrame(), should be confined into this function.
 375          * This function is guaranteed to be called only after
 376          * finishAnalysis().
 377          */
 378         virtual void writeOutput() = 0;
 379
 380         /*! \brief
 381          * Returns the number of datasets provided by the module.
 382          *
 383          * Does not throw.
 384          */
 385         int datasetCount() const;
 386         /*! \brief
 387          * Returns a vector with the names of datasets provided by the module.
 388          *
 389          * Does not throw.
 390          */
 391         const std::vector<std::string> &datasetNames() const;
 392         /*! \brief
 393          * Returns a pointer to the data set \p index.
 394          *
 395          * \param[in] index  Data set to query for.
 396          * \returns   Reference to the requested data set.
 397          * \throws    APIError if \p index is not valid.
 398          *
 399          * \p index should be >= 0 and < datasetCount().
 400          *
 401          * The return value is not const to allow callers to add modules to the
 402          * data sets. However, the AbstractAnalysisData interface does not
 403          * provide any means to alter the data, so the module does not need to
 404          * care about external modifications.
 405          */
 406         AbstractAnalysisData &datasetFromIndex(int index) const;
 407         /*! \brief
 408          * Returns a pointer to the data set with name \p name
 409          *
 410          * \param[in] name  Data set to query for.
 411          * \returns   Reference to the requested data set.
 412          * \throws    APIError if \p name is not valid.
 413          *
 414          * \p name should be one of the names returned by datasetNames().
 415          *
 416          * The return value is not const to allow callers to add modules to the
 417          * data sets. However, the AbstractAnalysisData interface does not
 418          * provide any means to alter the data, so the module does not need to
 419          * care about external modifications.
 420          */
 421         AbstractAnalysisData &datasetFromName(const char *name) const;
 422
 423     protected:
 424         /*! \brief
 425          * Initializes the dataset registration mechanism.
 426          *
 427          * \throws std::bad_alloc if out of memory.
 428          */
 429         TrajectoryAnalysisModule();
 430
 431         /*! \brief
 432          * Registers a dataset that exports data.
 433          *
 434          * \param     data  Data object to register.
 435          * \param[in] name  Name to register the dataset with.
 436          * \throws    std::bad_alloc if out of memory.
 437          *
 438          * Registers \p data as a dataset that provides output from the
 439          * analysis module.  Callers for the module can access the dataset
 440          * with datasetFromName() using \p name as an AbstractAnalysisData
 441          * object.  This allows them to add their own data modules to do extra
 442          * processing.
 443          *
 444          * \p name must be unique across all calls within the same
 445          * TrajectoryAnalysisModule instance.
 446          */
 447         void registerBasicDataset(AbstractAnalysisData *data, const char *name);
 448         /*! \brief
 449          * Registers a parallelized dataset that exports data.
 450          *
 451          * \param     data  AnalysisData object to register.
 452          * \param[in] name  Name to register the dataset with.
 453          * \throws    std::bad_alloc if out of memory.
 454          *
 455          * This method works as registerBasicDataset(), but additionally allows
 456          * data handles for \p data to be accessed using
 457          * TrajectoryAnalysisData.
 458          *
 459          * \see registerBasicDataset()
 460          */
 461         void registerAnalysisDataset(AnalysisData *data, const char *name);
 462
 463     private:
 464         class Impl;
 465
 466         PrivateImplPointer<Impl> _impl;
 467
 468         /*! \brief
 469          * Needed to access the registered analysis data sets.
 470          */
 471         friend class TrajectoryAnalysisModuleData;
 472 };
 473
 474 //! Smart pointer to manage a TrajectoryAnalysisModule.
 475 typedef gmx_unique_ptr<TrajectoryAnalysisModule>::type
 476         TrajectoryAnalysisModulePointer;
 477
 478 } // namespace gmx
 479
 480 #endif