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) 2011,2014,2015,2016,2018 by the GROMACS development team. 7 * Copyright (c) 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 /*! \file 39 * 40 * \brief This file declares functions for inter-rank signalling by mdrun 41 * 42 * This handles details of responding to termination conditions, 43 * coordinating checkpoints, and coordinating multi-simulations. 44 * 45 * \todo Move this to mdrunutility module alongside gathering 46 * multi-simulation communication infrastructure there. 47 * 48 * \author Berk Hess <hess@kth.se> 49 * \author Mark Abraham <mark.j.abraham@gmail.com> 50 * \inlibraryapi 51 * \ingroup module_mdlib 52 */ 53 #ifndef GMX_MDLIB_SIMULATIONSIGNAL_H 54 #define GMX_MDLIB_SIMULATIONSIGNAL_H 55 56 #include <array> 57 58 #include "gromacs/utility/real.h" 59 60 struct gmx_multisim_t; 61 struct t_commrec; 62 63 //! Kinds of simulation conditions to signal about. 64 enum 65 { 66 eglsCHKPT, 67 eglsSTOPCOND, 68 eglsRESETCOUNTERS, 69 eglsNR 70 }; 71 72 namespace gmx 73 { 74 75 template<typename T> 76 class ArrayRef; 77 78 /*! 79 * \brief POD-style object used by mdrun ranks to set and 80 * receive signals within and between simulations. 81 * 82 * Keep in mind that the values of signals are transmitted to other 83 * ranks through an MPI_Reduce after casting them to a real (so the 84 * signals can be sent together with other data). This means that the 85 * only meaningful values are positive, negative or zero. 86 * 87 * isLocal permits (for example) replica-exchange to require that any 88 * checkpointing is synchronized across all simulations, by setting 89 * isLocal to false, so that the trigger for action is set only when 90 * inter-simulation signalling happens. Replica-exchange can 91 * coordinate this at run time when a SimulationSignaller is made. */ 92 class SimulationSignal 93 { 94 public: 95 //! Constructor 96 SimulationSignal(bool isSignalLocal = true) : sig(0), set(0), isLocal(isSignalLocal) {} 97 //! The signal set by this rank in do_md(). 98 signed char sig; 99 //! The communicated signal that triggers action, which will be equal for all ranks, once communication has occured. 100 signed char set; 101 //! Is the signal in one simulation independent of other simulations? 102 bool isLocal; 103 }; 104 105 //! Convenience typedef for the group of signals used. 106 typedef std::array<SimulationSignal, eglsNR> SimulationSignals; 107 108 /*! 109 * \brief Object used by mdrun ranks to signal to each other at this step. 110 * 111 * This object has responsibility to read signal values from \c gs, 112 * coordinate communication within and perhaps between simulations, 113 * and set result signal values in \c gs as appropriate. 114 * 115 * It is intended to have a very short lifetime, so should remain easy 116 * to construct and destruct on the stack just when the global 117 * communication occurs. */ 118 class SimulationSignaller 119 { 120 public: 121 //! Constructor 122 SimulationSignaller(SimulationSignals* signals, 123 const t_commrec* cr, 124 const gmx_multisim_t* ms, 125 bool doInterSim, 126 bool doIntraSim); 127 /*! \brief Return a reference to an array of signal values to communicate. 128 * 129 * \return If intra-sim signalling will take place, fill and 130 * return a reference to the array of reals in which signals 131 * will be communicated with the signal values to be 132 * sent. Otherwise return a EmptyArrayRef. */ 133 gmx::ArrayRef<real> getCommunicationBuffer(); 134 /*! \brief Handle inter-simulation signal communication. 135 * 136 * If an inter-simulation signal should be handled, communicate between 137 * simulation-master ranks, then propagate from the masters to the 138 * rest of the ranks for each simulation. It is the responsibility of 139 * the calling code to ensure that any necessary intra-simulation 140 * signalling has already occurred, e.g. in global_stat(). */ 141 void signalInterSim(); 142 /*! \brief Propagate signals when appropriate. 143 * 144 * Always propagate an mdrun signal value when doing 145 * inter-simulation signalling; otherwise, propagate it only 146 * if should be propagated within this simulation, 147 * ie. locally. See documentation of SimulationSignal for 148 * details. */ 149 void setSignals(); 150 //! Convenience wrapper that calls signalInterSim() then setSignals(). 151 void finalizeSignals(); 152 153 private: 154 //! Source and sink for mdrun signals 155 SimulationSignals* signals_; 156 //! Communication object. 157 const t_commrec* cr_; 158 //! Multi-sim handler. 159 const gmx_multisim_t* ms_; 160 //! Do inter-sim communication at this step. 161 bool doInterSim_; 162 //! Do intra-sim communication at this step. 163 bool doIntraSim_; 164 //! Buffer for MPI communication. 165 std::array<real, eglsNR> mpiBuffer_; 166 }; 167 168 } // namespace gmx 169 170 #endif 171