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