Dat.hpp
Go to the documentation of this file.
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 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*/) noexcept = delete; // NOLINT
54  Dat& operator=(Dat&& /*rhs*/) noexcept = 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  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  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  void append(const Matrix& data);
76 
77  /*!
78  * \returns the legend of the Dat file
79  */
80  const std::vector<std::string>& get_legend() const noexcept {
81  return legend_;
82  }
83 
84  /*!
85  * \returns all data stored in the Dat file
86  *
87  * \example
88  * \snippet Test_H5.cpp h5dat_get_data
89  */
90  Matrix get_data() const;
91 
92  /*!
93  * \brief Get only some columns over a range of rows
94  * \requires all members of `these_columns` have a value less than the number
95  * of columns, `first_row < last_row` and `last_row` is less than or equal to
96  * the number of rows
97  * \returns a subset of the data from the Dat file
98  *
99  * \example
100  * \snippet Test_H5.cpp h5dat_get_subset
101  */
102  Matrix get_data_subset(const std::vector<size_t>& these_columns,
103  size_t first_row = 0, size_t num_rows = 1) const;
104 
105  /*!
106  * \returns the number of rows (first index) and columns (second index)
107  */
108  const std::array<hsize_t, 2>& get_dimensions() const noexcept {
109  return size_;
110  }
111 
112  /*!
113  * \returns the header of the Dat file
114  */
115  const std::string& get_header() const noexcept { return header_; }
116 
117  /*!
118  * \returns the user-specified version number of the Dat file
119  *
120  * \note h5::Version returns a uint32_t, so we return one here too for the
121  * version
122  */
123  uint32_t get_version() const noexcept { return version_; }
124 
125  private:
126  void append_impl(hsize_t number_of_rows, const std::vector<double>& data);
127 
128  /// \cond HIDDEN_SYMBOLS
129  detail::OpenGroup group_;
130  std::string name_;
131  uint32_t version_;
132  std::vector<std::string> legend_;
134  std::string header_;
135  hid_t dataset_id_{-1};
136  /// \endcond HIDDEN_SYMBOLS
137 };
138 } // namespace h5
Defines class OpenGroup for opening groups in HDF5.
Contains functions and classes for manipulating HDF5 files.
Definition: AccessType.cpp:10
const std::vector< std::string > & get_legend() const noexcept
Definition: Dat.hpp:80
Defines class h5::Object abstract base class.
uint32_t get_version() const noexcept
Definition: Dat.hpp:123
Represents a multicolumn dat file inside an HDF5 file.
Definition: Dat.hpp:42
HIDDEN_SYMBOLS void append(const std::vector< double > &data)
Definition: Dat.cpp:144
Abstract base class representing an object in an HDF5 file.
Definition: Object.hpp:14
const std::array< hsize_t, 2 > & get_dimensions() const noexcept
Definition: Dat.hpp:108
const std::string & get_header() const noexcept
Definition: Dat.hpp:115
Matrix get_data() const
Definition: Dat.cpp:199
A dynamically sized matrix of doubles with column-major storage.
Definition: Matrix.hpp:19
Matrix get_data_subset(const std::vector< size_t > &these_columns, size_t first_row=0, size_t num_rows=1) const
Get only some columns over a range of rows.
Definition: Dat.cpp:227