2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 2013,2014,2015,2016,2017 by the GROMACS development team.
5 * Copyright (c) 2018,2019,2020, by the GROMACS development team, led by
6 * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
7 * and including many others, as listed in the AUTHORS file in the
8 * top-level source directory and at http://www.gromacs.org.
10 * GROMACS is free software; you can redistribute it and/or
11 * modify it under the terms of the GNU Lesser General Public License
12 * as published by the Free Software Foundation; either version 2.1
13 * of the License, or (at your option) any later version.
15 * GROMACS is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 * Lesser General Public License for more details.
20 * You should have received a copy of the GNU Lesser General Public
21 * License along with GROMACS; if not, see
22 * http://www.gnu.org/licenses, or write to the Free Software Foundation,
23 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
25 * If you want to redistribute modifications to GROMACS, please
26 * consider that scientific software is very special. Version
27 * control is crucial - bugs must be traceable. We will be happy to
28 * consider code for inclusion in the official distribution, but
29 * derived work must not be called official GROMACS. Details are found
30 * in the README & COPYING files - if they are missing, get the
31 * official version at http://www.gromacs.org.
33 * To help us fund GROMACS development, we humbly ask that you cite
34 * the research papers on the package. Check out http://www.gromacs.org.
37 #ifndef GMX_FILEIO_TNGIO_H
38 #define GMX_FILEIO_TNGIO_H
42 #include "gromacs/math/vectypes.h"
43 #include "gromacs/utility/arrayref.h"
44 #include "gromacs/utility/basedefinitions.h"
45 #include "gromacs/utility/real.h"
49 struct gmx_tng_trajectory;
50 typedef struct gmx_tng_trajectory* gmx_tng_trajectory_t;
53 /*! \brief Open a TNG trajectory file
55 * \param filename Name of file to open
56 * \param mode Can be set to 'r', 'w' or 'a' for reading, writing or appending respectively.
57 * \param tng_data_p Pointer to an allocated gmx_tng_trajectory_t into which a handle to a TNG trajectory will be stored.
59 * Handles all I/O errors internally via fatal error
61 void gmx_tng_open(const char* filename, char mode, gmx_tng_trajectory_t* tng_data_p);
63 /*! \brief Finish writing a TNG trajectory file */
64 void gmx_tng_close(gmx_tng_trajectory_t* tng);
66 /*!\brief Add molecular topology information to TNG output (if
69 * \param tng Valid handle to a TNG trajectory
70 * \param mtop Pointer to a topology (can be NULL)
72 void gmx_tng_add_mtop(gmx_tng_trajectory_t tng, const gmx_mtop_t* mtop);
74 /*! \brief Do all TNG preparation for full-precision whole-system
75 * trajectory writing during MD simulations.
77 * \param tng Valid handle to a TNG trajectory
78 * \param mtop Global topology
79 * \param ir Input settings (for writing frequencies)
81 void gmx_tng_prepare_md_writing(gmx_tng_trajectory_t tng, const gmx_mtop_t* mtop, const t_inputrec* ir);
83 /*! \brief Set the default compression precision for TNG writing
85 * \param tng Valid handle to a TNG trajectory
86 * \param prec GROMACS-style precision setting (i.e. 1000 for 3 digits of precision) */
87 void gmx_tng_set_compression_precision(gmx_tng_trajectory_t tng, real prec);
89 /*! \brief Do all TNG preparation for low-precision selection-based
90 * trajectory writing during MD simulations.
92 * \param tng Valid handle to a TNG trajectory
93 * \param mtop Global topology
94 * \param ir Input settings (for writing frequencies)
96 void gmx_tng_prepare_low_prec_writing(gmx_tng_trajectory_t tng, const gmx_mtop_t* mtop, const t_inputrec* ir);
98 /*! \brief Write a frame to a TNG file
100 * \param tng Valid handle to a TNG trajectory
101 * \param bUseLossyCompression Whether to use lossy compression
102 * \param step MD step number
103 * \param elapsedPicoSeconds Elapsed MD time
104 * \param lambda Free-energy lambda value
105 * \param box Simulation box
106 * \param nAtoms Number of atoms (i.e. vector lengths)
107 * \param x Vector of position coordinates
108 * \param v Vector of elocities
109 * \param f Vector of forces
111 * The pointers tng, x, v, f may be NULL, which triggers not writing
112 * (that component). box can only be NULL if x is also NULL. */
113 void gmx_fwrite_tng(gmx_tng_trajectory_t tng,
114 gmx_bool bUseLossyCompression,
116 real elapsedPicoSeconds,
124 /*! \brief Write the current frame set to disk. Perform compression
127 * \param tng Valid handle to a TNG trajectory
129 void fflush_tng(gmx_tng_trajectory_t tng);
131 /*! \brief Get the time (in picoseconds) of the final frame in the
134 * \param tng Valid handle to a TNG trajectory
136 float gmx_tng_get_time_of_final_frame(gmx_tng_trajectory_t tng);
138 /*! \brief Prepare to write TNG output from trajectory conversion tools */
139 void gmx_prepare_tng_writing(const char* filename,
141 gmx_tng_trajectory_t* in,
142 gmx_tng_trajectory_t* out,
144 const struct gmx_mtop_t* mtop,
145 gmx::ArrayRef<const int> index,
146 const char* indexGroupName);
148 /*! \brief Write a trxframe to a TNG file
150 * \param output Trajectory to write to
151 * \param frame Frame data to write
152 * \param natoms Number of atoms to actually write
154 * The natoms field in frame is the number of atoms in the system. The
155 * parameter natoms supports writing an index-group subset of the
158 void gmx_write_tng_from_trxframe(gmx_tng_trajectory_t output, const t_trxframe* frame, int natoms);
160 /*! \brief Creates a molecule containing only the indexed atoms and sets
161 * the number of all other molecules to 0. Works similar to a
162 * selection group. */
163 void gmx_tng_setup_atom_subgroup(gmx_tng_trajectory_t tng, gmx::ArrayRef<const int> ind, const char* name);
165 /*! \brief Read the first/next TNG frame. */
166 gmx_bool gmx_read_next_tng_frame(gmx_tng_trajectory_t input,
167 struct t_trxframe* fr,
168 int64_t* requestedIds,
169 int numRequestedIds);
171 /*! \brief Print the molecule system to stream */
172 void gmx_print_tng_molecule_system(gmx_tng_trajectory_t input, FILE* stream);
174 /*! \brief Get a list of block IDs present in the next frame with data. */
175 gmx_bool gmx_get_tng_data_block_types_of_next_frame(gmx_tng_trajectory_t input,
178 int64_t* requestedIds,
183 /*! \brief Get data of the next frame with data from the data block
184 * with the specified block ID. */
185 gmx_bool gmx_get_tng_data_next_frame_of_block_type(gmx_tng_trajectory_t input,
188 int64_t* frameNumber,
190 int64_t* nValuesPerFrame,
197 /*! \brief Get the output interval of box size.
199 * \return The box output interval, or -1 when TNG support is not available. */
200 int gmx_tng_get_box_output_interval(gmx_tng_trajectory_t gmx_tng);
202 /*! \brief Get the output interval of lambda.
204 * \return The box output interval, or -1 when TNG support is not available. */
205 int gmx_tng_get_lambda_output_interval(gmx_tng_trajectory_t gmx_tng);
207 #endif /* GMX_FILEIO_TNGIO_H */