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
  46 namespace gmx
  47 {
  48
  49 class AnalysisDataPlotSettings;
  50 class Options;
  51 class TrajectoryAnalysisRunnerCommon;
  52
  53 /*! \brief
  54  * Trajectory analysis module configuration object.
  55  *
  56  * This class is used by trajectory analysis modules to inform the caller
  57  * about the requirements they have on the input (e.g., whether a topology is
  58  * required, or whether PBC removal makes sense). It is also used to pass
  59  * similar information back to the analysis module after parsing user input.
  60  *
  61  * Having this functionality as a separate class makes the
  62  * TrajectoryAnalysisModule interface much cleaner, and also reduces the need to
  63  * change existing code when new options are added.
  64  *
  65  * \inpublicapi
  66  * \ingroup module_trajectoryanalysis
  67  */
  68 class TrajectoryAnalysisSettings
  69 {
  70     public:
  71         //! Recognized flags.
  72         enum
  73         {
  74             /*! \brief
  75              * Forces loading of a topology file.
  76              *
  77              * If this flag is not specified, the topology file is loaded only
  78              * if it is provided on the command line explicitly.
  79              */
  80             efRequireTop     = 1<<0,
  81             /*! \brief
  82              * Requests topology coordinates.
  83              *
  84              * If this flag is specified, the coordinates loaded from the
  85              * topology can be accessed, otherwise they are not loaded.
  86              *
  87              * \see TopologyInformation
  88              */
  89             efUseTopX        = 1<<1,
  90             /*! \brief
  91              * Disallows the user from changing PBC handling.
  92              *
  93              * If this option is not specified, the analysis module (see
  94              * TrajectoryAnalysisModule::analyzeFrame()) may be passed a NULL
  95              * PBC structure, and it should be able to handle such a situation.
  96              *
  97              * \see setPBC()
  98              */
  99             efNoUserPBC      = 1<<4,
 100             /*! \brief
 101              * Disallows the user from changing PBC removal.
 102              *
 103              * \see setRmPBC()
 104              */
 105             efNoUserRmPBC    = 1<<5,
 106             /*! \brief
 107              * Requests dumps of parsed and compiled selection trees.
 108              *
 109              * This flag is used by internal debugging tools to request
 110              * the selection trees dumping to stderr.
 111              */
 112             efDebugSelection = 1<<16,
 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 ::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 ::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 ::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         Impl                   *_impl;
 220
 221         // Disallow copy and assign.
 222         TrajectoryAnalysisSettings(const TrajectoryAnalysisSettings &);
 223         void operator =(const TrajectoryAnalysisSettings &);
 224
 225         friend class TrajectoryAnalysisRunnerCommon;
 226 };
 227
 228 /*! \brief
 229  * Topology information passed to a trajectory analysis module.
 230  *
 231  * \inpublicapi
 232  * \ingroup module_trajectoryanalysis
 233  */
 234 class TopologyInformation
 235 {
 236     public:
 237         //! Returns true if a topology file was loaded.
 238         bool hasTopology() const { return _top != NULL; }
 239         //! Returns true if a full topology file was loaded.
 240         bool hasFullTopology() const { return _bTop; }
 241         //! Returns the loaded topology, or NULL if not loaded.
 242         t_topology *topology() const { return _top; }
 243         //! Returns the ePBC field from the topology.
 244         int ePBC() const { return _ePBC; }
 245         /*! \brief
 246          * Gets the configuration from the topology.
 247          *
 248          * \param[out] x     Topology coordinate pointer to initialize.
 249          *      (can be NULL, in which case it is not used).
 250          * \param[out] box   Box size from the topology file
 251          *      (can be NULL, in which case it is not used).
 252          *
 253          * If TrajectoryAnalysisSettings::efUseTopX has not been specified,
 254          * \p x should be NULL.
 255          *
 256          * The pointer returned in \p *x should not be freed.
 257          */
 258         void getTopologyConf(rvec **x, matrix box) const;
 259
 260     private:
 261         TopologyInformation();
 262         ~TopologyInformation();
 263
 264         //! The topology structure, or NULL if no topology loaded.
 265         t_topology          *_top;
 266         //! true if full tpx file was loaded, false otherwise.
 267         bool                 _bTop;
 268         //! Coordinates from the topology (can be NULL).
 269         rvec                *_xtop;
 270         //! The box loaded from the topology file.
 271         matrix               _boxtop;
 272         //! The ePBC field loaded from the topology file.
 273         int                  _ePBC;
 274
 275         // Disallow copy and assign.
 276         TopologyInformation(const TopologyInformation &);
 277         void operator =(const TopologyInformation &);
 278
 279         friend class TrajectoryAnalysisRunnerCommon;
 280 };
 281
 282 } // namespace gmx
 283
 284 #endif