src/gromacs/mdlib/simulationsignal.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) 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