api/gmxapi/include/gmxapi/md.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2018,2019,2020, 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 #ifndef GMXAPI_MD_H
  36 #define GMXAPI_MD_H
  37 /*! \file
  38  * \brief Declare base classes and API for MD simulation engines.
  39  *
  40  * This header allows interaction with gmxapi for basic MD simulation functionality in client code
  41  * without additional dependencies.
  42  *
  43  * Helper functions, standard concrete classes, and implementation interfaces are in gmxapi/md/
  44  * \ingroup gmxapi_md
  45  */
  46 /*! \dir md
  47  * \brief Additional declarations for API implementation and extension.
  48  *
  49  * This directory contains headers that require gromacsfwd.h and that declare
  50  * objects that have stronger dependencies on GROMACS to fully define or extend.
  51  * \ingroup gmxapi_md
  52  */
  53
  54 /*! \defgroup gmxapi_md Molecular Dynamics
  55  * \brief API access to Molecular Mechanics and Molecular Dynamics calculation in GROMACS
  56  *
  57  * At a minimum, the client code must specify the input source for a MD simulation. Helper functions
  58  * allow setting up inputs from a standard GROMACS run input `.tpr` file. A System object serves as
  59  * a container for a molecular system and associated computational work.
  60  *
  61  * \ingroup gmxapi
  62  */
  63 #include <memory>
  64 #include <string>
  65 #include <vector>
  66
  67 namespace gmxapi
  68 {
  69
  70 class MDModule;
  71
  72 /*! \addtogroup gmxapi_md
  73
  74  # Extending MD with custom code.
  75
  76    Classes deriving from MDModule can interact with GROMACS at a low level to
  77    extend the native GROMACS functionality. It is an evolving API that will
  78    allow increased flexibility with further development. Near term functionality
  79    includes the ability to attach custom code apply restraint forces during
  80    simulation.
  81
  82    Below, we show code that extends the GROMACS library, code that interfaces with this
  83    API, and client code that calls GROMACS with the custom code.
  84    Sample MD plugin code is available at https://github.com/kassonlab/sample_restraint
  85
  86    \todo Move this to an example source code file that we can compile and test.
  87
  88  ## Example
  89
  90    In client code, extend the GROMACS library by implementing a new restraint
  91    potential (see library documentation).
  92
  93    The gmxapi protocol to register a gmxapi::MDModule with a gmxapi::Session
  94    by passing an gmx::IRestraintPotential to a gmx::MdRunner is described in the
  95    gmxapi::Session docs. To exercise it, we need to call gmxapi::Session::setRestraint(),
  96    passing a std::shared_ptr<gmxapi::MDModule> argument.
  97
  98         class NullRestraint : public gmx::IRestraintPotential
  99         {
 100             public:
 101                 gmx::PotentialPointData evaluate(gmx::Vector r1,
 102                                                  gmx::Vector r2,
 103                                                  double t) override
 104                 {
 105                     return {};
 106                 }
 107         };
 108
 109    Use gmxapi::MDModule to define an API object class that we can pass around.
 110
 111         class SimpleApiModule : public gmxapi::MDModule
 112         {
 113             public:
 114                 const char *name() override
 115                 {
 116                     return "NullApiModule";
 117                 }
 118
 119                 // Implement the MDModule protocol.
 120                 std::shared_ptr<gmx::IRestraintPotential> getRestraint() override
 121                 {
 122                     auto restraint = std::make_shared<NullRestraint>();
 123                     return restraint;
 124                 }
 125         };
 126
 127    C++ client code to run an MD simulation with the custom restraint.
 128
 129         bool mysim() {
 130                 auto system = gmxapi::fromTprFile(filename);
 131                 std::shared_ptr<gmxapi::Context> context = gmxapi::defaultContext();
 132                 auto runner = system->runner();
 133
 134                 auto session = runner->initialize(context);
 135
 136                 auto module = std::make_shared<SimpleApiModule>();
 137                 session->setRestraint(module);
 138
 139                 gmxapi::Status status;
 140                 status = session->run();
 141                 return status.success();
 142         };
 143
 144  */
 145
 146 /*!
 147  * \brief Container for Molecular Dynamics simulation setup.
 148  *
 149  * Client code provides the specification for MD work through an object of this type and registers
 150  * the object in the computing context when an execution session is launched. The contents of the
 151  * MDWorkSpec are used to pass appropriate parameters to the MD runner.
 152  *
 153  * \ingroup gmxapi_md
 154  */
 155 class MDWorkSpec
 156 {
 157 public:
 158     MDWorkSpec();
 159     ~MDWorkSpec();
 160
 161     /*!
 162      * \brief Grant shared ownership of a modular MD computation object
 163      *
 164      * \param module instance that can produce a IRestraintPotential at runtime.
 165      */
 166     void addModule(std::shared_ptr<gmxapi::MDModule> module);
 167
 168     /*!
 169      * \brief Get a handle to the stored list of modules
 170      *
 171      * Future versions of MDWorkSpec will not directly hold and grant access to module instances.
 172      * \return reference that is only valid for the life of this object.
 173      */
 174     std::vector<std::shared_ptr<gmxapi::MDModule>>& getModules();
 175
 176 private:
 177     //! \cond internal
 178     //! \brief Private implementation class
 179     class Impl;
 180     //! \brief Opaque pointer to implementation object.
 181     std::unique_ptr<Impl> impl_;
 182     //! \endcond
 183 };
 184
 185 } // end namespace gmxapi
 186
 187 #endif // header guard