src/gromacs/trajectoryanalysis/analysissettings.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::TrajectoryAnalysisSettings and gmx::TopologyInformation.
  34  *
  35  * \author Teemu Murtola <teemu.murtola@cbr.su.se>
  36  * \inpublicapi
  37  * \ingroup module_trajectoryanalysis
  38  */
  39 #ifndef GMX_TRAJECTORYANALYSIS_ANALYSISSETTINGS_H
  40 #define GMX_TRAJECTORYANALYSIS_ANALYSISSETTINGS_H
  41
  42 #include "../legacyheaders/typedefs.h"
  43
  44 #include "../options/timeunitmanager.h"
  45 #include "../utility/common.h"
  46
  47 namespace gmx
  48 {
  49
  50 class AnalysisDataPlotSettings;
  51 class Options;
  52 class TrajectoryAnalysisRunnerCommon;
  53
  54 /*! \brief
  55  * Trajectory analysis module configuration object.
  56  *
  57  * This class is used by trajectory analysis modules to inform the caller
  58  * about the requirements they have on the input (e.g., whether a topology is
  59  * required, or whether PBC removal makes sense).  It is also used to pass
  60  * similar information back to the analysis module after parsing user input.
  61  *
  62  * Having this functionality as a separate class makes the
  63  * TrajectoryAnalysisModule interface much cleaner, and also reduces the need to
  64  * change existing code when new options are added.
  65  *
  66  * Methods in this class do not throw, except for the constructor, which may
  67  * throw an std::bad_alloc.
  68  *
  69  * \todo
  70  * Remove plain flags from the public interface.
  71  *
  72  * \inpublicapi
  73  * \ingroup module_trajectoryanalysis
  74  */
  75 class TrajectoryAnalysisSettings
  76 {
  77     public:
  78         //! Recognized flags.
  79         enum
  80         {
  81             /*! \brief
  82              * Forces loading of a topology file.
  83              *
  84              * If this flag is not specified, the topology file is loaded only
  85              * if it is provided on the command line explicitly.
  86              */
  87             efRequireTop     = 1<<0,
  88             /*! \brief
  89              * Requests topology coordinates.
  90              *
  91              * If this flag is specified, the coordinates loaded from the
  92              * topology can be accessed, otherwise they are not loaded.
  93              *
  94              * \see TopologyInformation
  95              */
  96             efUseTopX        = 1<<1,
  97             /*! \brief
  98              * Disallows the user from changing PBC handling.
  99              *
 100              * If this option is not specified, the analysis module (see
 101              * TrajectoryAnalysisModule::analyzeFrame()) may be passed a NULL
 102              * PBC structure, and it should be able to handle such a situation.
 103              *
 104              * \see setPBC()
 105              */
 106             efNoUserPBC      = 1<<4,
 107             /*! \brief
 108              * Disallows the user from changing PBC removal.
 109              *
 110              * \see setRmPBC()
 111              */
 112             efNoUserRmPBC    = 1<<5,
 113         };
 114
 115         //! Initializes default settings.
 116         TrajectoryAnalysisSettings();
 117         ~TrajectoryAnalysisSettings();
 118
 119         //! Returns the time unit manager with time unit timeUnit().
 120         const TimeUnitManager &timeUnitManager() const;
 121         //! Returns the time unit the user has requested.
 122         TimeUnit timeUnit() { return timeUnitManager().timeUnit(); }
 123         //! Returns common settings for analysis data plot modules.
 124         const AnalysisDataPlotSettings &plotSettings() const;
 125
 126         //! Returns the currently set flags.
 127         unsigned long flags() const;
 128         //! Tests whether a flag has been set.
 129         bool hasFlag(unsigned long flag) const;
 130         /*! \brief
 131          * Returns whether PBC should be used.
 132          *
 133          * Returns the value set with setPBC() and/or overridden by the user.
 134          * The user-provided value can be accessed in
 135          * TrajectoryAnalysisModule::initOptionsDone(), and can be overridden
 136          * with a call to setPBC().
 137          */
 138         bool hasPBC() const;
 139         /*! \brief
 140          * Returns whether molecules should be made whole.
 141          *
 142          * See hasPBC() for information on accessing or overriding the
 143          * user-provided value.
 144          */
 145         bool hasRmPBC() const;
 146         //! Returns the currently set frame flags.
 147         int frflags() const;
 148
 149         /*! \brief
 150          * Sets flags.
 151          *
 152          * Overrides any earlier set flags.
 153          * By default, no flags are set.
 154          */
 155         void setFlags(unsigned long flags);
 156         //! Sets or clears an individual flag.
 157         void setFlag(unsigned long flag, bool bSet = true);
 158         /*! \brief
 159          * Sets whether PBC are used.
 160          *
 161          * \param[in]  bPBC   true if PBC should be used.
 162          *
 163          * If called in TrajectoryAnalysisModule::initOptions(), this function
 164          * sets the default for whether PBC are used in the analysis.
 165          * If \ref efNoUserPBC is not set, a command-line option is provided
 166          * for the user to override the default value.
 167          * If called later, it overrides the setting provided by the user or an
 168          * earlier call.
 169          *
 170          * If this function is not called, the default is to use PBC.
 171          *
 172          * If PBC are not used, the \p pbc pointer passed to
 173          * TrajectoryAnalysisModule::analyzeFrame() is NULL.
 174          * The value of the flag can also be accessed with hasPBC().
 175          *
 176          * \see efNoUserPBC
 177          */
 178         void setPBC(bool bPBC);
 179         /*! \brief
 180          * Sets whether molecules are made whole.
 181          *
 182          * \param[in]     bRmPBC true if molecules should be made whole.
 183          *
 184          * If called in TrajectoryAnalysisModule::initOptions(), this function
 185          * sets the default for whether molecules are made whole.
 186          * If \ref efNoUserRmPBC is not set, a command-line option is provided
 187          * for the user to override the default value.
 188          * If called later, it overrides the setting provided by the user or an
 189          * earlier call.
 190          *
 191          * If this function is not called, the default is to make molecules
 192          * whole.
 193          *
 194          * The main use of this function is to call it with \c false if your
 195          * analysis program does not require whole molecules as this can
 196          * increase the performance.
 197          * In such a case, you can also specify \ref efNoUserRmPBC to not to
 198          * confuse the user with an option that would only slow the program
 199          * down.
 200          *
 201          * \see efNoUserRmPBC
 202          */
 203         void setRmPBC(bool bRmPBC);
 204         /*! \brief
 205          * Sets flags that determine what to read from the trajectory.
 206          *
 207          * \param[in]     frflags Flags for what to read from the trajectory file.
 208          *
 209          * If this function is not called, the flags default to TRX_NEED_X.
 210          * If the analysis module needs some other information (velocities,
 211          * forces), it can call this function to load additional information
 212          * from the trajectory.
 213          */
 214         void setFrameFlags(int frflags);
 215
 216     private:
 217         class Impl;
 218
 219         PrivateImplPointer<Impl> _impl;
 220
 221         friend class TrajectoryAnalysisRunnerCommon;
 222 };
 223
 224 /*! \brief
 225  * Topology information passed to a trajectory analysis module.
 226  *
 227  * This class is used to pass topology information to trajectory analysis
 228  * modules and to manage memory for them.  Having a single wrapper object
 229  * instead of passing each item separately makes TrajectoryAnalysisModule
 230  * interface simpler, and also reduces the need to change existing code if
 231  * additional information is added.
 232  *
 233  * Methods in this class do not throw if not explicitly stated.
 234  *
 235  * \inpublicapi
 236  * \ingroup module_trajectoryanalysis
 237  */
 238 class TopologyInformation
 239 {
 240     public:
 241         //! Returns true if a topology file was loaded.
 242         bool hasTopology() const { return _top != NULL; }
 243         //! Returns true if a full topology file was loaded.
 244         bool hasFullTopology() const { return _bTop; }
 245         //! Returns the loaded topology, or NULL if not loaded.
 246         t_topology *topology() const { return _top; }
 247         //! Returns the ePBC field from the topology.
 248         int ePBC() const { return _ePBC; }
 249         /*! \brief
 250          * Gets the configuration from the topology.
 251          *
 252          * \param[out] x     Topology coordinate pointer to initialize.
 253          *      (can be NULL, in which case it is not used).
 254          * \param[out] box   Box size from the topology file
 255          *      (can be NULL, in which case it is not used).
 256          * \throws  APIError if topology coordinates are not available and
 257          *      \p x is not NULL.
 258          *
 259          * If TrajectoryAnalysisSettings::efUseTopX has not been specified,
 260          * \p x should be NULL.
 261          *
 262          * The pointer returned in \p *x should not be freed.
 263          */
 264         void getTopologyConf(rvec **x, matrix box) const;
 265
 266     private:
 267         TopologyInformation();
 268         ~TopologyInformation();
 269
 270         //! The topology structure, or NULL if no topology loaded.
 271         t_topology          *_top;
 272         //! true if full tpx file was loaded, false otherwise.
 273         bool                 _bTop;
 274         //! Coordinates from the topology (can be NULL).
 275         rvec                *_xtop;
 276         //! The box loaded from the topology file.
 277         matrix               _boxtop;
 278         //! The ePBC field loaded from the topology file.
 279         int                  _ePBC;
 280
 281         GMX_DISALLOW_COPY_AND_ASSIGN(TopologyInformation);
 282
 283         /*! \brief
 284          * Needed to initialize the data.
 285          */
 286         friend class TrajectoryAnalysisRunnerCommon;
 287 };
 288
 289 } // namespace gmx
 290
 291 #endif