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, 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
  61 namespace gmx
  62 {
  63
  64 struct MdModulesNotifier;
  65 class KeyValueTreeObject;
  66 class ReadCheckpointDataHolder;
  67 class WriteCheckpointDataHolder;
  68
  69 /*! \brief Read to a key-value-tree value used for checkpointing.
  70  *
  71  * \tparam ValueType
  72  *
  73  * \param[in] value the value to be checkpointed
  74  * \param[in] name name of the value to be checkpointed
  75  * \param[in] identifier uniquely identifies the module that is checkpointing
  76  *                       typically the module name
  77  * \param[in] kvt the key value tree to read from
  78  *
  79  * \throws InternalError if kvt does not contain requested value.
  80  * \note Triggers assertion if value type is not correct.
  81  */
  82 template<typename ValueType>
  83 void readKvtCheckpointValue(compat::not_null<ValueType*> value,
  84                             const std::string&           name,
  85                             const std::string&           identifier,
  86                             const KeyValueTreeObject&    kvt);
  87 //! \copydoc readKvtCheckpointValue
  88 extern template void readKvtCheckpointValue(compat::not_null<std::int64_t*> value,
  89                                             const std::string&              name,
  90                                             const std::string&              identifier,
  91                                             const KeyValueTreeObject&       kvt);
  92 //! \copydoc readKvtCheckpointValue
  93 extern template void readKvtCheckpointValue(compat::not_null<real*>   value,
  94                                             const std::string&        name,
  95                                             const std::string&        identifier,
  96                                             const KeyValueTreeObject& kvt);
  97
  98 /*! \brief Write to a key-value-tree used for checkpointing.
  99  *
 100  * \tparam ValueType
 101  *
 102  * \param[in] value name of the value to be checkpointed
 103  * \param[in] name the value to be checkpointed
 104  * \param[in] identifier uniquely identifies the module that is checkpointing
 105  *                       typically the module name
 106  * \param[in] kvtBuilder the key-value-tree builder used to store the checkpoint values
 107  */
 108 template<typename ValueType>
 109 void writeKvtCheckpointValue(const ValueType&          value,
 110                              const std::string&        name,
 111                              const std::string&        identifier,
 112                              KeyValueTreeObjectBuilder kvtBuilder);
 113 //! \copydoc writeKvtCheckpointValue
 114 extern template void writeKvtCheckpointValue(const std::int64_t&       value,
 115                                              const std::string&        name,
 116                                              const std::string&        identifier,
 117                                              KeyValueTreeObjectBuilder kvtBuilder);
 118 //! \copydoc writeKvtCheckpointValue
 119 extern template void writeKvtCheckpointValue(const real&               value,
 120                                              const std::string&        name,
 121                                              const std::string&        identifier,
 122                                              KeyValueTreeObjectBuilder kvtBuilder);
 123
 124 /*! \libinternal
 125  * \brief Provides the MdModules with the checkpointed data on the master rank.
 126  */
 127 struct MdModulesCheckpointReadingDataOnMaster
 128 {
 129     //! The data of the MdModules that is stored in the checkpoint file
 130     const KeyValueTreeObject& checkpointedData_;
 131     //! The version of the read ceckpoint file
 132     int checkpointFileVersion_;
 133 };
 134
 135 /*! \libinternal
 136  * \brief Provides the MdModules with the communication record to broadcast.
 137  */
 138 struct MdModulesCheckpointReadingBroadcast
 139 {
 140     //! The communicator
 141     MPI_Comm communicator_;
 142     //! Whether the run is executed in parallel
 143     bool isParallelRun_;
 144     //! The version of the read file version
 145     int checkpointFileVersion_;
 146 };
 147
 148 /*! \libinternal \brief Writing the MdModules data to a checkpoint file.
 149  */
 150 struct MdModulesWriteCheckpointData
 151 {
 152     //! Builder for the Key-Value-Tree to store the MdModule checkpoint data
 153     KeyValueTreeObjectBuilder builder_;
 154     //! The version of the read file version
 155     int checkpointFileVersion_;
 156 };
 157
 158 } // namespace gmx
 159
 160 /* the name of the environment variable to disable fsync failure checks with */
 161 #define GMX_IGNORE_FSYNC_FAILURE_ENV "GMX_IGNORE_FSYNC_FAILURE"
 162
 163 // TODO Replace this mechanism with std::array<char, 1024> or similar.
 164 #define CPTSTRLEN 1024
 165
 166 /*!
 167  * \brief
 168  * Header explaining the context of a checkpoint file.
 169  *
 170  * TODO Expand this into being a container of all data for
 171  * serialization of a checkpoint, which can be stored by the caller
 172  * (e.g. so that mdrun doesn't have to open the checkpoint twice).
 173  * This will separate issues of allocation from those of
 174  * serialization, help separate comparison from reading, and have
 175  * better defined transformation functions to/from trajectory frame
 176  * data structures.
 177  *
 178  * Several fields were once written to checkpoint file headers, but
 179  * have been removed. So that old files can continue to be read,
 180  * the names of such fields contain the string "_UNUSED" so that it
 181  * is clear they should not be used.
 182  */
 183 struct CheckpointHeaderContents
 184 {
 185     //! Version of checkpoint file read from disk.
 186     int file_version;
 187     //! Version string.
 188     char version[CPTSTRLEN];
 189     //! Deprecated string for time.
 190     char btime_UNUSED[CPTSTRLEN];
 191     //! Deprecated string for user.
 192     char buser_UNUSED[CPTSTRLEN];
 193     //! Deprecated string for host.
 194     char bhost_UNUSED[CPTSTRLEN];
 195     //! Value for precision.
 196     int double_prec;
 197     //! Program string.
 198     char fprog[CPTSTRLEN];
 199     //! Time string.
 200     char ftime[CPTSTRLEN];
 201     //! Which integrator is in use.
 202     int eIntegrator;
 203     //! Which part of the simulation this is.
 204     int simulation_part;
 205     //! Which step the checkpoint is at.
 206     int64_t step;
 207     //! Current simulation time.
 208     double t;
 209     //! Number of nodes used for simulation,
 210     int nnodes;
 211     //! Domain decomposition settings?
 212     ivec dd_nc;
 213     //! Number of separate PME ranks.
 214     int npme;
 215     //! Number of atoms.
 216     int natoms;
 217     //! Number of temperature coupling groups.
 218     int ngtc;
 219     //! Number of Nose-Hoover pressure coupling chains.
 220     int nnhpres;
 221     //! Length of Nose-Hoover chains.
 222     int nhchainlength;
 223     //! Current FEP lambda state.
 224     int nlambda;
 225     //! Current state flags.
 226     int flags_state;
 227     //! Flags for kinetic energy.
 228     int flags_eks;
 229     //! Flags for energy history.
 230     int flags_enh;
 231     //! Flags for pull history.
 232     int flagsPullHistory;
 233     //! Flags for mystery history.
 234     int flags_dfh;
 235     //! Flags for AWH history.
 236     int flags_awhh;
 237     //! Essential dynamics states.
 238     int nED;
 239     //! Enum for coordinate swapping.
 240     int eSwapCoords;
 241     //! Whether the checkpoint was written by modular simulator.
 242     bool isModularSimulatorCheckpoint = false;
 243 };
 244
 245 /*! \brief Low-level checkpoint writing function */
 246 void write_checkpoint_data(t_fileio*                         fp,
 247                            CheckpointHeaderContents          headerContents,
 248                            gmx_bool                          bExpanded,
 249                            int                               elamstats,
 250                            t_state*                          state,
 251                            ObservablesHistory*               observablesHistory,
 252                            const gmx::MdModulesNotifier&     notifier,
 253                            std::vector<gmx_file_position_t>* outputfiles,
 254                            gmx::WriteCheckpointDataHolder*   modularSimulatorCheckpointData);
 255
 256 /* Loads a checkpoint from fn for run continuation.
 257  * Generates a fatal error on system size mismatch.
 258  * The master node reads the file
 259  * and communicates all the modified number of steps,
 260  * but not the state itself.
 261  * With reproducibilityRequested warns about version, build, #ranks differences.
 262  */
 263 void load_checkpoint(const char*                    fn,
 264                      t_fileio*                      logfio,
 265                      const t_commrec*               cr,
 266                      const ivec                     dd_nc,
 267                      t_inputrec*                    ir,
 268                      t_state*                       state,
 269                      ObservablesHistory*            observablesHistory,
 270                      gmx_bool                       reproducibilityRequested,
 271                      const gmx::MdModulesNotifier&  mdModulesNotifier,
 272                      gmx::ReadCheckpointDataHolder* modularSimulatorCheckpointData,
 273                      bool                           useModularSimulator);
 274
 275 /* Read everything that can be stored in t_trxframe from a checkpoint file */
 276 void read_checkpoint_trxframe(struct t_fileio* fp, t_trxframe* fr);
 277
 278 /* Print the complete contents of checkpoint file fn to out */
 279 void list_checkpoint(const char* fn, FILE* out);
 280
 281 /*!\brief Read simulation step and part from a checkpoint file
 282  *
 283  * Used by tune_pme to handle tuning with a checkpoint file as part of the input.
 284  *
 285  * \param[in]  filename         Name of checkpoint file
 286  * \param[out] simulation_part  The part of the simulation that wrote the checkpoint
 287  * \param[out] step             The final step number of the simulation that wrote the checkpoint
 288  *
 289  * The output variables will both contain 0 if filename is NULL, the file
 290  * does not exist, or is not readable. */
 291 void read_checkpoint_part_and_step(const char* filename, int* simulation_part, int64_t* step);
 292
 293 /*!\brief Return header information from an open checkpoint file.
 294  *
 295  * Used by mdrun to handle restarts
 296  *
 297  * \param[in]  fp               Handle to open checkpoint file
 298  * \param[out] outputfiles      Container of output file names from the previous run. */
 299 CheckpointHeaderContents
 300 read_checkpoint_simulation_part_and_filenames(t_fileio* fp, std::vector<gmx_file_position_t>* outputfiles);
 301
 302 #endif