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  * optionsFinished(), 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] options  Options object to add the options to.
 230          * \param[in,out] settings Settings to pass to and from the module.
 231          *
 232          * This method is called first after the constructor, and it should
 233          * add options understood by the module to \p options.  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          * optionsFinished().
 243          */
 244         virtual void initOptions(Options                    *options,
 245                                  TrajectoryAnalysisSettings *settings) = 0;
 246         /*! \brief
 247          * Called after all option values have been set.
 248          *
 249          * \param[in,out] options  Options object in which options are stored.
 250          * \param[in,out] settings Settings to pass to and from the module.
 251          *
 252          * This method is called after option values have been assigned (but
 253          * interactive selection input has not yet been performed).
 254          *
 255          * If the module needs to change settings that affect topology loading
 256          * (can be done using the \p settings object) or selection
 257          * initialization (can be done using SelectionOptionInfo) based on
 258          * option values, this method has to be overridden.
 259          *
 260          * The default implementation does nothing.
 261          */
 262         virtual void optionsFinished(Options                    *options,
 263                                      TrajectoryAnalysisSettings *settings);
 264         /*! \brief
 265          * Initializes the analysis.
 266          *
 267          * \param[in]    settings Settings to pass to and from the module.
 268          * \param[in]    top      Topology information.
 269          *
 270          * When this function is called, selections have been initialized based
 271          * on user input, and a topology has been loaded if provided by the
 272          * user.  For dynamic selections, the selections have been evaluated to
 273          * the largest possible selection, i.e., the selections passed to
 274          * analyzeFrame() are always a subset of the selections provided here.
 275          */
 276         virtual void initAnalysis(const TrajectoryAnalysisSettings &settings,
 277                                   const TopologyInformation        &top) = 0;
 278         /*! \brief
 279          * Performs additional initialization after reading the first frame.
 280          *
 281          * When this function is called, selections are the same as in
 282          * initAnalysis(), i.e., they have not been evaluated for the first
 283          * frame.
 284          *
 285          * It is necessary to override this method only if the module needs to
 286          * do initialization for which it requires data from the first frame.
 287          *
 288          * The default implementation does nothing.
 289          */
 290         virtual void initAfterFirstFrame(const t_trxframe &fr);
 291
 292         /*! \brief
 293          * Starts the analysis of frames.
 294          *
 295          * \param[in]  opt
 296          * \param[in]  selections  Frame-local selection collection object.
 297          * \returns    Data structure for thread-local data.
 298          *
 299          * This function is necessary only for threaded parallelization.
 300          * It is called once for each thread and should initialize a class that
 301          * contains any required frame-local data in the returned value.
 302          * The default implementation creates a basic data structure that holds
 303          * thread-local data handles for all data objects registered with
 304          * registerAnalysisDataset(), as well as the thread-local selection
 305          * collection.  These can be accessed in analyzeFrame() using the
 306          * methods in TrajectoryAnalysisModuleData.
 307          * If other thread-local data is needed, this function should be
 308          * overridden and it should create an instance of a class derived from
 309          * TrajectoryAnalysisModuleData.
 310          *
 311          * \see TrajectoryAnalysisModuleData
 312          */
 313         virtual TrajectoryAnalysisModuleDataPointer startFrames(
 314             const AnalysisDataParallelOptions &opt,
 315             const SelectionCollection         &selections);
 316         /*! \brief
 317          * Analyzes a single frame.
 318          *
 319          * \param[in]     frnr   Frame number, a zero-based index that
 320          *      uniquely identifies the frame.
 321          * \param[in]     fr     Current frame.
 322          * \param[in]     pbc    Periodic boundary conditions for \p fr.
 323          * \param[in,out] pdata  Data structure for frame-local data.
 324          *
 325          * This method is called once for each frame to be analyzed, and should
 326          * analyze the positions provided in the selections.  Data handles and
 327          * selections should be obtained from the \p pdata structure.
 328          *
 329          * For threaded analysis, this method is called asynchronously in
 330          * different threads to analyze different frames.  The \p pdata
 331          * structure is one of the structures created with startFrames(),
 332          * but no assumptions should be made about which of these data
 333          * structures is used.  It is guaranteed that two instances of
 334          * analyzeFrame() are not running concurrently with the same \p pdata
 335          * data structure.
 336          * Any access to data structures not stored in \p pdata should be
 337          * designed to be thread-safe.
 338          */
 339         virtual void analyzeFrame(int frnr, const t_trxframe &fr, t_pbc *pbc,
 340                                   TrajectoryAnalysisModuleData *pdata) = 0;
 341         /*! \brief
 342          * Finishes the analysis of frames.
 343          *
 344          * \param[in]  pdata    Data structure for thread-local data.
 345          *
 346          * This method is called once for each call of startFrames(), with the
 347          * data structure returned by the corresponding startFrames().
 348          * The \p pdata object should be destroyed by the caller after this
 349          * function has been called.
 350          *
 351          * You only need to override this method if you need custom
 352          * operations to combine data from the frame-local data structures
 353          * to get the final result.  In such cases, the data should be
 354          * aggregated in this function and stored in a member attribute.
 355          *
 356          * The default implementation does nothing.
 357          *
 358          * \see startFrames()
 359          */
 360         virtual void finishFrames(TrajectoryAnalysisModuleData *pdata);
 361
 362         /*! \brief
 363          * Postprocesses data after frames have been read.
 364          *
 365          * \param[in]  nframes  Total number of frames processed.
 366          *
 367          * This function is called after all finishFrames() calls have been
 368          * called.
 369          * \p nframes will equal the number of calls to analyzeFrame() that
 370          * have occurred.
 371          */
 372         virtual void finishAnalysis(int nframes) = 0;
 373         /*! \brief
 374          * Writes output into files and/or standard output/error.
 375          *
 376          * All output from the module, excluding data written out for each
 377          * frame during analyzeFrame(), should be confined into this function.
 378          * This function is guaranteed to be called only after
 379          * finishAnalysis().
 380          */
 381         virtual void writeOutput() = 0;
 382
 383         /*! \brief
 384          * Returns the name of the analysis module.
 385          *
 386          * Does not throw.
 387          */
 388         const char *name() const;
 389         /*! \brief
 390          * Returns short description for the analysis module.
 391          *
 392          * Does not throw.
 393          */
 394         const char *description() const;
 395         /*! \brief
 396          * Returns the number of datasets provided by the module.
 397          *
 398          * Does not throw.
 399          */
 400         int datasetCount() const;
 401         /*! \brief
 402          * Returns a vector with the names of datasets provided by the module.
 403          *
 404          * Does not throw.
 405          */
 406         const std::vector<std::string> &datasetNames() const;
 407         /*! \brief
 408          * Returns a pointer to the data set \p index.
 409          *
 410          * \param[in] index  Data set to query for.
 411          * \returns   Reference to the requested data set.
 412          * \throws    APIError if \p index is not valid.
 413          *
 414          * \p index should be >= 0 and < datasetCount().
 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 &datasetFromIndex(int index) const;
 422         /*! \brief
 423          * Returns a pointer to the data set with name \p name
 424          *
 425          * \param[in] name  Data set to query for.
 426          * \returns   Reference to the requested data set.
 427          * \throws    APIError if \p name is not valid.
 428          *
 429          * \p name should be one of the names returned by datasetNames().
 430          *
 431          * The return value is not const to allow callers to add modules to the
 432          * data sets. However, the AbstractAnalysisData interface does not
 433          * provide any means to alter the data, so the module does not need to
 434          * care about external modifications.
 435          */
 436         AbstractAnalysisData &datasetFromName(const char *name) const;
 437
 438     protected:
 439         /*! \brief
 440          * Initializes the dataset registration mechanism.
 441          *
 442          * \param[in] name         Name for the module.
 443          * \param[in] description  One-line description for the module.
 444          * \throws    std::bad_alloc if out of memory.
 445          */
 446         TrajectoryAnalysisModule(const char *name, const char *description);
 447
 448         /*! \brief
 449          * Registers a dataset that exports data.
 450          *
 451          * \param     data  Data object to register.
 452          * \param[in] name  Name to register the dataset with.
 453          * \throws    std::bad_alloc if out of memory.
 454          *
 455          * Registers \p data as a dataset that provides output from the
 456          * analysis module.  Callers for the module can access the dataset
 457          * with datasetFromName() using \p name as an AbstractAnalysisData
 458          * object.  This allows them to add their own data modules to do extra
 459          * processing.
 460          *
 461          * \p name must be unique across all calls within the same
 462          * TrajectoryAnalysisModule instance.
 463          */
 464         void registerBasicDataset(AbstractAnalysisData *data, const char *name);
 465         /*! \brief
 466          * Registers a parallelized dataset that exports data.
 467          *
 468          * \param     data  AnalysisData object to register.
 469          * \param[in] name  Name to register the dataset with.
 470          * \throws    std::bad_alloc if out of memory.
 471          *
 472          * This method works as registerBasicDataset(), but additionally allows
 473          * data handles for \p data to be accessed using
 474          * TrajectoryAnalysisData.
 475          *
 476          * \see registerBasicDataset()
 477          */
 478         void registerAnalysisDataset(AnalysisData *data, const char *name);
 479
 480     private:
 481         class Impl;
 482
 483         PrivateImplPointer<Impl> impl_;
 484
 485         /*! \brief
 486          * Needed to access the registered analysis data sets.
 487          */
 488         friend class TrajectoryAnalysisModuleData;
 489 };
 490
 491 //! Smart pointer to manage a TrajectoryAnalysisModule.
 492 typedef gmx_unique_ptr<TrajectoryAnalysisModule>::type
 493     TrajectoryAnalysisModulePointer;
 494
 495 } // namespace gmx
 496
 497 #endif