2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 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.
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.
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.
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.
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.
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.
37 * \brief Compatibility header for functionality differences in gmxapi releases.
39 * Also handle the transitioning installed headers from GROMACS 2019 moving forward.
41 * \todo Configure for gmxapi 0.0.7, 0.0.8, GROMACS 2019, GROMACS master...
43 * \defgroup gmxapi_compat
44 * \author M. Eric Irrgang <ericirrgang@gmail.com>
45 * \ingroup gmxapi_compat
48 #ifndef GMXAPICOMPAT_H
49 #define GMXAPICOMPAT_H
54 #include "gmxapi/exceptions.h"
55 #include "gmxapi/gmxapi.h"
56 #include "gmxapi/gromacsfwd.h"
59 * \brief Compatibility code for features that may not be in the gmxapi specification yet.
61 * \ingroup gmxapi_compat
63 namespace gmxapicompat
67 * \brief The key name provided for a key-value mapping is invalid.
69 class KeyError
: public gmxapi::BasicException
<KeyError
>
71 using gmxapi::BasicException
<KeyError
>::BasicException
;
75 * \brief The value provided for a key-value mapping is invalid.
77 class ValueError
: public gmxapi::BasicException
<ValueError
>
79 using gmxapi::BasicException
<ValueError
>::BasicException
;
83 * \brief Value provided for a key-value mapping is of an incompatible type.
85 class TypeError
: public gmxapi::BasicException
<TypeError
>
87 using gmxapi::BasicException
<TypeError
>::BasicException
;
91 * \brief Static map of GROMACS MDP user input to normalized "type".
93 * Note that only fields present in the TPR file are named. Additional names
94 * may be accepted as mdp file entries, but we cannot discern which parameter
95 * name was used from inspection of the TPR file and this is an interim solution
96 * that does not need to support a complete MDP file converter.
98 std::map
<std::string
, gmxapi::GmxapiType
> simulationParameterTypeMap();
100 std::map
<std::string
, bool t_inputrec::*> boolParams();
101 std::map
<std::string
, int t_inputrec::*> int32Params();
102 std::map
<std::string
, float t_inputrec::*> float32Params();
103 std::map
<std::string
, double t_inputrec::*> float64Params();
104 std::map
<std::string
, int64_t t_inputrec::*> int64Params();
107 * \brief Static mapping of parameter names to gmxapi types for GROMACS.
109 * \param name MDP entry name.
110 * \return enumeration value for known parameters.
112 * \throws gmxapi_compat::ValueError for parameters with no mapping.
114 gmxapi::GmxapiType
mdParamToType(const std::string
& name
);
117 * \brief Facade for objects that can provide atomic data for a configuration.
119 class StructureSource
;
122 * \brief Facade for objects that can provide molecular topology information for a structure.
124 class TopologySource
;
127 * \brief Proxy to simulation state data.
129 class SimulationState
;
132 * \brief Handle / manager for GROMACS molecular computation input parameters.
134 * Interface should be consistent with MDP file entries, but data maps to TPR
135 * file interface. For type safety and simplicity, we don't have generic operator
136 * accessors. Instead, we have templated accessors that throw exceptions when
139 * When MDP input is entirely stored in a key-value tree, this class can be a
140 * simple adapter or wrapper. Until then, we need a manually maintained mapping
141 * of MDP entries to TPR data.
143 * Alternatively, we could update the infrastructure used by list_tpx to provide
144 * more generic output, but our efforts may be better spent in updating the
145 * infrastructure for the key-value tree input system.
150 * \brief Handle for a TPR data resource.
152 * Can provide StructureSource, TopologySource, GmxMdParams, and SimulationState.
154 * This is the type of object we allow Python clients to hold references to, though
155 * we don't expose any methods to Python. Python clients should acquire access
156 * to TPR file contents with read_tpr().
158 * \todo gmxapi C++ API should provide mechanisms for subscribing to simulation
159 * input data from various sources.
164 * \brief Open a TPR file and retrieve a handle.
166 * \param filename Path of file to read.
167 * \return handle that may share ownership of TPR file resource.
169 std::unique_ptr
<TprReadHandle
> readTprFile(const std::string
& filename
);
172 * \brief Write a new TPR file to the filesystem with the provided contents.
174 * \param filename output file path
175 * \param params simulation parameters
176 * \param structure system structure (atomic configuration)
177 * \param state simulation state
178 * \param topology molecular topology
180 * \throws ValueError for invalid or irreconcilable input.
182 void writeTprFile(const std::string
& filename
,
183 const GmxMdParams
& params
,
184 const StructureSource
& structure
,
185 const SimulationState
& state
,
186 const TopologySource
& topology
);
189 * \brief Get a topology source from the TPR contents collection.
193 * \todo replace with a helper template on T::topologySource() member function existence.
196 std::unique_ptr
<TopologySource
> getTopologySource(const TprReadHandle
& handle
);
199 * \brief Get a source of simulation state from the TPR contents collection.
203 * \todo template on T::simulationState() member function existence.
205 std::unique_ptr
<SimulationState
> getSimulationState(const TprReadHandle
& handle
);
208 * \brief Get a source of atomic structure from the TPR contents collection.
212 std::unique_ptr
<StructureSource
> getStructureSource(const TprReadHandle
& handle
);
215 * \brief Get an initialized parameters structure.
219 std::unique_ptr
<GmxMdParams
> getMdParams(const TprReadHandle
& handle
);
222 * \brief A set of overloaded functions to fetch parameters of the indicated type, if possible.
224 * \param params Handle to a parameters structure from which to extract.
225 * \param name Parameter name
226 * \param (tag) type for dispatch
228 * Could be used for dispatch and/or some sort of templating in the future, but
229 * invoked directly for now.
231 int extractParam(const GmxMdParams
& params
, const std::string
& name
, int /*unused*/);
232 int64_t extractParam(const GmxMdParams
& params
, const std::string
& name
, int64_t /*unused*/);
233 float extractParam(const GmxMdParams
& params
, const std::string
& name
, float /*unused*/);
234 double extractParam(const GmxMdParams
& params
, const std::string
& name
, double /*unused*/);
236 void setParam(GmxMdParams
* params
, const std::string
& name
, double value
);
237 void setParam(GmxMdParams
* params
, const std::string
& name
, int64_t value
);
240 } // end namespace gmxapicompat
242 #endif // GMXAPICOMPAT_H