Line data    Source code

       1           1 : // Distributed under the MIT License.
       2             : // See LICENSE.txt for details.
       3             : 
       4             : /// \file
       5             : /// Defines class h5::Dat
       6             : 
       7             : #pragma once
       8             : 
       9             : #include <array>
      10             : #include <cstddef>
      11             : #include <cstdint>
      12             : #include <hdf5.h>
      13             : #include <string>
      14             : #include <vector>
      15             : 
      16             : #include "IO/H5/Object.hpp"
      17             : #include "IO/H5/OpenGroup.hpp"
      18             : 
      19             : /// \cond
      20             : class Matrix;
      21             : /// \endcond
      22             : 
      23             : namespace h5 {
      24             : /*!
      25             :  * \ingroup HDF5Group
      26             :  * \brief Represents a multicolumn dat file inside an HDF5 file
      27             :  *
      28             :  * A Dat object represents a dat file inside an H5File. A dat file is a
      29             :  * multicolumn text file with a header describing what each column represents.
      30             :  * Typically dat files are space or tab delimited, and often represent time
      31             :  * series data. One common use for them is writing out error norms over the
      32             :  * computational domain as a function of time. Inside the H5File they are stored
      33             :  * as a string header, and a matrix of doubles holding the data. One problem
      34             :  * encountered with dat files is that they quickly increase the file count
      35             :  * causing users to run into number of file limitations on HPC systems. Since
      36             :  * multiple Dat objects can be stored inside a single H5File the problem of many
      37             :  * different dat files being stored as individual files is solved.
      38             :  *
      39             :  * \note This class does not do any caching of data so all data is written as
      40             :  * soon as append() is called.
      41             :  */
      42           1 : class Dat : public h5::Object {
      43             :  public:
      44             :   /// \cond HIDDEN_SYMBOLS
      45             :   static std::string extension() { return ".dat"; }
      46             : 
      47             :   Dat(bool exists, detail::OpenGroup&& group, hid_t location,
      48             :       const std::string& name, std::vector<std::string> legend = {},
      49             :       uint32_t version = 1);
      50             : 
      51             :   Dat(const Dat& /*rhs*/) = delete;
      52             :   Dat& operator=(const Dat& /*rhs*/) = delete;
      53             :   Dat(Dat&& /*rhs*/) = delete;             // NOLINT
      54             :   Dat& operator=(Dat&& /*rhs*/) = delete;  // NOLINT
      55             : 
      56             :   ~Dat() override;
      57             :   /// \endcond HIDDEN_SYMBOLS
      58             : 
      59             :   /*!
      60             :    * \requires `data.size()` is the same as the number of columns in the file
      61             :    * \effects appends `data` to the Dat file
      62             :    */
      63           1 :   void append(const std::vector<double>& data);
      64             : 
      65             :   /*!
      66             :    * \requires `data[0].size()` is the same as the number of columns in the file
      67             :    * \effects appends `data` to the Dat file
      68             :    */
      69           1 :   void append(const std::vector<std::vector<double>>& data);
      70             : 
      71             :   /*!
      72             :    * \requires `data.columns()` is the same as the number of columns in the file
      73             :    * \effects appends `data` to the Dat file
      74             :    */
      75           1 :   void append(const Matrix& data);
      76             : 
      77             :   /*!
      78             :    * \returns the legend of the Dat file
      79             :    */
      80           1 :   const std::vector<std::string>& get_legend() const { return legend_; }
      81             : 
      82             :   /*!
      83             :    * \returns all data stored in the Dat file
      84             :    *
      85             :    * \example
      86             :    * \snippet Test_Dat.cpp h5dat_get_data
      87             :    */
      88           1 :   Matrix get_data() const;
      89             : 
      90             :   /*!
      91             :    * \brief Get only some columns over a range of rows
      92             :    * \requires all members of `these_columns` have a value less than the number
      93             :    * of columns, `first_row < last_row` and `last_row` is less than or equal to
      94             :    * the number of rows
      95             :    * \returns a subset of the data from the Dat file
      96             :    *
      97             :    * \example
      98             :    * \snippet Test_Dat.cpp h5dat_get_subset
      99             :    */
     100           1 :   Matrix get_data_subset(const std::vector<size_t>& these_columns,
     101             :                          size_t first_row = 0, size_t num_rows = 1) const;
     102             : 
     103             :   /*!
     104             :    * \returns the number of rows (first index) and columns (second index)
     105             :    */
     106           1 :   const std::array<hsize_t, 2>& get_dimensions() const { return size_; }
     107             : 
     108             :   /*!
     109             :    * \returns the header of the Dat file
     110             :    */
     111           1 :   const std::string& get_header() const { return header_; }
     112             : 
     113             :   /*!
     114             :    * \returns the user-specified version number of the Dat file
     115             :    *
     116             :    * \note h5::Version returns a uint32_t, so we return one here too for the
     117             :    * version
     118             :    */
     119           1 :   uint32_t get_version() const { return version_; }
     120             : 
     121           1 :   const std::string& subfile_path() const override { return path_; }
     122             : 
     123             :  private:
     124           0 :   void append_impl(hsize_t number_of_rows, const std::vector<double>& data);
     125             : 
     126             :   /// \cond HIDDEN_SYMBOLS
     127             :   detail::OpenGroup group_;
     128             :   std::string name_;
     129             :   std::string path_;
     130             :   uint32_t version_;
     131             :   std::vector<std::string> legend_;
     132             :   std::array<hsize_t, 2> size_;
     133             :   std::string header_;
     134             :   hid_t dataset_id_{-1};
     135             :   /// \endcond HIDDEN_SYMBOLS
     136             : };
     137             : }  // namespace h5