python_packaging/src/gmxapi/tprfile.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2019, 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 Declare TPR file helpers.
  37  *
  38  * \ingroup module_python
  39  * \author M. Eric Irrgang <ericirrgang@gmail.com>
  40  */
  41
  42 #ifndef GMXPY_TPRFILE_H
  43 #define GMXPY_TPRFILE_H
  44
  45 #include <string>
  46 #include <vector>
  47
  48 #include "compat_exceptions.h"
  49 #include "mdparams.h"
  50
  51 namespace gmxapicompat
  52 {
  53
  54 /*!
  55  * \brief Facade for objects that can provide atomic data for a configuration.
  56  */
  57 class StructureSource;
  58
  59 /*!
  60  * \brief Facade for objects that can provide molecular topology information for a structure.
  61  */
  62 class TopologySource;
  63
  64 /*!
  65  * \brief Proxy to simulation state data.
  66  */
  67 class SimulationState;
  68
  69 /*!
  70  * \brief Manager for TPR file resources.
  71  *
  72  * To avoid copies, this resource-owning object is shared by consumers of its
  73  * resources, even when different resources are consumed.
  74  *
  75  * Multiple read-only handles may be issued if there are no write-handles.
  76  * One write handle may be issued if there are no other open handles.
  77  *
  78  * A const TprFile may only issue read file-handles, allowing handles to be
  79  * issued more quickly by avoiding atomic resource locking.
  80  *
  81  * \note Shared ownership of file manager could be avoided if owned by a Context.
  82  * It is appropriate for a Context to own and mediate access to the manager because
  83  * the Context should provide the filesystem abstraction to more intelligently
  84  * map named file paths to resources. For now, handles and other consumers share ownership
  85  * of the TprContents manager object via shared_ptr.
  86  */
  87 class TprContents;
  88
  89 /*!
  90  * \brief Handle for a TPR data resource.
  91  *
  92  * Can provide StructureSource, TopologySource, GmxMdParams, and SimulationState.
  93  *
  94  * This is the type of object we allow Python clients to hold references to, though
  95  * we don't expose any methods to Python. Python clients should acquire access
  96  * to TPR file contents with read_tpr().
  97  *
  98  * \todo gmxapi C++ API should provide mechanisms for subscribing to simulation
  99  *       input data from various sources.
 100  */
 101 class TprReadHandle
 102 {
 103     public:
 104         explicit TprReadHandle(std::shared_ptr<TprContents> tprFile);
 105         explicit TprReadHandle(TprContents &&tprFile);
 106         ~TprReadHandle();
 107
 108         /*!
 109          * \brief Allow API functions to access data resources.
 110          *
 111          * Used internally. The entire TPR contents are never extracted to the
 112          * client, but API implementation details need to be
 113          * able to access some or all entire contents in later operations.
 114          *
 115          * \return Reference-counted handle to data container.
 116          */
 117         std::shared_ptr<TprContents> get() const;
 118     private:
 119         std::shared_ptr<TprContents> tprContents_;
 120 };
 121
 122 /*!
 123  * \brief Open a TPR file and retrieve a handle.
 124  *
 125  * \param filename Path of file to read.
 126  * \return handle that may share ownership of TPR file resource.
 127  */
 128 TprReadHandle readTprFile(const std::string &filename);
 129
 130 /*!
 131  * \brief Write a new TPR file to the filesystem with the provided contents.
 132  *
 133  * \param filename output file path
 134  * \param params simulation parameters
 135  * \param structure system structure (atomic configuration)
 136  * \param state simulation state
 137  * \param topology molecular topology
 138  */
 139 void writeTprFile(const std::string     &filename,
 140                   const GmxMdParams     &params,
 141                   const StructureSource &structure,
 142                   const SimulationState &state,
 143                   const TopologySource  &topology);
 144
 145 /*!
 146  * \brief Helper function for early implementation.
 147  *
 148  * Allows extraction of TPR file information from special params objects.
 149  *
 150  * \todo This is a very temporary shim! Find a better way to construct simulation input.
 151  */
 152 TprReadHandle getSourceFileHandle(const GmxMdParams &params);
 153
 154 /*!
 155  * \brief Get a topology source from the TPR contents collection.
 156  * \param handle
 157  * \return
 158  *
 159  * \todo replace with a helper template on T::topologySource() member function existence.
 160  */
 161
 162 TopologySource getTopologySource(const TprReadHandle &handle);
 163
 164 /*!
 165  * \brief Get a source of simulation state from the TPR contents collection.
 166  * \param handle
 167  * \return
 168  *
 169  * \todo template on T::simulationState() member function existence.
 170  */
 171 SimulationState getSimulationState(const TprReadHandle &handle);
 172
 173 /*!
 174  * \brief Get a source of atomic structure from the TPR contents collection.
 175  * \param handle
 176  * \return
 177  */
 178 StructureSource getStructureSource(const TprReadHandle &handle);
 179
 180 /*!
 181  * \brief Get an initialized parameters structure.
 182  * \param handle
 183  * \return
 184  */
 185 GmxMdParams getMdParams(const TprReadHandle &handle);
 186
 187 std::vector<std::string> keys(const GmxMdParams &params);
 188
 189 class StructureSource
 190 {
 191     public:
 192         std::shared_ptr<TprContents> tprFile_;
 193 };
 194
 195 class TopologySource
 196 {
 197     public:
 198         std::shared_ptr<TprContents> tprFile_;
 199 };
 200
 201 class SimulationState
 202 {
 203     public:
 204         std::shared_ptr<TprContents> tprFile_;
 205 };
 206
 207 } // end namespace gmxapicompat
 208
 209 namespace gmxpy
 210 {
 211
 212 /*!
 213  * \brief Copy TPR file.
 214  *
 215  * \param input TPR source to copy from
 216  * \param outFile output TPR file name
 217  * \return true if successful. else false.
 218  */
 219 bool copy_tprfile(const gmxapicompat::TprReadHandle &input, std::string outFile);
 220
 221 /*!
 222  * \brief Copy and possibly update TPR file by name.
 223  *
 224  * \param inFile Input file name
 225  * \param outFile Output file name
 226  * \param endTime Replace `nsteps` in infile with `endTime/dt`
 227  * \return true if successful, else false
 228  */
 229 bool rewrite_tprfile(std::string inFile, std::string outFile, double endTime);
 230
 231 }      // end namespace gmxpy
 232
 233 #endif //GMXPY_TPRFILE_H