src/gromacs/options/timeunitmanager.h

   1 /*
   2  *
   3  *                This source code is part of
   4  *
   5  *                 G   R   O   M   A   C   S
   6  *
   7  *          GROningen MAchine for Chemical Simulations
   8  *
   9  * Written by David van der Spoel, Erik Lindahl, Berk Hess, and others.
  10  * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
  11  * Copyright (c) 2001-2009, The GROMACS development team,
  12  * check out http://www.gromacs.org for more information.
  13
  14  * This program is free software; you can redistribute it and/or
  15  * modify it under the terms of the GNU General Public License
  16  * as published by the Free Software Foundation; either version 2
  17  * of the License, or (at your option) any later version.
  18  *
  19  * If you want to redistribute modifications, please consider that
  20  * scientific software is very special. Version control is crucial -
  21  * bugs must be traceable. We will be happy to consider code for
  22  * inclusion in the official distribution, but derived work must not
  23  * be called official GROMACS. Details are found in the README & COPYING
  24  * files - if they are missing, get the official version at www.gromacs.org.
  25  *
  26  * To help us fund GROMACS development, we humbly ask that you cite
  27  * the papers on the package - you can find them in the top README file.
  28  *
  29  * For more info, check our website at http://www.gromacs.org
  30  */
  31 /*! \file
  32  * \brief
  33  * Declares gmx::TimeUnitManager.
  34  *
  35  * \author Teemu Murtola <teemu.murtola@cbr.su.se>
  36  * \inpublicapi
  37  * \ingroup module_options
  38  */
  39 #ifndef GMX_OPTIONS_TIMEUNITMANAGER_H
  40 #define GMX_OPTIONS_TIMEUNITMANAGER_H
  41
  42 #include "../utility/gmxassert.h"
  43
  44 namespace gmx
  45 {
  46
  47 class Options;
  48
  49 /*! \brief
  50  * Time values for TimeUnitManager.
  51  *
  52  * \if internal
  53  * Currently, this should match with the time_unit_t enum defined in oenv.h
  54  * except that there is no NULL first item in this enum.
  55  * \endif
  56  *
  57  * \inpublicapi
  58  */
  59 enum TimeUnit
  60 {
  61     eTimeUnit_fs, //!< Femtoseconds.
  62     eTimeUnit_ps, //!< Picoseconds.
  63     eTimeUnit_ns, //!< Nanoseconds.
  64     eTimeUnit_us, //!< Microseconds.
  65     eTimeUnit_ms, //!< Milliseconds.
  66     eTimeUnit_s   //!< Seconds.
  67 };
  68
  69 /*! \brief
  70  * Provides common functionality for time unit conversions.
  71  *
  72  * Methods/objects that need to deal with time units can either take a
  73  * TimeUnitManager object, or they can take a TimeUnit value and construct a
  74  * TimeUnitManager object internally.
  75  *
  76  * Default copy constructor and assignment are used: the copy is an independent
  77  * object that is initialized with the same time unit as the original.
  78  *
  79  * \if internal
  80  * \todo
  81  * Most of this class is independent of the options implementation.
  82  * To ease reuse, it could be split such that the generic part is moved to the
  83  * utility module, and only the options-specific parts left in the options
  84  * module.
  85  * \endif
  86  *
  87  * \inpublicapi
  88  * \ingroup module_options
  89  */
  90 class TimeUnitManager
  91 {
  92     public:
  93         //! Creates a time unit manager with the default (ps) time unit.
  94         TimeUnitManager();
  95         //! Creates a time unit manager with the given time unit.
  96         explicit TimeUnitManager(TimeUnit unit);
  97
  98         //! Returns the currently selected time unit.
  99         TimeUnit timeUnit() const
 100         {
 101             GMX_ASSERT(timeUnit_ >= 0 && timeUnit_ <= eTimeUnit_s,
 102                        "Time unit index has become out-of-range");
 103             return static_cast<TimeUnit>(timeUnit_);
 104         }
 105         //! Set a new time unit for the manager.
 106         void setTimeUnit(TimeUnit unit);
 107
 108         //! Returns a string constant corresponding to the current time unit.
 109         const char *timeUnitAsString() const;
 110
 111         //! Returns the scaling factor to convert times to ps.
 112         double timeScaleFactor() const;
 113         //! Returns the scaling factor to convert times from ps.
 114         double inverseTimeScaleFactor() const;
 115
 116         /*! \brief
 117          * Adds a common option for selecting the time unit.
 118          *
 119          * \param[in,out] options Options to which the common option is added.
 120          * \param[in]     name    Name of the option to add.
 121          *
 122          * Adds an enum option to \p options to select the time unit for this
 123          * manager.
 124          */
 125         void addTimeUnitOption(Options *options, const char *name);
 126         /*! \brief
 127          * Scales user input values given to time options.
 128          *
 129          * \param[in,out] options Options in which to scale times.
 130          *
 131          * Scales each time option (see DoubleOption::timeValue()) in
 132          * \p options such that any user-given values are interpreted as given
 133          * in the time unit specified by this manager, and scaled to
 134          * picoseconds.  Programmatically given values (e.g., as default values
 135          * for the options) are not scaled.
 136          */
 137         void scaleTimeOptions(Options *options) const;
 138
 139     private:
 140         /*! \brief
 141          * Currently set time unit for this manager.
 142          *
 143          * Type is int to make it possible to use it with
 144          * StringOption::storeEnumIndex(), but it should always one of the
 145          * allowed values for TimeUnit.
 146          */
 147         int                     timeUnit_;
 148 };
 149
 150 } // namespace gmx
 151
 152 #endif