Helpers.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 functions for h5 manipulations
6 
7 #pragma once
8 
9 #include <array>
10 #include <cstddef>
11 #include <hdf5.h>
12 #include <string>
13 #include <vector>
14 
15 #include "DataStructures/Index.hpp"
16 
17 /// \cond
18 class DataVector;
19 /// \endcond
20 
21 namespace h5 {
22 /*!
23  * \ingroup HDF5Group
24  * \brief Write a std::vector named `name` to the group `group_id`
25  */
26 template <typename T>
27 void write_data(hid_t group_id, const std::vector<T>& data,
28  const std::vector<size_t>& extents,
29  const std::string& name = "scalar") noexcept;
30 
31 /*!
32  * \ingroup HDF5Group
33  * \brief Write a DataVector named `name` to the group `group_id`
34  */
35 void write_data(hid_t group_id, const DataVector& data,
36  const std::string& name) noexcept;
37 
38 /*!
39  * \ingroup HDF5Group
40  * \brief Write the extents as an attribute named `name` to the group
41  * `group_id`.
42  */
43 template <size_t Dim>
44 void write_extents(hid_t group_id, const Index<Dim>& extents,
45  const std::string& name = "Extents");
46 
47 /*!
48  * \ingroup HDF5Group
49  * \brief Write a value of type `Type` to an HDF5 attribute named `name`
50  */
51 template <typename Type>
52 void write_to_attribute(hid_t location_id, const std::string& name,
53  const Type& value) noexcept;
54 
55 /*!
56  * \ingroup HDF5Group
57  * \brief Write the vector `data` to the attribute `attribute_name` in the group
58  * `group_id`.
59  */
60 template <typename T>
61 void write_to_attribute(hid_t group_id, const std::string& name,
62  const std::vector<T>& data) noexcept;
63 
64 /*!
65  * \ingroup HDF5Group
66  * \brief Read a value of type `Type` from an HDF5 attribute named `name`
67  */
68 template <typename Type>
69 Type read_value_attribute(hid_t location_id, const std::string& name) noexcept;
70 
71 /*!
72  * \ingroup HDF5Group
73  * \brief Read rank-1 of type `Type` from an HDF5 attribute named `name`
74  */
75 template <typename T>
76 std::vector<T> read_rank1_attribute(hid_t group_id,
77  const std::string& name) noexcept;
78 
79 /*!
80  * \ingroup HDF5Group
81  * \brief Get the names of all the attributes in a group
82  */
83 std::vector<std::string> get_attribute_names(hid_t file_id,
84  const std::string& group_name);
85 
86 /*!
87  * \ingroup HDF5Group
88  * \brief Write the connectivity into the group in the H5 file
89  */
90 void write_connectivity(hid_t group_id,
91  const std::vector<int>& connectivity) noexcept;
92 
93 /*!
94  * \ingroup HDF5Group
95  * \brief Get the names of all the groups and datasets in a group
96  */
97 std::vector<std::string> get_group_names(
98  hid_t file_id, const std::string& group_name) noexcept;
99 
100 /*!
101  * \ingroup HDF5Group
102  * \brief Check if `name` is a dataset or group in the subgroup `group_name` of
103  * `id`.
104  *
105  * \note To check the current id for `name`, pass `""` as `group_name`.
106  */
107 bool contains_dataset_or_group(hid_t id, const std::string& group_name,
108  const std::string& dataset_name) noexcept;
109 
110 /*!
111  * \ingroup HDF5Group
112  * \brief Check if an attribute is in a group
113  */
114 bool contains_attribute(hid_t file_id, const std::string& group_name,
115  const std::string& attribute_name);
116 
117 /*!
118  * \ingroup HDF5Group
119  * \brief Open an HDF5 dataset
120  */
121 hid_t open_dataset(hid_t group_id,
122  const std::string& dataset_name) noexcept;
123 
124 /*!
125  * \ingroup HDF5Group
126  * \brief Close an HDF5 dataset
127  */
128 void close_dataset(hid_t dataset_id) noexcept;
129 
130 /*!
131  * \ingroup HDF5Group
132  * \brief Open an HDF5 dataspace
133  */
134 hid_t open_dataspace(hid_t dataset_id) noexcept;
135 
136 /*!
137  * \ingroup HDF5Group
138  * \brief Close an HDF5 dataspace
139  */
140 void close_dataspace(hid_t dataspace_id) noexcept;
141 
142 /*!
143  * \ingroup HDF5Group
144  * \brief Read an array of rank 0-3 into an object.
145  *
146  * For each rank, the data can be read into objects of the following types:
147  * rank 0: double or int
148  * rank 1: std::vector or DataVector
149  * rank 2: boost::multiarray or DataVector
150  * rank 3: boost::multiarray or DataVector
151  */
152 template <size_t Rank, typename T>
153 T read_data(hid_t group_id, const std::string& dataset_name) noexcept;
154 
155 /*!
156  * \ingroup HDF5Group
157  * \brief Read the HDF5 attribute representing extents from a group
158  */
159 template <size_t Dim>
160 Index<Dim> read_extents(hid_t group_id,
161  const std::string& extents_name = "Extents");
162 } // namespace h5
163 
164 namespace h5 {
165 namespace detail {
166 /*!
167  * \ingroup HDF5Group
168  * \brief Create a dataset that can be extended/appended to
169  *
170  * \requires group_id is an open group, each element of `initial_size` is less
171  * than the respective element in `max_size`, and each element in `max_size` is
172  * a positive integer or `H5S_UNLIMITED`
173  * \effects creates a potentially extensible dataset of dimension Dim inside the
174  * group `group_id`
175  * \returns the HDF5 id to the created dataset
176  *
177  * See the tutorial at https://support.hdfgroup.org/HDF5/Tutor/extend.html
178  * for details on the implementation choice.
179  */
180 template <size_t Dims>
181 hid_t create_extensible_dataset(hid_t group_id, const std::string& name,
182  const std::array<hsize_t, Dims>& initial_size,
183  const std::array<hsize_t, Dims>& chunk_size,
184  const std::array<hsize_t, Dims>& max_size);
185 } // namespace detail
186 } // namespace h5
Contains functions and classes for manipulating HDF5 files.
Definition: AccessType.cpp:10
std::vector< std::string > get_attribute_names(const hid_t file_id, const std::string &group_name)
Get the names of all the attributes in a group.
Definition: Helpers.cpp:392
std::vector< std::string > get_group_names(const hid_t file_id, const std::string &group_name) noexcept
Get the names of all the groups and datasets in a group.
Definition: Helpers.cpp:184
hid_t open_dataspace(const hid_t dataset_id) noexcept
Open an HDF5 dataspace.
Definition: Helpers.cpp:441
void close_dataspace(const hid_t dataspace_id) noexcept
Close an HDF5 dataspace.
Definition: Helpers.cpp:447
void write_to_attribute(const hid_t location_id, const std::string &name, const Type &value) noexcept
Write a value of type Type to an HDF5 attribute named name
Definition: Helpers.cpp:219
hid_t open_dataset(const hid_t group_id, const std::string &dataset_name) noexcept
Open an HDF5 dataset.
Definition: Helpers.cpp:429
void write_connectivity(const hid_t group_id, const std::vector< int > &connectivity) noexcept
Write the connectivity into the group in the H5 file.
Definition: Helpers.cpp:167
Defines class template Index.
Definition: Determinant.hpp:11
void write_extents(const hid_t group_id, const Index< Dim > &extents, const std::string &name)
Write the extents as an attribute named name to the group group_id.
Definition: Helpers.cpp:150
Type read_value_attribute(const hid_t location_id, const std::string &name) noexcept
Read a value of type Type from an HDF5 attribute named name
Definition: Helpers.cpp:233
Stores a collection of function values.
Definition: DataVector.hpp:46
An integer multi-index.
Definition: Index.hpp:28
void close_dataset(const hid_t dataset_id) noexcept
Close an HDF5 dataset.
Definition: Helpers.cpp:437
T read_data(const hid_t group_id, const std::string &dataset_name) noexcept
Read an array of rank 0-3 into an object.
Definition: Helpers.cpp:452
bool contains_dataset_or_group(const hid_t id, const std::string &group_name, const std::string &dataset_name) noexcept
Check if name is a dataset or group in the subgroup group_name of id.
Definition: Helpers.cpp:213
Index< Dim > read_extents(const hid_t group_id, const std::string &extents_name)
Read the HDF5 attribute representing extents from a group.
Definition: Helpers.cpp:489
bool contains_attribute(const hid_t file_id, const std::string &group_name, const std::string &attribute_name)
Check if an attribute is in a group.
Definition: Helpers.cpp:421
std::vector< T > read_rank1_attribute(const hid_t group_id, const std::string &name) noexcept
Read rank-1 of type Type from an HDF5 attribute named name
Definition: Helpers.cpp:269
void write_data(const hid_t group_id, const std::vector< T > &data, const std::vector< size_t > &extents, const std::string &name) noexcept
Write a std::vector named name to the group group_id
Definition: Helpers.cpp:114