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