src/gromacs/mdlib/ebin.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
   5  * Copyright (c) 2001-2004, The GROMACS development team.
   6  * Copyright (c) 2013,2014,2015,2018,2019, by the GROMACS development team, led by
   7  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   8  * and including many others, as listed in the AUTHORS file in the
   9  * top-level source directory and at http://www.gromacs.org.
  10  *
  11  * GROMACS is free software; you can redistribute it and/or
  12  * modify it under the terms of the GNU Lesser General Public License
  13  * as published by the Free Software Foundation; either version 2.1
  14  * of the License, or (at your option) any later version.
  15  *
  16  * GROMACS is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19  * Lesser General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU Lesser General Public
  22  * License along with GROMACS; if not, see
  23  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  24  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  25  *
  26  * If you want to redistribute modifications to GROMACS, please
  27  * consider that scientific software is very special. Version
  28  * control is crucial - bugs must be traceable. We will be happy to
  29  * consider code for inclusion in the official distribution, but
  30  * derived work must not be called official GROMACS. Details are found
  31  * in the README & COPYING files - if they are missing, get the
  32  * official version at http://www.gromacs.org.
  33  *
  34  * To help us fund GROMACS development, we humbly ask that you cite
  35  * the research papers on the package. Check out http://www.gromacs.org.
  36  */
  37 /* \internal \file
  38  * \brief
  39  * Declares structures and interfaces to store, compute and print current and average values for thermodynamics properties.
  40  *
  41  * The word 'energy' is used here in wide scope and refer to any thermodynamic quantity that can benefit from
  42  * averaging (e.g. temperature, pressure).
  43  *
  44  * \ingroup module_mdlib
  45  */
  46 #ifndef GMX_MDLIB_EBIN_H
  47 #define GMX_MDLIB_EBIN_H
  48
  49 #include <stdio.h>
  50
  51 #include "gromacs/fileio/enxio.h"
  52 #include "gromacs/trajectory/energyframe.h"
  53 #include "gromacs/utility/arrayref.h"
  54 #include "gromacs/utility/basedefinitions.h"
  55
  56 /* \brief Running averaging structure ('energy bin') to store thermodynamic values.
  57  *
  58  * Collects the data on thermodynamic parameters (energy terms, temperature,
  59  * pressure etc.) during the run, including their current and average values.
  60  *
  61  * \todo Clean this structure from unused values.
  62  */
  63 struct t_ebin
  64 {
  65     //! Number of thermodynamic terms
  66     int nener;
  67     //! Name and units for each term
  68     gmx_enxnm_t* enm;
  69     //! Number of steps used for sum (for energy history)
  70     int64_t nsteps;
  71     //! Number of values added to the sum so far
  72     int64_t nsum;
  73     //! Term values: each structure stores current, running average and sum.
  74     t_energy* e;
  75     //! Total number of steps saved (for energy history)
  76     int64_t nsteps_sim;
  77     //! Total number of values added to sum (used when printing average values at the end of the run)
  78     int64_t nsum_sim;
  79     //! Energy values throughout the entire simulation: structure stores current, average and sum, but only sum value is used to compute averages
  80     t_energy* e_sim;
  81 };
  82
  83 /* \brief Type of expected output: normal or average.
  84  */
  85 enum
  86 {
  87     eprNORMAL,
  88     eprAVER,
  89     eprNR
  90 };
  91
  92 /*! \brief Create the structure to store thermodynamic properties*/
  93 t_ebin* mk_ebin();
  94
  95 /*! \brief Destroy the \c eb structure.
  96  *
  97  * \param[in,out] eb  Pointer to the structure to destroy.
  98  */
  99 void done_ebin(t_ebin* eb);
 100
 101 /*! \brief Create space for the extra thermodynamic term(s) and register its(their) name(s).
 102  *
 103  * The enm array must be static, because the contents are not copied, only the pointers.
 104  *
 105  * \param[in] eb     Srtucture in which the space for the termodynamic terms shall be created..
 106  * \param[in] nener  Number of thermodyamic terms to allocate memory for.
 107  * \param[in] enm    Names of the terms.
 108  * \param[in] unit   Units.
 109  *
 110  * \returns          A serial number (index) for the newly allocated terms.
 111  */
 112 int get_ebin_space(t_ebin* eb, int nener, const char* const enm[], const char* unit);
 113
 114 /*! \brief Add current value of the thermodynamic term(s) to the bin(s).
 115  *
 116  * Add nener reals (eg. energies, box-lengths, pressures) to the at position specified by \c
 117  * entryIndex. If bSum is TRUE then the reals are also added to the sum and sum of squares.
 118  *
 119  * \param[in] eb          Structure that stores the thermodynamic values.
 120  * \param[in] entryIndex  Internal index of the term(s) to add.
 121  * \param[in] nener       Number of the terms to add.
 122  * \param[in] ener        Value(s) of thermodynamic term(s) (nener ptc.)
 123  * \param[in] bSum        If the average value should be accumulated for this term(s).
 124  */
 125 void add_ebin(t_ebin* eb, int entryIndex, int nener, const real ener[], gmx_bool bSum);
 126
 127
 128 /*! \brief Add values from array to the bins if the matching entry in \c shouldUse is true.
 129  *
 130  * Caller must ensure that \c shouldUse and \c ener to have the same
 131  * size, and that \c eb has enough room for the number of true
 132  * entries in \c shouldUse.
 133  *
 134  * \param[in] eb          Structure that stores the thermodynamic values.
 135  * \param[in] entryIndex  Internal index of the term(s).
 136  * \param[in] shouldUse   Array of booleans that indicate which terms should be used.
 137  * \param[in] ener        Values of thermodinamic terms to add.
 138  * \param[in] bSum        If the average value should be accumulated for these terms.
 139  */
 140 void add_ebin_indexed(t_ebin*                   eb,
 141                       int                       entryIndex,
 142                       gmx::ArrayRef<bool>       shouldUse,
 143                       gmx::ArrayRef<const real> ener,
 144                       gmx_bool                  bSum);
 145
 146 /*! \brief Increase the counters for the sums.
 147  *
 148  * This routine should be called after all add_ebin calls for this step.
 149  *
 150  * \param[in] increment   How much counts should be increased
 151  * \param[in] eb          Structure that stores the thermodynamic values.
 152  * \param[in] bSum        If the sums counters should be increased as well.
 153  */
 154 void ebin_increase_count(int increment, t_ebin* eb, gmx_bool bSum);
 155
 156
 157 /*! \brief Reset the average and fluctuation sums.
 158  *
 159  * \param[in] eb          Structure that stores the thermodynamic values.
 160  */
 161 void reset_ebin_sums(t_ebin* eb);
 162
 163
 164 /*! \brief Print the contents of some energy bins.
 165  *
 166  * We will print \c nperline entries on a text line (advisory <=
 167  * 5). \c prmode may be any of the above listed enum values. \c tsteps is
 168  * used only when \c eprAVER is set. If \c bPrHead than the
 169  * header is printed.
 170  *
 171  * \c entryIndex and \c nener must be in [0,\c eb->nener), except that \c
 172  * nener -1 is interpreted as \c eb->nener.
 173  *
 174  * \todo Callers should be refactored to pass \c eb->nener, rather than
 175  *       us implement and rely on this special behavior of -1.
 176  *
 177  * \param[in] fp          I/O pointer to print to.
 178  * \param[in] eb          Structure that stores the thermodynamic values.
 179  * \param[in] entryIndex  Internal index of the term(s).
 180  * \param[in] nener       Number of the terms to print.
 181  * \param[in] nperline    Number of values per line.
 182  * \param[in] prmode      Print current (eprNORMAL) or average (eprAVER) values.
 183  * \param[in] bPrHead     If the header should be printed.
 184  */
 185 void pr_ebin(FILE* fp, t_ebin* eb, int entryIndex, int nener, int nperline, int prmode, gmx_bool bPrHead);
 186
 187 #endif