api/include/gmxapi/compat/tpr.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
  36 /*! \file
  37  * \brief Tools for converting simulation input data to and from TPR files.
  38  *
  39  * \author M. Eric Irrgang <ericirrgang@gmail.com>
  40  * \ingroup gmxapi_compat
  41  */
  42
  43 #ifndef GMXAPICOMPAT_TPR_H
  44 #define GMXAPICOMPAT_TPR_H
  45
  46 #include <memory>
  47 #include <vector>
  48
  49 #include "gmxapi/gmxapicompat.h"
  50 #include "gmxapi/compat/mdparams.h"
  51
  52 namespace gmxapicompat
  53 {
  54
  55 /*!
  56  * \brief Manager for TPR file resources.
  57  *
  58  * To avoid copies, this resource-owning object is shared by consumers of its
  59  * resources, even when different resources are consumed.
  60  *
  61  * Multiple read-only handles may be issued if there are no write-handles.
  62  * One write handle may be issued if there are no other open handles.
  63  *
  64  * A const TprFile may only issue read file-handles, allowing handles to be
  65  * issued more quickly by avoiding atomic resource locking.
  66  *
  67  * \note Shared ownership of file manager could be avoided if owned by a Context.
  68  * It is appropriate for a Context to own and mediate access to the manager because
  69  * the Context should provide the filesystem abstraction to more intelligently
  70  * map named file paths to resources. For now, handles and other consumers share ownership
  71  * of the TprContents manager object via shared_ptr.
  72  */
  73 class TprContents;
  74
  75 class TprReadHandle
  76 {
  77 public:
  78     explicit TprReadHandle(std::shared_ptr<TprContents> tprFile);
  79     explicit TprReadHandle(TprContents&& tprFile);
  80     TprReadHandle(const TprReadHandle&) = default;
  81     TprReadHandle& operator=(const TprReadHandle&) = default;
  82     TprReadHandle(TprReadHandle&&) noexcept        = default;
  83     TprReadHandle& operator=(TprReadHandle&&) noexcept = default;
  84     ~TprReadHandle();
  85
  86     /*!
  87      * \brief Allow API functions to access data resources.
  88      *
  89      * Used internally. The entire TPR contents are never extracted to the
  90      * client, but API implementation details need to be
  91      * able to access some or all entire contents in later operations.
  92      *
  93      * \return Reference-counted handle to data container.
  94      */
  95     std::shared_ptr<TprContents> get() const;
  96
  97 private:
  98     std::shared_ptr<TprContents> tprContents_;
  99 };
 100
 101 /*!
 102  * \brief Helper function for early implementation.
 103  *
 104  * Allows extraction of TPR file information from special params objects.
 105  *
 106  * \todo This is a very temporary shim! Find a better way to construct simulation input.
 107  */
 108 TprReadHandle getSourceFileHandle(const GmxMdParams& params);
 109
 110 class StructureSource
 111 {
 112 public:
 113     std::shared_ptr<TprContents> tprFile_;
 114 };
 115
 116 class TopologySource
 117 {
 118 public:
 119     std::shared_ptr<TprContents> tprFile_;
 120 };
 121
 122 class SimulationState
 123 {
 124 public:
 125     std::shared_ptr<TprContents> tprFile_;
 126 };
 127
 128 /*!
 129  * \brief Copy TPR file.
 130  *
 131  * \param input TPR source to copy from
 132  * \param outFile output TPR file name
 133  * \return true if successful. else false.
 134  */
 135 bool copy_tprfile(const gmxapicompat::TprReadHandle& input, const std::string& outFile);
 136
 137 /*!
 138  * \brief Copy and possibly update TPR file by name.
 139  *
 140  * \param inFile Input file name
 141  * \param outFile Output file name
 142  * \param endTime Replace `nsteps` in infile with `endTime/dt`
 143  * \return true if successful, else false
 144  */
 145 bool rewrite_tprfile(const std::string& inFile, const std::string& outFile, double endTime);
 146
 147 } // end namespace gmxapicompat
 148
 149 #endif // GMXAPICOMPAT_TPR_H