src/gromacs/coordinateio/coordinatefile.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
  37  * CoordinateFile takes care of opening files and writing output to them.
  38  *
  39  * \author
  40  * \inpublicapi
  41  * \ingroup module_coordinateio
  42  */
  43 #ifndef GMX_COORDINATEIO_COORDINATEFILE_H
  44 #define GMX_COORDINATEIO_COORDINATEFILE_H
  45
  46 #include <algorithm>
  47 #include <utility>
  48
  49 #include "gromacs/coordinateio/ioutputadapter.h"
  50 #include "gromacs/coordinateio/outputadaptercontainer.h"
  51 #include "gromacs/fileio/filetypes.h"
  52 #include "gromacs/fileio/trxio.h"
  53 #include "gromacs/selection/selection.h"
  54 #include "gromacs/topology/mtop_util.h"
  55 #include "gromacs/topology/topology.h"
  56
  57 namespace gmx
  58 {
  59
  60 class TrajectoryFrameWriter;
  61 struct OutputRequirements;
  62
  63 /*! \brief
  64  * Factory function for TrajectoryFrameWriter.
  65  *
  66  * Used to initialize a new instance of TrajectoryFrameWriter with the user supplied information
  67  * for writing trajectory data to disk. Information needed is the file type, file name
  68  * corresponding to the type, if available topology information and selection information.
  69  *
  70  * If supplied, the modules contained within \p adapters are registered on
  71  * the TrajectoryFrameWriter if possible.
  72  *
  73  * The factory function is responsible for the initial santity checks concerning file types and
  74  * availability of topology information, with the registration of modules being the second part.
  75  *
  76  * \param[in] top                    Pointer to full topology or null.
  77  * \param[in] sel                    Reference to global selection used to construct the object.
  78  * \param[in] filename               Name of new output file, used to deduce file type.
  79  * \param[in] atoms                  Smart Pointer to atoms data or null.
  80  * \param[in] requirements           Container for settings obtained to specify which
  81  *                                   OutputAdapters should be registered.
  82  * \throws    InconsistentInputError When user input and requirements don't match.
  83  */
  84 std::unique_ptr<TrajectoryFrameWriter> createTrajectoryFrameWriter(const gmx_mtop_t  *top,
  85                                                                    const Selection   &sel,
  86                                                                    const std::string &filename,
  87                                                                    AtomsDataPtr       atoms,
  88                                                                    OutputRequirements requirements);
  89
  90 /*!\brief
  91  * Low level method to take care of only file opening and closing.
  92  *
  93  * \inpublicapi
  94  * \ingroup module_coordinateio
  95  *
  96  */
  97 class TrajectoryFileOpener
  98 {
  99     public:
 100         /*! \brief
 101          * Constructor, taking all arguments needed to open valid coordinate files of any type.
 102          *
 103          * \param[in] name Name of the file to create.
 104          * \param[in] filetype Internal filetype to know which kind we are going to have.
 105          * \param[in] sel Reference to selection of atoms to write. Needs to be valid for
 106          *                longer than the lifetime of the object created here.
 107          * \param[in] mtop Topology used to create TNG output. Needs to be valid for longer
 108          *                 than the object created here.
 109          */
 110         TrajectoryFileOpener(const std::string        &name,
 111                              int                       filetype,
 112                              const Selection          &sel,
 113                              const gmx_mtop_t         *mtop) :
 114             outputFileName_(name), outputFile_(nullptr), filetype_(filetype), sel_(sel), mtop_(mtop)
 115         {}
 116
 117         /*! \brief
 118          * Closes new trajectory file after finishing the writing to it.
 119          */
 120         ~TrajectoryFileOpener();
 121
 122         /*! \brief
 123          * Get access to initialized output file object.
 124          *
 125          * Performs lazy initialization if needed.
 126          */
 127         t_trxstatus *outputFile();
 128
 129     private:
 130         //! Name for the new coordinate file.
 131         std::string  outputFileName_;
 132
 133         //! File pointer to the coordinate file being written.
 134         t_trxstatus *outputFile_;
 135
 136         //! Storage of file type for determing what kind of file will be written to disk.
 137         int          filetype_;
 138
 139         /*! \brief
 140          * Selection of atoms to write out.
 141          *
 142          * Currently, CoordinateFile expects that the lifetime of the selection is longer
 143          * than that of itself, and that the selection remains unchanged during this lifetime.
 144          * A better approach will be to pass the selection to it and expect it to
 145          * manage the lifetime instead.
 146          */
 147         const Selection   &sel_;
 148
 149         //! Pointer to topology information if available.
 150         const gmx_mtop_t *mtop_;
 151 };
 152
 153 /*!\brief
 154  * Writes coordinate frames to a sink, e.g. a trajectory file.
 155  *
 156  * Writes all frames passed to the trajectory file handle it
 157  * manages. It can use IOutputAdapter modules to transform the
 158  * frame data before writing. If any transform modules are used,
 159  * makes a deep copy of the frame contents.
 160  *
 161  * \inpublicapi
 162  * \ingroup module_coordinateio
 163  *
 164  */
 165 class TrajectoryFrameWriter
 166 {
 167     public:
 168         friend std::unique_ptr<TrajectoryFrameWriter>
 169         createTrajectoryFrameWriter(const gmx_mtop_t  *top,
 170                                     const Selection   &sel,
 171                                     const std::string &filename,
 172                                     AtomsDataPtr       atoms,
 173                                     OutputRequirements requirements);
 174
 175         /*! \brief
 176          * Writes the input frame, after applying any IOutputAdapters.
 177          *
 178          * \param[in] framenumber Number of frame being currently processed.
 179          * \param[in] input View of the constant t_trxframe object provided by the
 180          *                  method that calls the output manager.
 181          */
 182         void prepareAndWriteFrame(int framenumber, const t_trxframe &input);
 183
 184     private:
 185         /*! \brief
 186          * Creates fully initialized object.
 187          *
 188          * \param[in] name Name of the file to create.
 189          * \param[in] filetype Internal filetype to know which kind we are going to have.
 190          * \param[in] sel Reference to selection of atoms to write. Needs to be valid for
 191          *                longer than the lifetime of the object created here.
 192          * \param[in] mtop Topology used to create TNG output. Needs to be valid for longer
 193          *                 than the object created here.
 194          * \param[in] adapters Container of methods that can modify the information written
 195          *                     to the new file.
 196          */
 197         TrajectoryFrameWriter(const std::string        &name,
 198                               int                       filetype,
 199                               const Selection          &sel,
 200                               const gmx_mtop_t         *mtop,
 201                               OutputAdapterContainer    adapters) :
 202             file_(name, filetype, sel, mtop),
 203             outputAdapters_(std::move(adapters))
 204         {
 205         }
 206
 207         //! Underlying object for open/writing to file.
 208         TrajectoryFileOpener file_;
 209
 210         //! Storage for list of output adapters.
 211         OutputAdapterContainer outputAdapters_;
 212
 213         //! Local storage for modified positions.
 214         std::vector<RVec> localX_;
 215         //! Local storage for modified velocities.
 216         std::vector<RVec> localV_;
 217         //! Local storage for modified forces.
 218         std::vector<RVec> localF_;
 219         //! Local storage for modified indices.
 220         std::vector<int>  localIndex_;
 221 };
 222
 223 //! Smart pointer to manage the TrajectoryFrameWriter object.
 224 using TrajectoryFrameWriterPointer = std::unique_ptr<TrajectoryFrameWriter>;
 225
 226 } // namespace gmx
 227
 228 #endif