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