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  * \inpublicapi
  67  * \ingroup module_trajectoryanalysis
  68  */
  69 class TrajectoryAnalysisSettings
  70 {
  71     public:
  72         //! Recognized flags.
  73         enum
  74         {
  75             /*! \brief
  76              * Forces loading of a topology file.
  77              *
  78              * If this flag is not specified, the topology file is loaded only
  79              * if it is provided on the command line explicitly.
  80              */
  81             efRequireTop     = 1<<0,
  82             /*! \brief
  83              * Requests topology coordinates.
  84              *
  85              * If this flag is specified, the coordinates loaded from the
  86              * topology can be accessed, otherwise they are not loaded.
  87              *
  88              * \see TopologyInformation
  89              */
  90             efUseTopX        = 1<<1,
  91             /*! \brief
  92              * Disallows the user from changing PBC handling.
  93              *
  94              * If this option is not specified, the analysis module (see
  95              * TrajectoryAnalysisModule::analyzeFrame()) may be passed a NULL
  96              * PBC structure, and it should be able to handle such a situation.
  97              *
  98              * \see setPBC()
  99              */
 100             efNoUserPBC      = 1<<4,
 101             /*! \brief
 102              * Disallows the user from changing PBC removal.
 103              *
 104              * \see setRmPBC()
 105              */
 106             efNoUserRmPBC    = 1<<5,
 107             /*! \brief
 108              * Requests dumps of parsed and compiled selection trees.
 109              *
 110              * This flag is used by internal debugging tools to request
 111              * the selection trees dumping to stderr.
 112              */
 113             efDebugSelection = 1<<16,
 114         };
 115
 116         //! Initializes default settings.
 117         TrajectoryAnalysisSettings();
 118         ~TrajectoryAnalysisSettings();
 119
 120         //! Returns the time unit manager with time unit timeUnit().
 121         const TimeUnitManager &timeUnitManager() const;
 122         //! Returns the time unit the user has requested.
 123         TimeUnit timeUnit() { return timeUnitManager().timeUnit(); }
 124         //! Returns common settings for analysis data plot modules.
 125         const AnalysisDataPlotSettings &plotSettings() const;
 126
 127         //! Returns the currently set flags.
 128         unsigned long flags() const;
 129         //! Tests whether a flag has been set.
 130         bool hasFlag(unsigned long flag) const;
 131         /*! \brief
 132          * Returns whether PBC should be used.
 133          *
 134          * Returns the value set with setPBC() and/or overridden by the user.
 135          * The user-provided value can be accessed in
 136          * TrajectoryAnalysisModule::initOptionsDone(), and can be overridden
 137          * with a call to setPBC().
 138          */
 139         bool hasPBC() const;
 140         /*! \brief
 141          * Returns whether molecules should be made whole.
 142          *
 143          * See hasPBC() for information on accessing or overriding the
 144          * user-provided value.
 145          */
 146         bool hasRmPBC() const;
 147         //! Returns the currently set frame flags.
 148         int frflags() const;
 149
 150         /*! \brief
 151          * Sets flags.
 152          *
 153          * Overrides any earlier set flags.
 154          * By default, no flags are set.
 155          */
 156         void setFlags(unsigned long flags);
 157         //! Sets or clears an individual flag.
 158         void setFlag(unsigned long flag, bool bSet = true);
 159         /*! \brief
 160          * Sets whether PBC are used.
 161          *
 162          * \param[in]  bPBC   true if PBC should be used.
 163          *
 164          * If called in TrajectoryAnalysisModule::initOptions(), this function
 165          * sets the default for whether PBC are used in the analysis.
 166          * If ::efNoUserPBC is not set, a command-line option is provided
 167          * for the user to override the default value.
 168          * If called later, it overrides the setting provided by the user or an
 169          * earlier call.
 170          *
 171          * If this function is not called, the default is to use PBC.
 172          *
 173          * If PBC are not used, the \p pbc pointer passed to
 174          * TrajectoryAnalysisModule::analyzeFrame() is NULL.
 175          * The value of the flag can also be accessed with hasPBC().
 176          *
 177          * \see ::efNoUserPBC
 178          */
 179         void setPBC(bool bPBC);
 180         /*! \brief
 181          * Sets whether molecules are made whole.
 182          *
 183          * \param[in]     bRmPBC true if molecules should be made whole.
 184          *
 185          * If called in TrajectoryAnalysisModule::initOptions(), this function
 186          * sets the default for whether molecules are made whole.
 187          * If ::efNoUserRmPBC is not set, a command-line option is provided
 188          * for the user to override the default value.
 189          * If called later, it overrides the setting provided by the user or an
 190          * earlier call.
 191          *
 192          * If this function is not called, the default is to make molecules
 193          * whole.
 194          *
 195          * The main use of this function is to call it with \c false if your
 196          * analysis program does not require whole molecules as this can
 197          * increase the performance.
 198          * In such a case, you can also specify ::efNoUserRmPBC to not to
 199          * confuse the user with an option that would only slow the program
 200          * down.
 201          *
 202          * \see ::efNoUserRmPBC
 203          */
 204         void setRmPBC(bool bRmPBC);
 205         /*! \brief
 206          * Sets flags that determine what to read from the trajectory.
 207          *
 208          * \param[in]     frflags Flags for what to read from the trajectory file.
 209          *
 210          * If this function is not called, the flags default to TRX_NEED_X.
 211          * If the analysis module needs some other information (velocities,
 212          * forces), it can call this function to load additional information
 213          * from the trajectory.
 214          */
 215         void setFrameFlags(int frflags);
 216
 217     private:
 218         class Impl;
 219
 220         PrivateImplPointer<Impl> _impl;
 221
 222         friend class TrajectoryAnalysisRunnerCommon;
 223 };
 224
 225 /*! \brief
 226  * Topology information passed to a trajectory analysis module.
 227  *
 228  * \inpublicapi
 229  * \ingroup module_trajectoryanalysis
 230  */
 231 class TopologyInformation
 232 {
 233     public:
 234         //! Returns true if a topology file was loaded.
 235         bool hasTopology() const { return _top != NULL; }
 236         //! Returns true if a full topology file was loaded.
 237         bool hasFullTopology() const { return _bTop; }
 238         //! Returns the loaded topology, or NULL if not loaded.
 239         t_topology *topology() const { return _top; }
 240         //! Returns the ePBC field from the topology.
 241         int ePBC() const { return _ePBC; }
 242         /*! \brief
 243          * Gets the configuration from the topology.
 244          *
 245          * \param[out] x     Topology coordinate pointer to initialize.
 246          *      (can be NULL, in which case it is not used).
 247          * \param[out] box   Box size from the topology file
 248          *      (can be NULL, in which case it is not used).
 249          *
 250          * If TrajectoryAnalysisSettings::efUseTopX has not been specified,
 251          * \p x should be NULL.
 252          *
 253          * The pointer returned in \p *x should not be freed.
 254          */
 255         void getTopologyConf(rvec **x, matrix box) const;
 256
 257     private:
 258         TopologyInformation();
 259         ~TopologyInformation();
 260
 261         //! The topology structure, or NULL if no topology loaded.
 262         t_topology          *_top;
 263         //! true if full tpx file was loaded, false otherwise.
 264         bool                 _bTop;
 265         //! Coordinates from the topology (can be NULL).
 266         rvec                *_xtop;
 267         //! The box loaded from the topology file.
 268         matrix               _boxtop;
 269         //! The ePBC field loaded from the topology file.
 270         int                  _ePBC;
 271
 272         GMX_DISALLOW_COPY_AND_ASSIGN(TopologyInformation);
 273
 274         friend class TrajectoryAnalysisRunnerCommon;
 275 };
 276
 277 } // namespace gmx
 278
 279 #endif