src/gromacs/utility/mdmodulenotification.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2019,2020,2021, 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
  37  * Declares gmx::MdModulesNotifier.
  38  *
  39  * \author Christian Blau <blau@kth.se>
  40  * \inlibraryapi
  41  * \ingroup module_utility
  42  */
  43
  44 #ifndef GMX_UTILITY_MDMODULENOTIFICATION_H
  45 #define GMX_UTILITY_MDMODULENOTIFICATION_H
  46
  47 #include <string>
  48 #include <vector>
  49
  50 #include "gromacs/utility/mdmodulenotification-impl.h"
  51
  52 struct t_commrec;
  53 enum class PbcType : int;
  54
  55 namespace gmx
  56 {
  57
  58 class KeyValueTreeObject;
  59 class KeyValueTreeObjectBuilder;
  60 class LocalAtomSetManager;
  61 class IndexGroupsAndNames;
  62 class SeparatePmeRanksPermitted;
  63 struct MdModulesCheckpointReadingDataOnMaster;
  64 struct MdModulesCheckpointReadingBroadcast;
  65 struct MdModulesWriteCheckpointData;
  66
  67 /*! \libinternal \brief Check if module outputs energy to a specific field.
  68  *
  69  * Ensures that energy is output for this module.
  70  */
  71 struct MdModulesEnergyOutputToDensityFittingRequestChecker
  72 {
  73     //! Trigger output to density fitting energy field
  74     bool energyOutputToDensityFitting_ = false;
  75 };
  76
  77 /*! \libinternal
  78  * \brief Collect errors for the energy calculation frequency.
  79  *
  80  * Collect errors regarding energy calculation frequencies as strings that then
  81  * may be used to issue errors.
  82  *
  83  * \note The mdp option "nstcalcenergy" is altered after reading the .mdp input
  84  *       and only used in certain integrators, thus this class is to be used
  85  *       only after all these operations are done.
  86  */
  87 class EnergyCalculationFrequencyErrors
  88 {
  89 public:
  90     //! Construct by setting the energy calculation frequency
  91     EnergyCalculationFrequencyErrors(int64_t energyCalculationIntervalInSteps) :
  92         energyCalculationIntervalInSteps_(energyCalculationIntervalInSteps)
  93     {
  94     }
  95     //! Return the number of steps of an energy calculation interval
  96     std::int64_t energyCalculationIntervalInSteps() const
  97     {
  98         return energyCalculationIntervalInSteps_;
  99     }
 100     //! Collect error messages
 101     void addError(const std::string& errorMessage) { errorMessages_.push_back(errorMessage); }
 102     //! Return error messages
 103     const std::vector<std::string>& errorMessages() const { return errorMessages_; }
 104
 105 private:
 106     //! The frequency of energy calculations
 107     const std::int64_t energyCalculationIntervalInSteps_;
 108     //! The error messages
 109     std::vector<std::string> errorMessages_;
 110 };
 111
 112 /*! \libinternal \brief Provides the simulation time step in ps.
 113  */
 114 struct SimulationTimeStep
 115 {
 116     //! Time step (ps)
 117     const double delta_t;
 118 };
 119
 120 /*! \libinternal
 121  * \brief Collection of callbacks to MDModules at differnt run-times.
 122  *
 123  * MDModules use members of this struct to sign up for callback functionality.
 124  *
 125  * The members of the struct represent callbacks at these run-times:
 126  *
 127  *  When pre-processing the simulation data
 128  *  When reading and writing check-pointing data
 129  *  When setting up simulation after reading in the tpr file
 130  *
 131    \msc
 132    wordwraparcs=true,
 133    hscale="2";
 134
 135    runner [label="runner:\nMdrunner"],
 136    CallParameter [label = "eventA:\nCallParameter"],
 137    MOD [label = "mdModules_:\nMdModules"],
 138    ModuleA [label="moduleA"],
 139    ModuleB [label="moduleB"],
 140    MdModuleNotification [label="notifier_:\nMdModuleNotification"];
 141
 142    MOD box MdModuleNotification [label = "mdModules_ owns notifier_ and moduleA/B"];
 143    MOD =>> ModuleA [label="instantiates(notifier_)"];
 144    ModuleA =>> MdModuleNotification [label="subscribe(otherfunc)"];
 145    ModuleA =>> MOD;
 146    MOD =>> ModuleB [label="instantiates(notifier_)"];
 147    ModuleB =>> MdModuleNotification [label="subscribe(func)"];
 148    ModuleB =>> MOD;
 149    runner =>> CallParameter [label="instantiate"];
 150    CallParameter =>> runner ;
 151    runner =>> MOD [label="notify(eventA)"];
 152    MOD =>> MdModuleNotification [label="notify(eventA)"];
 153    MdModuleNotification =>> ModuleA [label="notify(eventA)"];
 154    ModuleA -> ModuleA [label="func(eventA)"];
 155    MdModuleNotification =>> ModuleB [label="notify(eventA)"];
 156    ModuleB -> ModuleB [label="otherfunc(eventA)"];
 157
 158    \endmsc
 159  *
 160  * The template arguments to the members of this struct directly reflect
 161  * the callback function signature. Arguments passed as pointers are always
 162  * meant to be modified, but never meant to be stored (in line with the policy
 163  * everywhere else).
 164  */
 165 struct MdModulesNotifier
 166 {
 167     /*! \brief Pre-processing callback functions.
 168      *
 169      * EnergyCalculationFrequencyErrors* allows modules to check if they match
 170      *                                   their required calculation frequency
 171      *                                   and add their error message if needed
 172      *                                   to the collected error messages
 173      * IndexGroupsAndNames provides modules with atom indices and their names
 174      * KeyValueTreeObjectBuilder enables writing of module internal data to
 175      *                           .tpr files.
 176      */
 177     registerMdModuleNotification<EnergyCalculationFrequencyErrors*, IndexGroupsAndNames, KeyValueTreeObjectBuilder>::type preProcessingNotifications_;
 178
 179     /*! \brief Checkpointing callback functions.
 180      *
 181      * MdModulesCheckpointReadingDataOnMaster provides modules with their
 182      *                                        checkpointed data on the master
 183      *                                        node and checkpoint file version
 184      * MdModulesCheckpointReadingBroadcast provides modules with a communicator
 185      *                                     and the checkpoint file version to
 186      *                                     distribute their data
 187      * MdModulesWriteCheckpointData provides the modules with a key-value-tree
 188      *                              builder to store their checkpoint data and
 189      *                              the checkpoint file version
 190      */
 191     registerMdModuleNotification<MdModulesCheckpointReadingDataOnMaster,
 192                                  MdModulesCheckpointReadingBroadcast,
 193                                  MdModulesWriteCheckpointData>::type checkpointingNotifications_;
 194
 195     /*! \brief Callbacks during simulation setup.
 196      *
 197      * const KeyValueTreeObject& provides modules with the internal data they
 198      *                           wrote to .tpr files
 199      * LocalAtomSetManager* enables modules to add atom indices to local atom sets
 200      *                      to be managed
 201      * MdModulesEnergyOutputToDensityFittingRequestChecker* enables modules to
 202      *                      report if they want to write their energy output
 203      *                      to the density fitting field in the energy files
 204      * SeparatePmeRanksPermitted* enables modules to report if they want
 205      *                      to disable dedicated PME ranks
 206      * const PbcType& provides modules with the periodic boundary condition type
 207      *                that is used during the simulation
 208      * const SimulationTimeStep& provides modules with the simulation time-step
 209      *                           that allows them to interconvert between step
 210      *                           time information
 211      * const t_commrec& provides a communicator to the modules during simulation
 212      *                  setup
 213      */
 214     registerMdModuleNotification<const KeyValueTreeObject&,
 215                                  LocalAtomSetManager*,
 216                                  MdModulesEnergyOutputToDensityFittingRequestChecker*,
 217                                  SeparatePmeRanksPermitted*,
 218                                  const PbcType&,
 219                                  const SimulationTimeStep&,
 220                                  const t_commrec&>::type simulationSetupNotifications_;
 221 };
 222
 223 } // namespace gmx
 224
 225 #endif