src/api/cpp/mdsignals.cpp

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2018, 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
  36 /*! \file
  37  * \brief Implementation details for MD signalling support.
  38  *
  39  * \ingroup gmxapi_md
  40  */
  41
  42 #include <algorithm>
  43
  44 #include <atomic>
  45
  46 #include <memory>
  47 #include "gromacs/mdlib/simulationsignal.h"
  48 #include "gromacs/mdrun/runner.h"
  49 #include "gromacs/utility/gmxassert.h"
  50
  51 #include "gmxapi/exceptions.h"
  52 #include "gmxapi/session.h"
  53 #include "gmxapi/md/mdsignals.h"
  54
  55 #include "mdsignals.h"
  56 #include "sessionresources.h"
  57
  58 namespace gmxapi
  59 {
  60
  61 //! \cond
  62 Signal::Signal(Signal&&) noexcept = default;
  63 Signal& Signal::operator=(Signal&&) noexcept = default;
  64
  65 Signal::Signal(std::unique_ptr<SignalImpl> impl) : impl_{ std::move(impl) } {}
  66
  67 Signal::~Signal() = default;
  68
  69 void Signal::operator()()
  70 {
  71     impl_->call();
  72 }
  73 //! \endcond
  74
  75 void SignalManager::addSignaller(const std::string& name)
  76 {
  77     called_[name].store(false);
  78 }
  79
  80 /*!
  81  * Implement the SignalImpl interface to provide a logical AND for managed MD signals.
  82  *
  83  * The class is a signal issuer and a signal receiver, but
  84  * \todo signals received by this operation and received by Mdrunner do not yet have a common interface.
  85  *
  86  * Tracks whether each registered input has issued a signal to this operation. When the
  87  * final registered input issues `call()`, the LogicalAND issues `call()` on the output
  88  * signal path.
  89  *
  90  * State is managed by the parent SignalManager. Client code should get a short-lived handle
  91  * to a Signal wrapping this implementation object by calling SignalManager::getSignal()
  92  * with the unique workflow operation name for the block of client code and a gmxapi::md::signals::STOP
  93  * signal argument.
  94  *
  95  * Currently explicitly supports the MD stop signal only.
  96  *
  97  * Version gmxapi 0.0.6:  Also, all registered restraints
  98  * are automatically in the set of ANDed inputs.
  99  *
 100  * \ingroup gmxapi_md
 101  */
 102 class SignalManager::LogicalAND : public Signal::SignalImpl
 103 {
 104 public:
 105     /*!
 106      * \brief Create short-lived signal issuer implementation.
 107      *
 108      * \param manager
 109      * \param name
 110      *
 111      * Caller is responsible for ensuring that the object pointed to by
 112      * manager remains valid for the life time of a LogicalAND instance.
 113      */
 114     LogicalAND(SignalManager* manager, std::string name) : name_(std::move(name)), manager_(manager)
 115     {
 116     }
 117
 118     //! \cond
 119     ~LogicalAND() override = default;
 120     //! \endcond
 121
 122     /*!
 123      * \brief Sets the stop condition when the last issuer issues.
 124      *
 125      * Once all participating signal issuers have called for a stop signal,
 126      * the stop condition state is updated to stopAtNextNSStep.
 127      */
 128     void call() override
 129     {
 130         auto& callCounter = manager_->called_.at(name_);
 131         callCounter.store(true);
 132         using pairType = typename decltype(manager_->called_)::value_type;
 133         if (std::all_of(manager_->called_.cbegin(), manager_->called_.cend(),
 134                         [](const pairType& p) { return p.second.load(); }))
 135         {
 136             *manager_->state_ = gmx::StopSignal::stopAtNextNSStep;
 137         }
 138     }
 139
 140 private:
 141     //! Named signal issuer for the current operation.
 142     const std::string name_;
 143
 144     //! The manager that generated this function object.
 145     SignalManager* manager_;
 146 };
 147
 148 Signal SignalManager::getSignal(const std::string& name, md::signals signal)
 149 {
 150     if (called_.find(name) == called_.end())
 151     {
 152         std::string message = name + " is not registered for this signal.";
 153         throw gmxapi::ProtocolError(std::move(message));
 154     }
 155
 156     if (signal != md::signals::STOP)
 157     {
 158         throw gmxapi::NotImplementedError("This signaller only handles stop signals.");
 159     }
 160
 161     auto signalImpl = std::make_unique<LogicalAND>(this, name);
 162     auto functor    = Signal(std::move(signalImpl));
 163     return functor;
 164 }
 165
 166 Signal getMdrunnerSignal(SessionResources* resources, md::signals signal)
 167 {
 168     // while there is only one choice...
 169     if (signal != md::signals::STOP)
 170     {
 171         throw gmxapi::NotImplementedError("This signaller only handles stop signals.");
 172     }
 173
 174     if (resources == nullptr)
 175     {
 176         throw gmxapi::UsageError(
 177                 "Caller must provide a valid SessionResources to getMdrunnerSignal.");
 178     }
 179
 180     auto signaller = resources->getMdrunnerSignal(signal);
 181
 182     return signaller;
 183 }
 184
 185 } // end namespace gmxapi