2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 2016,2018, 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 Interfaces of related classes for tests that want to
38 * inspect energies produced by mdrun.
40 * The responsibilities for reading and sharing information from .edr
41 * files in an exception-safe manner are shared between two
42 * classes. Intended usage is to call openEnergyFileToReadFields() to
43 * return an EnergyFrameReader that knows it expects to read the named
44 * .edr fields from each frame. Successive calls to its
45 * EnergyFrameReader::readNextFrame() and EnergyFrameReader::frame()
46 * methods will return EnergyFrame objects that contain the values for
47 * the .edr fields registered earlier.
49 * \author Mark Abraham <mark.j.abraham@gmail.com>
50 * \ingroup module_mdrun_integration_tests
52 #ifndef GMX_PROGRAMS_MDRUN_TESTS_ENERGYREADER_H
53 #define GMX_PROGRAMS_MDRUN_TESTS_ENERGYREADER_H
59 #include <unordered_map>
62 #include "gromacs/fileio/enxio.h"
63 #include "gromacs/utility/unique_cptr.h"
65 #include "testutils/testasserts.h"
75 /*! \brief Convenience function to get std::string keys from a map.
77 * This function can be used to provide an input for
78 * openEnergyFileToReadFields().
80 * \todo This returns a copy of the keys, which is convenient, but
81 * inefficient. Alternatively, this could return a view of the keys
82 * from a range rather than a container, but there's no implementation
83 * of that in C++11 at the moment. */
84 template <typename Map>
85 std::vector<std::string> getKeys(const Map &m)
87 std::vector<std::string> keys;
88 keys.reserve(m.size());
89 for (const auto &it : m)
91 keys.push_back(it.first);
96 //! Forward declaration
97 class EnergyFrameReader;
98 //! Convenience smart pointer typedef
99 typedef std::unique_ptr<EnergyFrameReader> EnergyFrameReaderPtr;
101 /*! \brief Open the file and return an object that can read the required fields from frames of an .edr file.
103 * \param[in] filename Name of the energy file to use
104 * \param[in] requiredEnergyFieldNames Names of the energy fields that the caller requires to
105 * be present for an .edr file frame to be considered valid
106 * \throws FileIOError If the .edr file cannot be opened
107 * \throws APIError If any required energy field is not present in the file
108 * \throws std::bad_alloc When out of memory
110 * This function is intended to have the main responsibility for
111 * making EnergyFrameReader objects. */
112 EnergyFrameReaderPtr openEnergyFileToReadFields(const std::string &filename,
113 const std::vector<std::string> &requiredEnergyFieldNames);
115 //! Convenience smart pointer typedef
116 typedef unique_cptr<ener_file, done_ener_file> ener_file_ptr;
117 //! Helper function to free resources (NB free_enxframe only frees the contents, not the pointer itself)
118 void done_enxframe(t_enxframe *fr);
119 //! Convenience smart pointer typedef
120 typedef unique_cptr<t_enxframe, done_enxframe> enxframe_ptr;
123 * \brief Manages returning an EnergyFrame containing required energy
124 * field values read from successive frames of an .edr file. */
125 class EnergyFrameReader
128 /*! \brief Attempt to read the next frame from the energy file.
130 * \return Whether a frame was available to read.
132 * If true is returned, then frame() should be called
133 * to get access to the data. If false is returned, then no
134 * further data exists and no further call to
135 * readNextFrame() or frame() should occur.
137 * \throws APIError if an earlier probe has not been properly handled
138 * (by calling frame(), or stopping trying to read
140 bool readNextFrame();
141 /*! \brief Make an EnergyFrame from the contents of the next frame in the energy file.
143 * If the next frame has not been probed for, then probe for
144 * it. If no next frame exists, then throw APIError, because
145 * user code should have called readNextFrame() itself if this
146 * is possible. (This permits user code to avoid making calls
147 * to readNextFrame() in a case where it already knows that
150 * \throws APIError if no next frame exists.
151 * \throws std::bad_alloc when out of memory. */
153 /*! \brief Constructor
155 * \param[in] indicesOfEnergyFields Looks up energy fields by name to get the index into a t_enxframe structure read by the legacy API.
156 * \param[in] energyFile Open energy file object to manage, and from which to read frames */
157 explicit EnergyFrameReader(const std::map<std::string, int> &indicesOfEnergyFields,
158 ener_file *energyFile);
160 //! Convert energy field name to its index within a t_enxframe from this file.
161 std::map<std::string, int> indicesOfEnergyFields_;
162 //! Owning handle of an open energy file ready to read frames.
163 const ener_file_ptr energyFileGuard_;
164 //! Owning handle of contents of .edr file frame after reading.
165 const enxframe_ptr enxframeGuard_;
166 //! Whether the API has been used properly (ie. probe before reading).
167 bool haveProbedForNextFrame_;
168 //! Whether there has been a probe that found a next frame.
169 bool nextFrameExists_;
171 // Multiple owners of these resources isn't very sensible, so prevent it
172 GMX_DISALLOW_COPY_AND_ASSIGN(EnergyFrameReader);