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,2018, 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.
  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/options/timeunitmanager.h"
  49 #include "gromacs/utility/classhelpers.h"
  50
  51 namespace gmx
  52 {
  53
  54 template <typename T> class ArrayRef;
  55
  56 class AnalysisDataPlotSettings;
  57 class ICommandLineOptionsModuleSettings;
  58 class Options;
  59 class TrajectoryAnalysisRunnerCommon;
  60
  61 /*! \brief
  62  * Trajectory analysis module configuration object.
  63  *
  64  * This class is used by trajectory analysis modules to inform the caller
  65  * about the requirements they have on the input (e.g., whether a topology is
  66  * required, or whether PBC removal makes sense).  It is also used to pass
  67  * similar information back to the analysis module after parsing user input.
  68  *
  69  * Having this functionality as a separate class makes the
  70  * TrajectoryAnalysisModule interface much cleaner, and also reduces the need to
  71  * change existing code when new options are added.
  72  *
  73  * Methods in this class do not throw, except for the constructor, which may
  74  * throw an std::bad_alloc.
  75  *
  76  * \todo
  77  * Remove plain flags from the public interface.
  78  *
  79  * \inpublicapi
  80  * \ingroup module_trajectoryanalysis
  81  */
  82 class TrajectoryAnalysisSettings
  83 {
  84     public:
  85         //! Recognized flags.
  86         enum
  87         {
  88             /*! \brief
  89              * Forces loading of a topology file.
  90              *
  91              * If this flag is not specified, the topology file is loaded only
  92              * if it is provided on the command line explicitly.
  93              */
  94             efRequireTop     = 1<<0,
  95             /*! \brief
  96              * Requests topology coordinates.
  97              *
  98              * If this flag is specified, the position coordinates loaded from the
  99              * topology can be accessed, otherwise they are not loaded.
 100              *
 101              * \see TopologyInformation
 102              */
 103             efUseTopX        = 1<<1,
 104             /*! \brief
 105              * Requests topology coordinates.
 106              *
 107              * If this flag is specified, the velocity coordinates loaded from the
 108              * topology can be accessed, otherwise they are not loaded.
 109              *
 110              * \see TopologyInformation
 111              */
 112             efUseTopV        = 1<<2,
 113             /*! \brief
 114              * Disallows the user from changing PBC handling.
 115              *
 116              * If this option is not specified, the analysis module (see
 117              * TrajectoryAnalysisModule::analyzeFrame()) may be passed a NULL
 118              * PBC structure, and it should be able to handle such a situation.
 119              *
 120              * \see setPBC()
 121              */
 122             efNoUserPBC      = 1<<4,
 123             /*! \brief
 124              * Disallows the user from changing PBC removal.
 125              *
 126              * \see setRmPBC()
 127              */
 128             efNoUserRmPBC    = 1<<5,
 129         };
 130
 131         //! Initializes default settings.
 132         TrajectoryAnalysisSettings();
 133         ~TrajectoryAnalysisSettings();
 134
 135         //! Injects command line options module settings for some methods to use.
 136         void setOptionsModuleSettings(ICommandLineOptionsModuleSettings *settings);
 137
 138         //! Returns the time unit the user has requested.
 139         TimeUnit timeUnit() const;
 140         //! Returns common settings for analysis data plot modules.
 141         const AnalysisDataPlotSettings &plotSettings() const;
 142
 143         //! Returns the currently set flags.
 144         unsigned long flags() const;
 145         //! Tests whether a flag has been set.
 146         bool hasFlag(unsigned long flag) const;
 147         /*! \brief
 148          * Returns whether PBC should be used.
 149          *
 150          * Returns the value set with setPBC() and/or overridden by the user.
 151          * The user-provided value can be accessed in
 152          * TrajectoryAnalysisModule::optionsFinished(), and can be overridden
 153          * with a call to setPBC().
 154          */
 155         bool hasPBC() const;
 156         /*! \brief
 157          * Returns whether molecules should be made whole.
 158          *
 159          * See hasPBC() for information on accessing or overriding the
 160          * user-provided value.
 161          */
 162         bool hasRmPBC() const;
 163         //! Returns the currently set frame flags.
 164         int frflags() const;
 165
 166         /*! \brief
 167          * Sets flags.
 168          *
 169          * Overrides any earlier set flags.
 170          * By default, no flags are set.
 171          */
 172         void setFlags(unsigned long flags);
 173         //! Sets or clears an individual flag.
 174         void setFlag(unsigned long flag, bool bSet = true);
 175         /*! \brief
 176          * Sets whether PBC are used.
 177          *
 178          * \param[in]  bPBC   true if PBC should be used.
 179          *
 180          * If called in TrajectoryAnalysisModule::initOptions(), this function
 181          * sets the default for whether PBC are used in the analysis.
 182          * If \ref efNoUserPBC is not set, a command-line option is provided
 183          * for the user to override the default value.
 184          * If called later, it overrides the setting provided by the user or an
 185          * earlier call.
 186          *
 187          * If this function is not called, the default is to use PBC.
 188          *
 189          * If PBC are not used, the \p pbc pointer passed to
 190          * TrajectoryAnalysisModule::analyzeFrame() is NULL.
 191          * The value of the flag can also be accessed with hasPBC().
 192          *
 193          * \see efNoUserPBC
 194          */
 195         void setPBC(bool bPBC);
 196         /*! \brief
 197          * Sets whether molecules are made whole.
 198          *
 199          * \param[in]     bRmPBC true if molecules should be made whole.
 200          *
 201          * If called in TrajectoryAnalysisModule::initOptions(), this function
 202          * sets the default for whether molecules are made whole.
 203          * If \ref efNoUserRmPBC is not set, a command-line option is provided
 204          * for the user to override the default value.
 205          * If called later, it overrides the setting provided by the user or an
 206          * earlier call.
 207          *
 208          * If this function is not called, the default is to make molecules
 209          * whole.
 210          *
 211          * The main use of this function is to call it with \c false if your
 212          * analysis program does not require whole molecules as this can
 213          * increase the performance.
 214          * In such a case, you can also specify \ref efNoUserRmPBC to not to
 215          * confuse the user with an option that would only slow the program
 216          * down.
 217          *
 218          * \see efNoUserRmPBC
 219          */
 220         void setRmPBC(bool bRmPBC);
 221         /*! \brief
 222          * Sets flags that determine what to read from the trajectory.
 223          *
 224          * \param[in]     frflags Flags for what to read from the trajectory file.
 225          *
 226          * If this function is not called, the flags default to TRX_NEED_X.
 227          * If the analysis module needs some other information (velocities,
 228          * forces), it can call this function to load additional information
 229          * from the trajectory.
 230          */
 231         void setFrameFlags(int frflags);
 232
 233         //! \copydoc ICommandLineOptionsModuleSettings::setHelpText()
 234         void setHelpText(const ArrayRef<const char *const> &help);
 235
 236     private:
 237         class Impl;
 238
 239         PrivateImplPointer<Impl> impl_;
 240
 241         friend class TrajectoryAnalysisRunnerCommon;
 242 };
 243
 244 } // namespace gmx
 245
 246 #endif