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