src/gromacs/mdrun/simulationinput.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2020, 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 /*! \libinternal \file
  36  * \brief Utilities for interacting with SimulationInput.
  37  *
  38  * \author M. Eric Irrgang <ericirrgang@gmail.com>
  39  * \ingroup module_mdrun
  40  * \inlibraryapi
  41  */
  42
  43 #ifndef GMX_MDRUN_SIMULATIONINPUT_H
  44 #define GMX_MDRUN_SIMULATIONINPUT_H
  45
  46 #include <memory>
  47 #include <string>
  48
  49 #include "gromacs/mdrun/simulationinputhandle.h"
  50 #include "gromacs/mdtypes/checkpointdata.h"
  51 #include "gromacs/utility/mdmodulenotification.h"
  52
  53 // Forward declarations for types from other modules that are opaque to the public API.
  54 // TODO: Document the sources of these symbols or import a (self-documenting) fwd header.
  55 struct gmx_mtop_t;
  56 struct t_commrec;
  57 struct t_fileio;
  58 struct t_inputrec;
  59 class t_state;
  60 struct ObservablesHistory;
  61 struct PartialDeserializedTprFile;
  62
  63 namespace gmx
  64 {
  65 /*
  66  * \brief Prescription for molecular simulation.
  67  *
  68  * In the first implementation, this is a POD struct to allow removal of direct
  69  * references to TPR and CPT files from Mdrunner. The interface for SimulationInput
  70  * should be considered to be *completely unspecified* until resolution of
  71  * https://gitlab.com/gromacs/gromacs/-/issues/3374
  72  *
  73  * Clients should use the utility functions defined in simulationinpututility.h
  74  *
  75  * Design note: It is probably sufficient for future versions to compose SimulationInput
  76  * through a Builder rather than to subclass an Interface or base class. Outside of this
  77  * translation unit, we should avoid coupling to the class definition until/unless we
  78  * develop a much better understanding of simulation input portability.
  79  */
  80 class SimulationInput
  81 {
  82 public:
  83     SimulationInput(const char* tprFilename, const char* cpiFilename);
  84
  85     std::string tprFilename_;
  86     std::string cpiFilename_;
  87 };
  88
  89 /*! \brief Get the global simulation input.
  90  *
  91  * Acquire global simulation data structures from the SimulationInput handle.
  92  * Note that global data is returned in the calling thread. In parallel
  93  * computing contexts, the client is responsible for calling only where needed.
  94  *
  95  * Example:
  96  *    if (SIMMASTER(cr))
  97  *    {
  98  *        // Only the master rank has the global state
  99  *        globalState = globalSimulationState(simulationInput);
 100  *
 101  *        // Read (nearly) all data required for the simulation
 102  *        applyGlobalInputRecord(simulationInput, inputrec);
 103  *        applyGlobalTopology(simulationInput, &mtop);
 104  *     }
 105  *
 106  * \todo Factor the logic for global/local and master-rank-checks.
 107  * The SimulationInput utilities should behave properly for the various distributed data scenarios.
 108  * Consider supplying data directly to the consumers rather than exposing the
 109  * implementation details of the legacy aggregate types.
 110  *
 111  * \{
 112  */
 113 // TODO: Remove this monolithic detail as member data can be separately cached and managed. (#3374)
 114 // Note that clients still need tpxio.h for PartialDeserializedTprFile.
 115 void applyGlobalSimulationState(const SimulationInput&      simulationInput,
 116                                 PartialDeserializedTprFile* partialDeserializedTpr,
 117                                 t_state*                    globalState,
 118                                 t_inputrec*                 inputrec,
 119                                 gmx_mtop_t*                 globalTopology);
 120 // TODO: Implement the following, pending further discussion re #3374.
 121 std::unique_ptr<t_state> globalSimulationState(const SimulationInput&);
 122 void                     applyGlobalInputRecord(const SimulationInput&, t_inputrec*);
 123 void                     applyGlobalTopology(const SimulationInput&, gmx_mtop_t*);
 124 //! \}
 125
 126 /*! \brief Initialize local stateful simulation data.
 127  *
 128  * Establish an invariant for the simulator at a trajectory point.
 129  * Call on all ranks (after domain decomposition and task assignments).
 130  *
 131  * After this call, the simulator has all of the information it will
 132  * receive in order to advance a trajectory from the current step.
 133  * Checkpoint information has been applied, if applicable, and stateful
 134  * data has been (re)initialized.
 135  *
 136  * \warning Mdrunner instances do not clearly distinguish between global and local
 137  * versions of t_state.
 138  *
 139  * \todo Factor the distributed data aspects of simulation input data into the
 140  *       SimulationInput implementation.
 141  *
 142  * \todo Consider refactoring to decouple the checkpoint facility from its consumers
 143  *       (state, observablesHistory, mdModulesNotifier, and parts of ir).
 144  *
 145  * \warning It is the caller’s responsibility to make sure that
 146  * preconditions are satisfied for the parameter objects.
 147  *
 148  * \see globalSimulationState()
 149  * \see applyGlobalInputRecord()
 150  * \see applyGlobalTopology()
 151  */
 152 void applyLocalState(const SimulationInput&         simulationInput,
 153                      t_fileio*                      logfio,
 154                      const t_commrec*               cr,
 155                      int*                           dd_nc,
 156                      t_inputrec*                    ir,
 157                      t_state*                       state,
 158                      ObservablesHistory*            observablesHistory,
 159                      bool                           reproducibilityRequested,
 160                      const MdModulesNotifier&       notifier,
 161                      gmx::ReadCheckpointDataHolder* modularSimulatorCheckpointData,
 162                      bool                           useModularSimulator);
 163
 164 } // end namespace gmx
 165
 166 #endif // GMX_MDRUN_SIMULATIONINPUT_H