src/gromacs/trajectoryanalysis/analysissettings.h

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