src/gromacs/mdrun/simulationinput.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 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 /*! \file
  36  * \brief Public interface for SimulationInput facilities.
  37  *
  38  * \author M. Eric Irrgang <ericirrgang@gmail.com>
  39  * \ingroup module_mdrun
  40  */
  41
  42 #ifndef GMX_MDRUN_SIMULATIONINPUT_H
  43 #define GMX_MDRUN_SIMULATIONINPUT_H
  44
  45 #include <memory>
  46
  47 namespace gmx
  48 {
  49
  50 // Forward declarations for types from other modules that are opaque to the public API.
  51 class LegacyMdrunOptions;
  52
  53 /*!
  54  * \brief Prescription for molecular simulation.
  55  *
  56  * Represents the complete and unique information needed to generate a simulation
  57  * trajectory segment. SimulationInput objects are opaque to the public API.
  58  * Clients can acquire SimulationInput objects through makeSimulationInput().
  59  *
  60  * See also https://gitlab.com/gromacs/gromacs/-/issues/3379 for design and development road map.
  61  */
  62 class SimulationInput;
  63
  64 /*!
  65  * \brief Owning handle to a SimulationInput object.
  66  *
  67  * SimulationInput has no public API. Acquire a SimulationInputHolder with makeSimulationInput().
  68  * See https://gitlab.com/gromacs/gromacs/-/issues/3374
  69  */
  70 class SimulationInputHolder
  71 {
  72 public:
  73     SimulationInputHolder();
  74     ~SimulationInputHolder();
  75
  76     SimulationInputHolder(SimulationInputHolder&&) noexcept = default;
  77     SimulationInputHolder& operator=(SimulationInputHolder&&) noexcept = default;
  78
  79     std::unique_ptr<SimulationInput> object_;
  80 };
  81
  82 namespace detail
  83 {
  84
  85 /*! \brief Get a SimulationInput.
  86  *
  87  * \internal
  88  * Design notes: SimulationInput creation will warrant a builder protocol, and
  89  * this helper can evolve into a director to apply the contents of LegacyMdrunOptions,
  90  * while such an operation is still relevant.
  91  *
  92  * Example:
  93  *     // After preparing a LegacyMdrunOptions and calling handleRestart()...
  94  *     SimulationInputBuilder builder;
  95  *     auto simulationInputHandle = makeSimulationInput(options, &builder);
  96  *
  97  *     // In addition to MdrunnerBuilder::addFiles(),
  98  *     mdrunnerBuilder.addInput(simulationInputHandle.get());
  99  *
 100  */
 101 SimulationInputHolder makeSimulationInput(const char* tprFilename, const char* cpiFilename);
 102
 103 } // end namespace detail
 104
 105 } // end namespace gmx
 106
 107 #endif // GMX_MDRUN_SIMULATIONINPUT_H