src/gromacs/trajectoryanalysis/analysissettings.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2010,2011,2012, by the GROMACS development team, led by
   5  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   6  * and including many others, as listed in the AUTHORS file in the
   7  * top-level source directory and at http://www.gromacs.org.
   8  *
   9  * GROMACS is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public License
  11  * as published by the Free Software Foundation; either version 2.1
  12  * of the License, or (at your option) any later version.
  13  *
  14  * GROMACS is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public
  20  * License along with GROMACS; if not, see
  21  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  22  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  23  *
  24  * If you want to redistribute modifications to GROMACS, please
  25  * consider that scientific software is very special. Version
  26  * control is crucial - bugs must be traceable. We will be happy to
  27  * consider code for inclusion in the official distribution, but
  28  * derived work must not be called official GROMACS. Details are found
  29  * in the README & COPYING files - if they are missing, get the
  30  * official version at http://www.gromacs.org.
  31  *
  32  * To help us fund GROMACS development, we humbly ask that you cite
  33  * the research papers on the package. Check out http://www.gromacs.org.
  34  */
  35 /*! \file
  36  * \brief
  37  * Declares gmx::TrajectoryAnalysisSettings and gmx::TopologyInformation.
  38  *
  39  * \author Teemu Murtola <teemu.murtola@gmail.com>
  40  * \inpublicapi
  41  * \ingroup module_trajectoryanalysis
  42  */
  43 #ifndef GMX_TRAJECTORYANALYSIS_ANALYSISSETTINGS_H
  44 #define GMX_TRAJECTORYANALYSIS_ANALYSISSETTINGS_H
  45
  46 #include "../legacyheaders/typedefs.h"
  47
  48 #include "../options/timeunitmanager.h"
  49 #include "../utility/common.h"
  50
  51 namespace gmx
  52 {
  53
  54 class AnalysisDataPlotSettings;
  55 class Options;
  56 class TrajectoryAnalysisRunnerCommon;
  57
  58 /*! \brief
  59  * Trajectory analysis module configuration object.
  60  *
  61  * This class is used by trajectory analysis modules to inform the caller
  62  * about the requirements they have on the input (e.g., whether a topology is
  63  * required, or whether PBC removal makes sense).  It is also used to pass
  64  * similar information back to the analysis module after parsing user input.
  65  *
  66  * Having this functionality as a separate class makes the
  67  * TrajectoryAnalysisModule interface much cleaner, and also reduces the need to
  68  * change existing code when new options are added.
  69  *
  70  * Methods in this class do not throw, except for the constructor, which may
  71  * throw an std::bad_alloc.
  72  *
  73  * \todo
  74  * Remove plain flags from the public interface.
  75  *
  76  * \inpublicapi
  77  * \ingroup module_trajectoryanalysis
  78  */
  79 class TrajectoryAnalysisSettings
  80 {
  81     public:
  82         //! Recognized flags.
  83         enum
  84         {
  85             /*! \brief
  86              * Forces loading of a topology file.
  87              *
  88              * If this flag is not specified, the topology file is loaded only
  89              * if it is provided on the command line explicitly.
  90              */
  91             efRequireTop     = 1<<0,
  92             /*! \brief
  93              * Requests topology coordinates.
  94              *
  95              * If this flag is specified, the coordinates loaded from the
  96              * topology can be accessed, otherwise they are not loaded.
  97              *
  98              * \see TopologyInformation
  99              */
 100             efUseTopX        = 1<<1,
 101             /*! \brief
 102              * Disallows the user from changing PBC handling.
 103              *
 104              * If this option is not specified, the analysis module (see
 105              * TrajectoryAnalysisModule::analyzeFrame()) may be passed a NULL
 106              * PBC structure, and it should be able to handle such a situation.
 107              *
 108              * \see setPBC()
 109              */
 110             efNoUserPBC      = 1<<4,
 111             /*! \brief
 112              * Disallows the user from changing PBC removal.
 113              *
 114              * \see setRmPBC()
 115              */
 116             efNoUserRmPBC    = 1<<5,
 117         };
 118
 119         //! Initializes default settings.
 120         TrajectoryAnalysisSettings();
 121         ~TrajectoryAnalysisSettings();
 122
 123         //! Returns the time unit manager with time unit timeUnit().
 124         const TimeUnitManager &timeUnitManager() const;
 125         //! Returns the time unit the user has requested.
 126         TimeUnit timeUnit() { return timeUnitManager().timeUnit(); }
 127         //! Returns common settings for analysis data plot modules.
 128         const AnalysisDataPlotSettings &plotSettings() const;
 129
 130         //! Returns the currently set flags.
 131         unsigned long flags() const;
 132         //! Tests whether a flag has been set.
 133         bool hasFlag(unsigned long flag) const;
 134         /*! \brief
 135          * Returns whether PBC should be used.
 136          *
 137          * Returns the value set with setPBC() and/or overridden by the user.
 138          * The user-provided value can be accessed in
 139          * TrajectoryAnalysisModule::optionsFinished(), and can be overridden
 140          * with a call to setPBC().
 141          */
 142         bool hasPBC() const;
 143         /*! \brief
 144          * Returns whether molecules should be made whole.
 145          *
 146          * See hasPBC() for information on accessing or overriding the
 147          * user-provided value.
 148          */
 149         bool hasRmPBC() const;
 150         //! Returns the currently set frame flags.
 151         int frflags() const;
 152
 153         /*! \brief
 154          * Sets flags.
 155          *
 156          * Overrides any earlier set flags.
 157          * By default, no flags are set.
 158          */
 159         void setFlags(unsigned long flags);
 160         //! Sets or clears an individual flag.
 161         void setFlag(unsigned long flag, bool bSet = true);
 162         /*! \brief
 163          * Sets whether PBC are used.
 164          *
 165          * \param[in]  bPBC   true if PBC should be used.
 166          *
 167          * If called in TrajectoryAnalysisModule::initOptions(), this function
 168          * sets the default for whether PBC are used in the analysis.
 169          * If \ref efNoUserPBC is not set, a command-line option is provided
 170          * for the user to override the default value.
 171          * If called later, it overrides the setting provided by the user or an
 172          * earlier call.
 173          *
 174          * If this function is not called, the default is to use PBC.
 175          *
 176          * If PBC are not used, the \p pbc pointer passed to
 177          * TrajectoryAnalysisModule::analyzeFrame() is NULL.
 178          * The value of the flag can also be accessed with hasPBC().
 179          *
 180          * \see efNoUserPBC
 181          */
 182         void setPBC(bool bPBC);
 183         /*! \brief
 184          * Sets whether molecules are made whole.
 185          *
 186          * \param[in]     bRmPBC true if molecules should be made whole.
 187          *
 188          * If called in TrajectoryAnalysisModule::initOptions(), this function
 189          * sets the default for whether molecules are made whole.
 190          * If \ref efNoUserRmPBC is not set, a command-line option is provided
 191          * for the user to override the default value.
 192          * If called later, it overrides the setting provided by the user or an
 193          * earlier call.
 194          *
 195          * If this function is not called, the default is to make molecules
 196          * whole.
 197          *
 198          * The main use of this function is to call it with \c false if your
 199          * analysis program does not require whole molecules as this can
 200          * increase the performance.
 201          * In such a case, you can also specify \ref efNoUserRmPBC to not to
 202          * confuse the user with an option that would only slow the program
 203          * down.
 204          *
 205          * \see efNoUserRmPBC
 206          */
 207         void setRmPBC(bool bRmPBC);
 208         /*! \brief
 209          * Sets flags that determine what to read from the trajectory.
 210          *
 211          * \param[in]     frflags Flags for what to read from the trajectory file.
 212          *
 213          * If this function is not called, the flags default to TRX_NEED_X.
 214          * If the analysis module needs some other information (velocities,
 215          * forces), it can call this function to load additional information
 216          * from the trajectory.
 217          */
 218         void setFrameFlags(int frflags);
 219
 220     private:
 221         class Impl;
 222
 223         PrivateImplPointer<Impl> impl_;
 224
 225         friend class TrajectoryAnalysisRunnerCommon;
 226 };
 227
 228 /*! \brief
 229  * Topology information passed to a trajectory analysis module.
 230  *
 231  * This class is used to pass topology information to trajectory analysis
 232  * modules and to manage memory for them.  Having a single wrapper object
 233  * instead of passing each item separately makes TrajectoryAnalysisModule
 234  * interface simpler, and also reduces the need to change existing code if
 235  * additional information is added.
 236  *
 237  * Methods in this class do not throw if not explicitly stated.
 238  *
 239  * \inpublicapi
 240  * \ingroup module_trajectoryanalysis
 241  */
 242 class TopologyInformation
 243 {
 244     public:
 245         //! Returns true if a topology file was loaded.
 246         bool hasTopology() const { return top_ != NULL; }
 247         //! Returns true if a full topology file was loaded.
 248         bool hasFullTopology() const { return bTop_; }
 249         //! Returns the loaded topology, or NULL if not loaded.
 250         t_topology *topology() const { return top_; }
 251         //! Returns the ePBC field from the topology.
 252         int ePBC() const { return ePBC_; }
 253         /*! \brief
 254          * Gets the configuration from the topology.
 255          *
 256          * \param[out] x     Topology coordinate pointer to initialize.
 257          *      (can be NULL, in which case it is not used).
 258          * \param[out] box   Box size from the topology file
 259          *      (can be NULL, in which case it is not used).
 260          * \throws  APIError if topology coordinates are not available and
 261          *      \p x is not NULL.
 262          *
 263          * If TrajectoryAnalysisSettings::efUseTopX has not been specified,
 264          * \p x should be NULL.
 265          *
 266          * The pointer returned in \p *x should not be freed.
 267          */
 268         void getTopologyConf(rvec **x, matrix box) const;
 269
 270     private:
 271         TopologyInformation();
 272         ~TopologyInformation();
 273
 274         //! The topology structure, or NULL if no topology loaded.
 275         t_topology          *top_;
 276         //! true if full tpx file was loaded, false otherwise.
 277         bool                 bTop_;
 278         //! Coordinates from the topology (can be NULL).
 279         rvec                *xtop_;
 280         //! The box loaded from the topology file.
 281         matrix               boxtop_;
 282         //! The ePBC field loaded from the topology file.
 283         int                  ePBC_;
 284
 285         GMX_DISALLOW_COPY_AND_ASSIGN(TopologyInformation);
 286
 287         /*! \brief
 288          * Needed to initialize the data.
 289          */
 290         friend class TrajectoryAnalysisRunnerCommon;
 291 };
 292
 293 } // namespace gmx
 294
 295 #endif