src/gromacs/fileio/checkpoint.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,2016,2017 by the GROMACS development team.
   7  * Copyright (c) 2018,2019,2020,2021, by the GROMACS development team, led by
   8  * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   9  * and including many others, as listed in the AUTHORS file in the
  10  * top-level source directory and at http://www.gromacs.org.
  11  *
  12  * GROMACS is free software; you can redistribute it and/or
  13  * modify it under the terms of the GNU Lesser General Public License
  14  * as published by the Free Software Foundation; either version 2.1
  15  * of the License, or (at your option) any later version.
  16  *
  17  * GROMACS is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  20  * Lesser General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU Lesser General Public
  23  * License along with GROMACS; if not, see
  24  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  25  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  26  *
  27  * If you want to redistribute modifications to GROMACS, please
  28  * consider that scientific software is very special. Version
  29  * control is crucial - bugs must be traceable. We will be happy to
  30  * consider code for inclusion in the official distribution, but
  31  * derived work must not be called official GROMACS. Details are found
  32  * in the README & COPYING files - if they are missing, get the
  33  * official version at http://www.gromacs.org.
  34  *
  35  * To help us fund GROMACS development, we humbly ask that you cite
  36  * the research papers on the package. Check out http://www.gromacs.org.
  37  */
  38
  39 #ifndef _checkpoint_h
  40 #define _checkpoint_h
  41
  42 #include <cstdio>
  43
  44 #include <vector>
  45
  46 #include "gromacs/compat/pointers.h"
  47 #include "gromacs/math/vectypes.h"
  48 #include "gromacs/utility/basedefinitions.h"
  49 #include "gromacs/utility/gmxmpi.h"
  50 #include "gromacs/utility/keyvaluetreebuilder.h"
  51
  52 class energyhistory_t;
  53 struct gmx_file_position_t;
  54 struct ObservablesHistory;
  55 struct t_commrec;
  56 struct t_fileio;
  57 struct t_inputrec;
  58 class t_state;
  59 struct t_trxframe;
  60 enum class IntegrationAlgorithm : int;
  61 enum class SwapType : int;
  62 enum class LambdaWeightCalculation : int;
  63
  64 namespace gmx
  65 {
  66
  67 struct MdModulesNotifier;
  68 class KeyValueTreeObject;
  69 class ReadCheckpointDataHolder;
  70 class WriteCheckpointDataHolder;
  71
  72 /*! \brief Read to a key-value-tree value used for checkpointing.
  73  *
  74  * \tparam ValueType
  75  *
  76  * \param[in] value the value to be checkpointed
  77  * \param[in] name name of the value to be checkpointed
  78  * \param[in] identifier uniquely identifies the module that is checkpointing
  79  *                       typically the module name
  80  * \param[in] kvt the key value tree to read from
  81  *
  82  * \throws InternalError if kvt does not contain requested value.
  83  * \note Triggers assertion if value type is not correct.
  84  */
  85 template<typename ValueType>
  86 void readKvtCheckpointValue(compat::not_null<ValueType*> value,
  87                             const std::string&           name,
  88                             const std::string&           identifier,
  89                             const KeyValueTreeObject&    kvt);
  90 //! \copydoc readKvtCheckpointValue
  91 extern template void readKvtCheckpointValue(compat::not_null<std::int64_t*> value,
  92                                             const std::string&              name,
  93                                             const std::string&              identifier,
  94                                             const KeyValueTreeObject&       kvt);
  95 //! \copydoc readKvtCheckpointValue
  96 extern template void readKvtCheckpointValue(compat::not_null<real*>   value,
  97                                             const std::string&        name,
  98                                             const std::string&        identifier,
  99                                             const KeyValueTreeObject& kvt);
 100
 101 /*! \brief Write to a key-value-tree used for checkpointing.
 102  *
 103  * \tparam ValueType
 104  *
 105  * \param[in] value name of the value to be checkpointed
 106  * \param[in] name the value to be checkpointed
 107  * \param[in] identifier uniquely identifies the module that is checkpointing
 108  *                       typically the module name
 109  * \param[in] kvtBuilder the key-value-tree builder used to store the checkpoint values
 110  */
 111 template<typename ValueType>
 112 void writeKvtCheckpointValue(const ValueType&          value,
 113                              const std::string&        name,
 114                              const std::string&        identifier,
 115                              KeyValueTreeObjectBuilder kvtBuilder);
 116 //! \copydoc writeKvtCheckpointValue
 117 extern template void writeKvtCheckpointValue(const std::int64_t&       value,
 118                                              const std::string&        name,
 119                                              const std::string&        identifier,
 120                                              KeyValueTreeObjectBuilder kvtBuilder);
 121 //! \copydoc writeKvtCheckpointValue
 122 extern template void writeKvtCheckpointValue(const real&               value,
 123                                              const std::string&        name,
 124                                              const std::string&        identifier,
 125                                              KeyValueTreeObjectBuilder kvtBuilder);
 126
 127 /*! \libinternal
 128  * \brief Provides the MdModules with the checkpointed data on the master rank.
 129  */
 130 struct MdModulesCheckpointReadingDataOnMaster
 131 {
 132     //! The data of the MdModules that is stored in the checkpoint file
 133     const KeyValueTreeObject& checkpointedData_;
 134     //! The version of the read ceckpoint file
 135     int checkpointFileVersion_;
 136 };
 137
 138 /*! \libinternal
 139  * \brief Provides the MdModules with the communication record to broadcast.
 140  */
 141 struct MdModulesCheckpointReadingBroadcast
 142 {
 143     //! The communicator
 144     MPI_Comm communicator_;
 145     //! Whether the run is executed in parallel
 146     bool isParallelRun_;
 147     //! The version of the read file version
 148     int checkpointFileVersion_;
 149 };
 150
 151 /*! \libinternal \brief Writing the MdModules data to a checkpoint file.
 152  */
 153 struct MdModulesWriteCheckpointData
 154 {
 155     //! Builder for the Key-Value-Tree to store the MdModule checkpoint data
 156     KeyValueTreeObjectBuilder builder_;
 157     //! The version of the read file version
 158     int checkpointFileVersion_;
 159 };
 160
 161 } // namespace gmx
 162
 163 /* the name of the environment variable to disable fsync failure checks with */
 164 #define GMX_IGNORE_FSYNC_FAILURE_ENV "GMX_IGNORE_FSYNC_FAILURE"
 165
 166 // TODO Replace this mechanism with std::array<char, 1024> or similar.
 167 #define CPTSTRLEN 1024
 168
 169 /*!
 170  * \brief
 171  * Header explaining the context of a checkpoint file.
 172  *
 173  * TODO Expand this into being a container of all data for
 174  * serialization of a checkpoint, which can be stored by the caller
 175  * (e.g. so that mdrun doesn't have to open the checkpoint twice).
 176  * This will separate issues of allocation from those of
 177  * serialization, help separate comparison from reading, and have
 178  * better defined transformation functions to/from trajectory frame
 179  * data structures.
 180  *
 181  * Several fields were once written to checkpoint file headers, but
 182  * have been removed. So that old files can continue to be read,
 183  * the names of such fields contain the string "_UNUSED" so that it
 184  * is clear they should not be used.
 185  */
 186 struct CheckpointHeaderContents
 187 {
 188     //! Version of checkpoint file read from disk.
 189     int file_version;
 190     //! Version string.
 191     char version[CPTSTRLEN];
 192     //! Deprecated string for time.
 193     char btime_UNUSED[CPTSTRLEN];
 194     //! Deprecated string for user.
 195     char buser_UNUSED[CPTSTRLEN];
 196     //! Deprecated string for host.
 197     char bhost_UNUSED[CPTSTRLEN];
 198     //! Value for precision.
 199     int double_prec;
 200     //! Program string.
 201     char fprog[CPTSTRLEN];
 202     //! Time string.
 203     char ftime[CPTSTRLEN];
 204     //! Which integrator is in use.
 205     IntegrationAlgorithm eIntegrator;
 206     //! Which part of the simulation this is.
 207     int simulation_part;
 208     //! Which step the checkpoint is at.
 209     int64_t step;
 210     //! Current simulation time.
 211     double t;
 212     //! Number of nodes used for simulation,
 213     int nnodes;
 214     //! Domain decomposition settings?
 215     ivec dd_nc;
 216     //! Number of separate PME ranks.
 217     int npme;
 218     //! Number of atoms.
 219     int natoms;
 220     //! Number of temperature coupling groups.
 221     int ngtc;
 222     //! Number of Nose-Hoover pressure coupling chains.
 223     int nnhpres;
 224     //! Length of Nose-Hoover chains.
 225     int nhchainlength;
 226     //! Current FEP lambda state.
 227     int nlambda;
 228     //! Current state flags.
 229     int flags_state;
 230     //! Flags for kinetic energy.
 231     int flags_eks;
 232     //! Flags for energy history.
 233     int flags_enh;
 234     //! Flags for pull history.
 235     int flagsPullHistory;
 236     //! Flags for mystery history.
 237     int flags_dfh;
 238     //! Flags for AWH history.
 239     int flags_awhh;
 240     //! Essential dynamics states.
 241     int nED;
 242     //! Enum for coordinate swapping.
 243     SwapType eSwapCoords;
 244     //! Whether the checkpoint was written by modular simulator.
 245     bool isModularSimulatorCheckpoint = false;
 246 };
 247
 248 /*! \brief Low-level checkpoint writing function */
 249 void write_checkpoint_data(t_fileio*                         fp,
 250                            CheckpointHeaderContents          headerContents,
 251                            gmx_bool                          bExpanded,
 252                            LambdaWeightCalculation           elamstats,
 253                            t_state*                          state,
 254                            ObservablesHistory*               observablesHistory,
 255                            const gmx::MdModulesNotifier&     notifier,
 256                            std::vector<gmx_file_position_t>* outputfiles,
 257                            gmx::WriteCheckpointDataHolder*   modularSimulatorCheckpointData);
 258
 259 /* Loads a checkpoint from fn for run continuation.
 260  * Generates a fatal error on system size mismatch.
 261  * The master node reads the file
 262  * and communicates all the modified number of steps,
 263  * but not the state itself.
 264  * With reproducibilityRequested warns about version, build, #ranks differences.
 265  */
 266 void load_checkpoint(const char*                    fn,
 267                      t_fileio*                      logfio,
 268                      const t_commrec*               cr,
 269                      const ivec                     dd_nc,
 270                      t_inputrec*                    ir,
 271                      t_state*                       state,
 272                      ObservablesHistory*            observablesHistory,
 273                      gmx_bool                       reproducibilityRequested,
 274                      const gmx::MdModulesNotifier&  mdModulesNotifier,
 275                      gmx::ReadCheckpointDataHolder* modularSimulatorCheckpointData,
 276                      bool                           useModularSimulator);
 277
 278 /* Read everything that can be stored in t_trxframe from a checkpoint file */
 279 void read_checkpoint_trxframe(struct t_fileio* fp, t_trxframe* fr);
 280
 281 /* Print the complete contents of checkpoint file fn to out */
 282 void list_checkpoint(const char* fn, FILE* out);
 283
 284 /*!\brief Read simulation step and part from a checkpoint file
 285  *
 286  * Used by tune_pme to handle tuning with a checkpoint file as part of the input.
 287  *
 288  * \param[in]  filename         Name of checkpoint file
 289  * \param[out] simulation_part  The part of the simulation that wrote the checkpoint
 290  * \param[out] step             The final step number of the simulation that wrote the checkpoint
 291  *
 292  * The output variables will both contain 0 if filename is NULL, the file
 293  * does not exist, or is not readable. */
 294 void read_checkpoint_part_and_step(const char* filename, int* simulation_part, int64_t* step);
 295
 296 /*!\brief Return header information from an open checkpoint file.
 297  *
 298  * Used by mdrun to handle restarts
 299  *
 300  * \param[in]  fp               Handle to open checkpoint file
 301  * \param[out] outputfiles      Container of output file names from the previous run. */
 302 CheckpointHeaderContents
 303 read_checkpoint_simulation_part_and_filenames(t_fileio* fp, std::vector<gmx_file_position_t>* outputfiles);
 304
 305 #endif