Debian Codegraph @

include/deal.II/base/hdf5.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2019 - 2025 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_hdf5_h
16 #define dealii_hdf5_h
17
18 #include <deal.II/base/config.h>
19
20 #ifdef DEAL_II_WITH_HDF5
21
22 # include <deal.II/base/array_view.h>
23
24 # include <deal.II/lac/full_matrix.h>
25
26 # include <hdf5.h>
27
28 # include <numeric>
29
30 DEAL_II_NAMESPACE_OPEN
31
32 // It is necessary to turn clang-format off in order to maintain the Doxygen
33 // links because they are longer than 80 characters
34 // clang-format off
35 /**
36 * Namespace containing deal.II's HDF5 interface.
37 *
38 * The [Hierarchical Data Format (HDF)](https://www.hdfgroup.org/) is a cross
39 * platform and a high I/O performance format designed to store large amounts of
40 * data. It supports serial and MPI I/O access. This set of classes provides an
41 * interface to the [HDF5 library](https://www.hdfgroup.org/downloads/hdf5/).
42 *
43 * The tutorial step-62 shows how to use deal.II's HDF5 interface.
44 *
45 * # Groups, Datasets and attributes
46 * An HDF5 file is organized in
47 * [groups](https://bitbucket.hdfgroup.org/pages/HDFFV/hdf5doc/master/browse/html/UG/HDF5_Users_Guide-Responsive%20HTML5/HDF5_Users_Guide/Groups/HDF5_Groups.htm)
48 * and
49 * [datasets](https://bitbucket.hdfgroup.org/pages/HDFFV/hdf5doc/master/browse/html/UG/HDF5_Users_Guide-Responsive%20HTML5/HDF5_Users_Guide/Datasets/HDF5_Datasets.htm).
50 * Groups can contain datasets and other groups. Datasets are objects composed by
51 * a collection of data elements. Datasets are equivalent to tensors and matrices.
52 * In addition, attributes can be attached to the root file, a group or a
53 * dataset. An [HDF5
54 * attribute](https://bitbucket.hdfgroup.org/pages/HDFFV/hdf5doc/master/browse/html/UG/HDF5_Users_Guide-Responsive%20HTML5/HDF5_Users_Guide/Attributes/HDF5_Attributes.htm)
55 * is a small meta data. The methods HDF5Object::get_attribute() and
56 * HDF5Object::set_attribute() can be used to get and set attributes.
57 *
58 * An example is shown below
59 * @code
60 * HDF5::File data_file(filename, HDF5::File::FileAccessMode::create);
61 * double double_attribute = 2.2;
62 * data_file.set_attribute("double_attribute", double_attribute);
63 * auto group = data_file.create_group("group");
64 * group.set_attribute("simulation_type", "elastic_equation");
65 * auto dataset = group.create_dataset<double>("dataset_name", dimensions);
66 * dataset.set_attribute("complex_double_attribute",
67 * std::complex<double>(2,2.3));
68 * @endcode
69 *
70 * # MPI I/O
71 * An HDF5 file can be opened/created with serial (one single process) or
72 * MPI support (several processes access the same HDF5 file).
73 * File::File(const std::string &, const FileAccessMode)
74 * opens/creates an HDF5 file for serial operations.
75 * File::File(const std::string &, const FileAccessMode, const MPI_Comm )
76 * creates or opens an HDF5 file in parallel using MPI. The HDF5 calls that
77 * modify the structure of the file are always collective, whereas writing
78 * and reading raw data in a dataset can be done independently or collectively.
79 * [Collective access is usually faster](https://www.hdfgroup.org/2015/08/parallel-io-with-hdf5/)
80 * since it allows MPI to do optimizations. In the deal.II's HDF5 interface all
81 * the calls are set to collective in order to maximize the performance. This
82 * means that all the MPI processes have to contribute to every single call, even
83 * if they don't have data to write. MPI HDF5 requires that deal.II and HDF5 have
84 * been compiled with MPI support.
85 *
86 * ## Write a hyperslab in parallel
87 * Hyperslabs are portions of datasets. A hyperslab can be a contiguous
88 * collection of points in a dataset, or it can be a regular pattern of points
89 * or blocks in a datataset. Hyperslabs are equivalent to python numpy and h5py
90 * [slices](http://docs.h5py.org/en/latest/high/dataset.html#reading-writing-data).
91 * See the <a
92 * href="https://support.hdfgroup.org/HDF5/doc/UG/HDF5_Users_Guide-Responsive%20HTML5/HDF5_Users_Guide/Dataspaces/HDF5_Dataspaces_and_Partial_I_O.htm?rhtocid=7.2#TOC_7_4_Dataspaces_and_Databc-6">Dataspaces
93 * and Data Transfer</a> section in the HDF5 User's Guide. See as well the
94 * <a
95 * href="https://support.hdfgroup.org/HDF5/doc1.8/RM/RM_H5S.html#Dataspace-SelectHyperslab">H5Sselect_hyperslab
96 * definition</a>.
97 *
98 * The example below shows how to write a simple rectangular hyperslab. The
99 * offset defines the origin of the hyperslab in the original dataset. The
100 * dimensions of the hyperslab are `hyperslab_dimensions = {2, 5}`. Note that
101 * each process can write a hyperslab with a different size. If a process does
102 * not write any data at all, the process should call the function
103 * DataSet::write_none() because the operation is *collective* and all the MPI
104 * processes have to contribute to the call, even if they don't have data to
105 * write.
106 * @code
107 * std::vector<hsize_t> dataset_dimensions = {50, 30};
108 * auto dataset = group.create_dataset<double>("name", dataset_dimensions);
109 * if (Utilities::MPI::this_mpi_process(mpi_communicator) == 0)
110 * {
111 * // hyperslab_data can be std::vector, FullMatrix or Vector
112 * FullMatrix<double> hyperslab_data = {...};
113 * std::vector<hsize_t> hyperslab_offset = {1, 2};
114 * std::vector<hsize_t> hyperslab_dimensions = {2, 3};
115 * dataset.write_hyperslab(hyperslab_data,
116 * hyperslab_offset,
117 * hyperslab_dimensions);
118 * }
119 * else
120 * {
121 * dataset.write_none<double>();
122 * }
123 * @endcode
124 *
125 * The function
126 * DataSet::write_hyperslab(const Container &,const std::vector<hsize_t> &, const std::vector<hsize_t> &)
127 * is used to write simple hyperslabs and the function
128 * DataSet::write_hyperslab(const Container &,const std::vector<hsize_t> &, const std::vector<hsize_t> &, const std::vector<hsize_t> &, const std::vector<hsize_t> &, const std::vector<hsize_t> &)
129 * is used to write complex hyperslabs.
130 *
131 * ## Write unordered data in parallel
132 * The example below shows how to write a selection of data. Note that each
133 * process can write a different amount of data. If a process does not write
134 * any data at all, the process should call the function
135 * DataSet::write_none() because the operation is *collective* and all the MPI
136 * processes have to contribute to the call, even if they don't have data to
137 * write. A more detailed example can be found in step-62.
138 * @code
139 * std::vector<hsize_t> dataset_dimensions = {50, 30};
140 * auto dataset = group.create_dataset<double>("name", dataset_dimensions);
141 *
142 * if (Utilities::MPI::this_mpi_process(mpi_communicator) == 0)
143 * {
144 * std::vector<hsize_t> coordinates = {0,
145 * 0, // first point
146 * 0,
147 * 2, // second point
148 * 3,
149 * 4, // third point
150 * 25,
151 * 12}; // fourth point
152 * std::vector<double> data = {2, 3, 5, 6};
153 * dataset.write_selection(data, coordinates);
154 * }
155 * else if (Utilities::MPI::this_mpi_process(mpi_communicator) == 1)
156 * {
157 * std::vector<hsize_t> coordinates = {5,
158 * 0, // first point
159 * 0,
160 * 4, // second point
161 * 5,
162 * 4, // third point
163 * 26,
164 * 12}; // fourth point
165 * std::vector<double> data = {9, 4, 7, 6};
166 * dataset.write_selection(data, coordinates);
167 * }
168 * else
169 * {
170 * dataset.write_none<double>();
171 * }
172 * @endcode
173 *
174 * ## Query the I/O mode that HDF5 used in the last parallel I/O call
175 * The default access mode in the deal.II's HDF5 C++ interface is collective
176 * which is typically faster since it allows MPI to do more optimizations. In
177 * some cases, such as when there is type conversion, the HDF5 library can
178 * decide to do independent I/O instead of collective I/O, even if the user asks
179 * for collective I/O. See the following
180 * [article](https://www.hdfgroup.org/2015/08/parallel-io-with-hdf5/).
181 * In cases where maximum performance is a requirement, it is important to
182 * make sure that all MPI read/write operations are collective. The HDF5 library
183 * provides API routines that can be used after the read/write I/O operations to
184 * query the I/O mode. If DataSet::query_io_mode is True, then after
185 * every read/write operation the deal.II's HDF5 interface calls the routines
186 * [H5Pget_mpio_actual_io_mode()](https://support.hdfgroup.org/HDF5/doc/RM/RM_H5P.html#Property-GetMpioActualIoMode)
187 * and
188 * [H5Pget_mpio_no_collective_cause()](https://support.hdfgroup.org/HDF5/doc/RM/RM_H5P.html#Property-GetMpioNoCollectiveCause).
189 * The results are stored in DataSet::io_mode, DataSet::local_no_collective_cause
190 * and DataSet::get_global_no_collective_cause. We suggest to query the I/O mode
191 * only in Debug mode because it requires calling additional HDF5 routines.
192 *
193 * The following code can be used to query the I/O method.
194 * @code
195 * auto dataset = group.create_dataset<double>("name", dimensions);
196 * if constexpr (running_in_debug_mode())
197 * dataset.set_query_io_mode(true);
198 *
199 * if (Utilities::MPI::this_mpi_process(mpi_communicator) == 0)
200 * {
201 * dataset.write(data);
202 * }
203 * else
204 * {
205 * dataset.write_none<double>();
206 * }
207 *
208 * if(dataset.get_query_io_mode()){
209 * pcout << "IO mode: " << dataset.io_mode() << std::endl;
210 * pcout << "Local no collective cause: "
211 * << dataset.local_no_collective_cause() << std::endl;
212 * pcout << "Global no collective cause: "
213 * << dataset.get_global_no_collective_cause() <<
214 * std::endl;
215 * }
216 * @endcode
217 *
218 * If the write operation was collective then the output should be
219 * @code
220 * IO mode: H5D_MPIO_CONTIGUOUS_COLLECTIVE
221 * Local no collective cause: H5D_MPIO_COLLECTIVE
222 * Global no collective cause: H5D_MPIO_COLLECTIVE
223 * @endcode
224 * See DataSet::get_io_mode(), DataSet::get_local_no_collective_cause() and
225 * DataSet::get_global_no_collective_cause() for all the possible return
226 * codes.
227 *
228 * # Rank of HDF5 datasets and hyperslabs
229 * The deal.II's HDF5 interface can be used to write/read data to datasets and
230 * hyperslabs of any particular rank. `FullMatrix` can only be used to
231 * write/read data to datasets and hyperslabs of rank 2. In the other hand,
232 * `std::vector` and `Vector` can be used to write/read data to datasets and
233 * hyperslabs of rank 1, 2, 3 and higher, the data is organized in
234 * [row-major order](https://en.wikipedia.org/wiki/Row-_and_column-major_order)
235 * which is commonly used in C and C++ matrices. We can re-write the code from
236 * the previous section using std::vector
237 * @code
238 * // Dataset of rank 2. dim_0 = 50, dim_1 = 30
239 * std::vector<hsize_t> dataset_dimensions = {50, 30};
240 * auto dataset = group.create_dataset<double>("name", dataset_dimensions);
241 * if (Utilities::MPI::this_mpi_process(mpi_communicator) == 0)
242 * {
243 * // hyperslab_data can be std::vector, FullMatrix or Vector
244 * std::vector<double> hyperslab_data = {0,1,2,3,4,5};
245 * // hyperslab of rank 2. dim_0 = 2 and dim_1 = 3
246 * std::vector<hsize_t> hyperslab_offset = {1, 2};
247 * std::vector<hsize_t> hyperslab_dimensions = {2, 3};
248 * dataset.write_hyperslab(hyperslab_data,
249 * hyperslab_offset,
250 * hyperslab_dimensions);
251 * }
252 * else
253 * {
254 * dataset.write_none<double>();
255 * }
256 * @endcode
257 * The previous code writes the following hyperslab matrix
258 * @code
259 * 0 1
260 * 2 3
261 * 4 5
262 * @endcode
263 *
264 * # Datatypes
265 * Attribute datatypes can be float, `double`, `std::complex<float>`,
266 * `std::complex<double>`, `int`, `unsigned int`, `bool` and `std::string`.
267 * HDF5Object::get_attribute() and HDF5Object::set_attribute() can be used with
268 * all of these datatypes.
269 *
270 * Dataset datatypes can be `float`, `double`, `std::complex<float>`,
271 * `std::complex<double>`, `int` and `unsigned int`. DataSet::read(),
272 * DataSet::write(), DataSet::read_selection(), etc. can be used with all of
273 * these datatypes. Note that the dataset datatype can not be `bool`, the
274 * reason is that it can not be assumed that `std::vector<bool>` stores the
275 * elements in a contiguous way.
276 *
277 *
278 * ## Complex numbers and HDF5
279 * There is no official HDF5 format to store `std::complex` numbers in a HDF5
280 * file. But the *de facto* standard is to store the `std::complex` number in a
281 * compound type in which `r` corresponds to the real part and `i` corresponds
282 * to the imaginary part. In this interface we define two compound types one for
283 * `std::complex<double>` which corresponds to `(double,double)` and another
284 * one for `std::complex<float>` which corresponds to `(float,float)`. These two
285 * types correspond respectively to the types of python/numpy/h5py:
286 * `complex128` and `complex64`. This means that the files generated by this
287 * interface will be read correctly by python/numpy/h5py and at the same time
288 * this interface is able to read the files generated by python/numpy/h5py.
289 *
290 * # Data exchange with python scripts
291 * The HDF5 format can be used to exchange data with python scripts. The strings
292 * are stored as HDF5 variable-length UTF-8 strings and the complex numbers, as
293 * explained above, are stored as HDF5 compound datatypes compatible with
294 * [h5py](https://www.h5py.org/) and [numpy](http://www.numpy.org/).
295 *
296 * The following python script writes the parameters for a deal.II simulation:
297 * ~~~~~~~~~~~~~{.py}
298 * h5_file = h5py.File('simulation.hdf5','w')
299 * data = h5_file.create_group('data')
300 * data.attrs['nb_frequency_points'] = 50 # int
301 * data.attrs['rho'] = 2300.5 # double
302 * data.attrs['save_vtk_files'] = True # bool
303 * data.attrs['simulation_type'] = 'elastic_equation' # utf8 string
304 * ~~~~~~~~~~~~~
305 *
306 * C++ deal.II simulation with MPI HDF5:
307 * @code
308 * HDF5::File data_file("simulation.hdf5",
309 * HDF5::File::FileAccessMode::open,
310 * MPI_COMM_WORLD);
311 * HDF5::Group data = data_file.open_group("data");
312 *
313 * auto nb_frequency_points = data.get_attribute<int>("nb_frequency_points");
314 * auto rho = data.get_attribute<double>("rho");
315 * auto save_vtk_files = data.get_attribute<bool>("save_vtk_files");
316 * auto simulation_type = data.get_attribute<std::string>("simulation_type");
317 *
318 * std::vector<std::complex<double>> displacement = {...};
319 *
320 * data.write_dataset("displacement", displacement);
321 *
322 * // Write the simulation metadata
323 * data.set_attribute("active_cells", triangulation.n_active_cells());
324 * @endcode
325 *
326 * Read the simulation results with python:
327 * ~~~~~~~~~~~~~{.py}
328 * h5_file = h5py.File('simulation.hdf5','r+')
329 * data = h5_file['data']
330 * displacement = data['displacement'] # complex128 dtype
331 * active_cells = data.attrs['degrees_of_freedom'])
332 * ~~~~~~~~~~~~~
333 *
334 * # HDF5 and thread safety
335 * By default HDF5 is not thread-safe. The HDF5 library can be configured to be
336 * thread-safe, see [the HDF5
337 * documentation](https://support.hdfgroup.org/HDF5/faq/threadsafe.html). The
338 * thread-safe HDF5 version serializes the API but does not provide any level of
339 * concurrency. To achieve high parallel performance with HDF5, we advice to use
340 * HDF5 with MPI.
341 */
342 // clang-format on
343 namespace HDF5
344 {
345 /**
346 * Base class for the HDF5 objects.
347 */
348 class HDF5Object
349 {
350 protected:
351 /**
352 * Constructor. @p string_name is the name of the HDF5 Object. If @p mpi is
353 * True then MPI I/O is used.
354 */
355 HDF5Object(const std::string &name, const bool mpi);
356
357 public:
358 /**
359 * Reads an attribute. @p T can be `float`, `double`, `std::complex<float>`,
360 * `std::complex<double>`, `int`, `unsigned int`, `bool` or `std::string`.
361 * Note that the encoding of `std::string` is UTF8 in order to be compatible
362 * with python3.
363 *
364 * Datatype conversion takes place at the time of a read or write and is
365 * automatic. See the <a
366 * href="https://support.hdfgroup.org/HDF5/doc/UG/HDF5_Users_Guide-Responsive%20HTML5/index.html#t=HDF5_Users_Guide%2FDatatypes%2FHDF5_Datatypes.htm%23TOC_6_10_Data_Transferbc-26&rhtocid=6.5_2">Data
367 * Transfer: Datatype Conversion and Selection</a> section in the HDF5
368 * User's Guide.
369 */
370 template <typename T>
371 T
372 get_attribute(const std::string &attr_name) const;
373
374 /**
375 * Writes an attribute. @p T can be `float`, `double`, `std::complex<float>`,
376 * `std::complex<double>`, `int`, `unsigned int`, `bool` or `std::string`.
377 * Note that the encoding of `std::string` is UTF8 in order to be compatible
378 * with python3.
379 *
380 * Datatype conversion takes place at the time of a read or write and is
381 * automatic. See the <a
382 * href="https://support.hdfgroup.org/HDF5/doc/UG/HDF5_Users_Guide-Responsive%20HTML5/index.html#t=HDF5_Users_Guide%2FDatatypes%2FHDF5_Datatypes.htm%23TOC_6_10_Data_Transferbc-26&rhtocid=6.5_2">Data
383 * Transfer: Datatype Conversion and Selection</a> section in the HDF5
384 * User's Guide.
385 */
386 template <typename T>
387 void
388 set_attribute(const std::string &attr_name, const T value);
389
390 /**
391 * Returns the #name of the object. In the case of File, #name corresponds
392 * to the file name. In the case of Group and DataSet, #name corresponds to
393 * the name of the object in the HDF5 file.
394 */
395 std::string
396 get_name() const;
397
398 protected:
399 /**
400 * Name of the HDF5Object. In the case of File, @p name corresponds to the
401 * file name. In the case of Group and DataSet @p name corresponds to the
402 * name of the object in the HDF5 file.
403 */
404 const std::string name;
405
406 /**
407 * HDF5 identifier for the objects File, Group and DataSet. The
408 * `std::shared_ptr<>` pointer allows the object to be copied. For example
409 * several parts of the program can share and access the same group; when
410 * all the functions that access the group are closed, the HDF5 resources of
411 * the group will be automatically released.
412 */
413 std::shared_ptr<hid_t> hdf5_reference;
414
415 /**
416 * If true use parallel HDF5, if false use serial HDF5.
417 */
418 const bool mpi;
419 };
420
421 /**
422 * This class implements an HDF5 DataSet.
423 */
424 class DataSet : public HDF5Object
425 {
426 friend class Group;
427
428 protected:
429 /**
430 * Open dataset. This is an internal constructor. The function
431 * Group::open_dataset() should be used to open a dataset.
432 */
433 DataSet(const std::string &name, const hid_t &parent_group_id, bool mpi);
434
435 /**
436 * Create dataset. This is an internal constructor. The function
437 * Group::create_dataset() should be used to create a dataset.
438 */
439 DataSet(const std::string &name,
440 const hid_t &parent_group_id,
441 const std::vector<hsize_t> &dimensions,
442 const std::shared_ptr<hid_t> &t_type,
443 const bool mpi);
444
445 public:
446 /**
447 * Reads all the data of the dataset.
448 *
449 * Datatype conversion takes place at the time of the read operation and is
450 * automatic. See the <a
451 * href="https://support.hdfgroup.org/HDF5/doc/UG/HDF5_Users_Guide-Responsive%20HTML5/index.html#t=HDF5_Users_Guide%2FDatatypes%2FHDF5_Datatypes.htm%23TOC_6_10_Data_Transferbc-26&rhtocid=6.5_2">Data
452 * Transfer: Datatype Conversion and Selection</a> section in the HDF5
453 * User's Guide.
454 *
455 * `Container` can be `std::vector<float>`, `std::vector<double>`,
456 * `std::vector<std::complex<float>>`, `std::vector<std::complex<double>>`,
457 * `std::vector<int>`, `std::vector<unsigned int>`, `Vector<float>`,
458 * `Vector<double>`, `Vector<std::complex<float>>`,
459 * `Vector<std::complex<double>>`, `FullMatrix<float>`,
460 * `FullMatrix<double>`, `FullMatrix<std::complex<float>>` or
461 * `FullMatrix<std::complex<double>>`.
462 */
463 template <typename Container>
464 Container
465 read();
466
467 /**
468 * Reads data of a subset of the dataset.
469 *
470 * Datatype conversion takes place at the time of the read operation and is
471 * automatic. See the <a
472 * href="https://support.hdfgroup.org/HDF5/doc/UG/HDF5_Users_Guide-Responsive%20HTML5/index.html#t=HDF5_Users_Guide%2FDatatypes%2FHDF5_Datatypes.htm%23TOC_6_10_Data_Transferbc-26&rhtocid=6.5_2">Data
473 * Transfer: Datatype Conversion and Selection</a> section in the HDF5
474 * User's Guide.
475 *
476 * The selected elements can be scattered and take any shape in the dataset.
477 * For example, in the case of a dataset with rank 4 a selection of 3 points
478 * will be described by a 3-by-4 array. Note the indexing is zero-based. To
479 * select the points (1,1,1,1), (14,6,12,18), and (8,22,30,22), the point
480 * selection array would be as follows:
481 *
482 * @code
483 * 0 0 0 0
484 *
485 * 13 5 11 17
486 *
487 * 7 21 29 21
488 * @endcode
489 *
490 * <a
491 * href="https://support.hdfgroup.org/newsletters/newsletter140.html">Parallel
492 * HDF5 supports collective I/O on point selections.</a>
493 *
494 * Datatype conversion takes place at the time of the read operation and is
495 * automatic. See the <a
496 * href="https://support.hdfgroup.org/HDF5/doc/UG/HDF5_Users_Guide-Responsive%20HTML5/index.html#t=HDF5_Users_Guide%2FDatatypes%2FHDF5_Datatypes.htm%23TOC_6_10_Data_Transferbc-26&rhtocid=6.5_2">Data
497 * Transfer: Datatype Conversion and Selection</a> section in the HDF5
498 * User's Guide.
499 */
500 template <typename Container>
501 Container
502 read_selection(const std::vector<hsize_t> &coordinates);
503
504 // clang-format off
505 /**
506 * Reads a hyperslab from the dataset. The parameters are summarized
507 * below:
508 * - @p offset: The starting location for the hyperslab.
509 * - @p count: The number of elements to select along each dimension.
510 *
511 * When reading a hyperslab, HDF5 also allows to provide "stride" and
512 * "block" parameters (see the [HDF5 documentation](https://support.hdfgroup.org/HDF5/doc1.8/RM/RM_H5S.html#Dataspace-SelectHyperslab)).
513 * These are not used by the current function and set to `nullptr`. However
514 * these parameters can be used with the function
515 * read_hyperslab(const std::vector<hsize_t> &, const std::vector<hsize_t> &, const std::vector<hsize_t> &, const std::vector<hsize_t> &, const std::vector<hsize_t> &)
516 *
517 * See the <a
518 * href="https://support.hdfgroup.org/HDF5/doc/UG/HDF5_Users_Guide-Responsive%20HTML5/HDF5_Users_Guide/Dataspaces/HDF5_Dataspaces_and_Partial_I_O.htm?rhtocid=7.2#TOC_7_4_Dataspaces_and_Databc-6">Dataspaces
519 * and Data Transfer</a> section in the HDF5 User's Guide. See as well the
520 * <a
521 * href="https://support.hdfgroup.org/HDF5/doc1.8/RM/RM_H5S.html#Dataspace-SelectHyperslab">H5Sselect_hyperslab
522 * definition</a>.
523 *
524 * Datatype conversion takes place at the time of a read or write and is
525 * automatic. See the <a
526 * href="https://support.hdfgroup.org/HDF5/doc/UG/HDF5_Users_Guide-Responsive%20HTML5/index.html#t=HDF5_Users_Guide%2FDatatypes%2FHDF5_Datatypes.htm%23TOC_6_10_Data_Transferbc-26&rhtocid=6.5_2">Data
527 * Transfer: Datatype Conversion and Selection</a> section in the HDF5
528 * User's Guide.
529 *
530 * `Container` can be `std::vector<float>`, `std::vector<double>`,
531 * `std::vector<std::complex<float>>`, `std::vector<std::complex<double>>`,
532 * `std::vector<int>`, `std::vector<unsigned int>`, `Vector<float>`,
533 * `Vector<double>`, `Vector<std::complex<float>>`,
534 * `Vector<std::complex<double>>`, `FullMatrix<float>`,
535 * `FullMatrix<double>`, `FullMatrix<std::complex<float>>` or
536 * `FullMatrix<std::complex<double>>`.
537 */
538 // clang-format on
539 template <typename Container>
540 Container
541 read_hyperslab(const std::vector<hsize_t> &offset,
542 const std::vector<hsize_t> &count);
543
544 /**
545 * Writes a data hyperslab to the dataset. The parameters are summarized
546 * below:
547 * - @p dataset_dimensions: the dimensions of the data memory block.
548 * - @p offset: The starting location for the hyperslab.
549 * - @p stride: The number of elements to separate each element or block to
550 * be selected.
551 * - @p count: The number of elements or blocks to select along each
552 * dimension.
553 * - @p block: The size of the block selected from the dataspace.
554 *
555 * See the <a
556 * href="https://support.hdfgroup.org/HDF5/doc/UG/HDF5_Users_Guide-Responsive%20HTML5/HDF5_Users_Guide/Dataspaces/HDF5_Dataspaces_and_Partial_I_O.htm?rhtocid=7.2#TOC_7_4_Dataspaces_and_Databc-6">Dataspaces
557 * and Data Transfer</a> section in the HDF5 User's Guide. See as well the
558 * <a
559 * href="https://support.hdfgroup.org/HDF5/doc1.8/RM/RM_H5S.html#Dataspace-SelectHyperslab">H5Sselect_hyperslab
560 * definition</a>.
561 *
562 * Datatype conversion takes place at the time of a read or write and is
563 * automatic. See the <a
564 * href="https://support.hdfgroup.org/HDF5/doc/UG/HDF5_Users_Guide-Responsive%20HTML5/index.html#t=HDF5_Users_Guide%2FDatatypes%2FHDF5_Datatypes.htm%23TOC_6_10_Data_Transferbc-26&rhtocid=6.5_2">Data
565 * Transfer: Datatype Conversion and Selection</a> section in the HDF5
566 * User's Guide.
567 *
568 * `Container` can be `std::vector<float>`, `std::vector<double>`,
569 * `std::vector<std::complex<float>>`, `std::vector<std::complex<double>>`,
570 * `std::vector<int>`, `std::vector<unsigned int>`, `Vector<float>`,
571 * `Vector<double>`, `Vector<std::complex<float>>`,
572 * `Vector<std::complex<double>>`, `FullMatrix<float>`,
573 * `FullMatrix<double>`, `FullMatrix<std::complex<float>>` or
574 * `FullMatrix<std::complex<double>>`.
575 */
576 template <typename Container>
577 Container
578 read_hyperslab(const std::vector<hsize_t> &data_dimensions,
579 const std::vector<hsize_t> &offset,
580 const std::vector<hsize_t> &stride,
581 const std::vector<hsize_t> &count,
582 const std::vector<hsize_t> &block);
583
584 /**
585 * This function does not read any data, but it can contribute to a
586 * collective read call. @p number can be `float`, `double`,
587 * `std::complex<float>`, `std::complex<double>`, `int` or `unsigned int`.
588 *
589 * Datatype conversion takes place at the time of a read or write and is
590 * automatic. See the <a
591 * href="https://support.hdfgroup.org/HDF5/doc/UG/HDF5_Users_Guide-Responsive%20HTML5/index.html#t=HDF5_Users_Guide%2FDatatypes%2FHDF5_Datatypes.htm%23TOC_6_10_Data_Transferbc-26&rhtocid=6.5_2">Data
592 * Transfer: Datatype Conversion and Selection</a> section in the HDF5
593 * User's Guide.
594 */
595 template <typename number>
596 void
597 read_none();
598
599 /**
600 * Writes data in the dataset. @p number can be `float`, `double`,
601 * `std::complex<float>`, `std::complex<double>`, `int` or `unsigned int`.
602 *
603 * Datatype conversion takes place at the time of a read or write and is
604 * automatic. See the <a
605 * href="https://support.hdfgroup.org/HDF5/doc/UG/HDF5_Users_Guide-Responsive%20HTML5/index.html#t=HDF5_Users_Guide%2FDatatypes%2FHDF5_Datatypes.htm%23TOC_6_10_Data_Transferbc-26&rhtocid=6.5_2">Data
606 * Transfer: Datatype Conversion and Selection</a> section in the HDF5
607 * User's Guide.
608 *
609 * `Container` can be `std::vector<float>`, `std::vector<double>`,
610 * `std::vector<std::complex<float>>`, `std::vector<std::complex<double>>`,
611 * `std::vector<int>`, `std::vector<unsigned int>`, `Vector<float>`,
612 * `Vector<double>`, `Vector<std::complex<float>>`,
613 * `Vector<std::complex<double>>`, `FullMatrix<float>`,
614 * `FullMatrix<double>`, `FullMatrix<std::complex<float>>` or
615 * `FullMatrix<std::complex<double>>`.
616 */
617 template <typename Container>
618 void
619 write(const Container &data);
620
621 /**
622 * Writes data to a subset of the dataset. @p number can be `float`, `double`,
623 * `std::complex<float>`, `std::complex<double>`, `int` or `unsigned int`.
624 *
625 * The selected elements can be scattered and take any shape in the dataset.
626 * For example, in the case of a dataset with rank 4 a selection of 3 points
627 * will be described by a 3-by-4 array. Note the indexing is zero-based. To
628 * select the points (1,1,1,1), (14,6,12,18), and (8,22,30,22), the point
629 * selection array would be as follows:
630 *
631 * @code
632 * 0 0 0 0
633 *
634 * 13 5 11 17
635 *
636 * 7 21 29 21
637 * @endcode
638 *
639 * <a
640 * href="https://support.hdfgroup.org/newsletters/newsletter140.html">Parallel
641 * HDF5 supports collective I/O on point selections.</a>
642 *
643 * Datatype conversion takes place at the time of a read or write and is
644 * automatic. See the <a
645 * href="https://support.hdfgroup.org/HDF5/doc/UG/HDF5_Users_Guide-Responsive%20HTML5/index.html#t=HDF5_Users_Guide%2FDatatypes%2FHDF5_Datatypes.htm%23TOC_6_10_Data_Transferbc-26&rhtocid=6.5_2">Data
646 * Transfer: Datatype Conversion and Selection</a> section in the HDF5
647 * User's Guide.
648 */
649 template <typename Container>
650 void
651 write_selection(const Container &data,
652 const std::vector<hsize_t> &coordinates);
653
654 // clang-format off
655 /**
656 * Writes a data hyperslab to the dataset. The parameters are summarized
657 * below:
658 * - @p offset: The starting location for the hyperslab.
659 * - @p count: The number of elements to select along each dimension.
660 *
661 * When writing a hyperslab, HDF5 also allows to provide "stride" and
662 * "block" parameters (see the [HDF5 documentation](https://support.hdfgroup.org/HDF5/doc1.8/RM/RM_H5S.html#Dataspace-SelectHyperslab)).
663 * These are not used by the current function and set to `nullptr`. However
664 * these parameters can be used with the function
665 * write_hyperslab(const Container &data, const std::vector<hsize_t> &data_dimensions, const std::vector<hsize_t> &offset, const std::vector<hsize_t> &stride, const std::vector<hsize_t> &count, const std::vector<hsize_t> &block).
666 *
667 * See the <a
668 * href="https://support.hdfgroup.org/HDF5/doc/UG/HDF5_Users_Guide-Responsive%20HTML5/HDF5_Users_Guide/Dataspaces/HDF5_Dataspaces_and_Partial_I_O.htm?rhtocid=7.2#TOC_7_4_Dataspaces_and_Databc-6">Dataspaces
669 * and Data Transfer</a> section in the HDF5 User's Guide. See as well the
670 * <a
671 * href="https://support.hdfgroup.org/HDF5/doc1.8/RM/RM_H5S.html#Dataspace-SelectHyperslab">H5Sselect_hyperslab
672 * definition</a>.
673 *
674 * Datatype conversion takes place at the time of a read or write and is
675 * automatic. See the <a
676 * href="https://support.hdfgroup.org/HDF5/doc/UG/HDF5_Users_Guide-Responsive%20HTML5/index.html#t=HDF5_Users_Guide%2FDatatypes%2FHDF5_Datatypes.htm%23TOC_6_10_Data_Transferbc-26&rhtocid=6.5_2">Data
677 * Transfer: Datatype Conversion and Selection</a> section in the HDF5
678 * User's Guide.
679 */
680 // clang-format on
681 template <typename Container>
682 void
683 write_hyperslab(const Container &data,
684 const std::vector<hsize_t> &offset,
685 const std::vector<hsize_t> &count);
686
687 /**
688 * Writes a data hyperslab to the dataset. The parameters are summarized
689 * below:
690 * - @p dataset_dimensions: the dimensions of the data memory block.
691 * - @p offset: The starting location for the hyperslab.
692 * - @p stride: The number of elements to separate each element or block to be
693 * selected.
694 * - @p count: The number of elements or blocks to select along each
695 * dimension.
696 * - @p block: The size of the block selected from the dataspace.
697 *
698 * See the <a
699 * href="https://support.hdfgroup.org/HDF5/doc/UG/HDF5_Users_Guide-Responsive%20HTML5/HDF5_Users_Guide/Dataspaces/HDF5_Dataspaces_and_Partial_I_O.htm?rhtocid=7.2#TOC_7_4_Dataspaces_and_Databc-6">Dataspaces
700 * and Data Transfer</a> section in the HDF5 User's Guide. See as well the
701 * <a
702 * href="https://support.hdfgroup.org/HDF5/doc1.8/RM/RM_H5S.html#Dataspace-SelectHyperslab">H5Sselect_hyperslab
703 * definition</a>.
704 *
705 * Datatype conversion takes place at the time of a read or write and is
706 * automatic. See the <a
707 * href="https://support.hdfgroup.org/HDF5/doc/UG/HDF5_Users_Guide-Responsive%20HTML5/index.html#t=HDF5_Users_Guide%2FDatatypes%2FHDF5_Datatypes.htm%23TOC_6_10_Data_Transferbc-26&rhtocid=6.5_2">Data
708 * Transfer: Datatype Conversion and Selection</a> section in the HDF5
709 * User's Guide.
710 *
711 * `Container` can be `std::vector<float>`, `std::vector<double>`,
712 * `std::vector<std::complex<float>>`, `std::vector<std::complex<double>>`,
713 * `std::vector<int>`, `std::vector<unsigned int>`, `Vector<float>`,
714 * `Vector<double>`, `Vector<std::complex<float>>`,
715 * `Vector<std::complex<double>>`, `FullMatrix<float>`,
716 * `FullMatrix<double>`, `FullMatrix<std::complex<float>>` or
717 * `FullMatrix<std::complex<double>>`.
718 */
719 template <typename Container>
720 void
721 write_hyperslab(const Container &data,
722 const std::vector<hsize_t> &data_dimensions,
723 const std::vector<hsize_t> &offset,
724 const std::vector<hsize_t> &stride,
725 const std::vector<hsize_t> &count,
726 const std::vector<hsize_t> &block);
727
728 /**
729 * This function does not write any data, but it can contribute to a
730 * collective write call. In the context of a collective MPI write call,
731 * if a process does not write any data at all, the process should call
732 * this function because the operation is *collective* and all the MPI
733 * processes have to contribute to the call, even if they don't have data
734 * to write. @p number can be `float`, `double`, `std::complex<float>`,
735 * `std::complex<double>`, `int` or `unsigned int`.
736 *
737 * Datatype conversion takes place at the time of a read or write and is
738 * automatic. See the <a
739 * href="https://support.hdfgroup.org/HDF5/doc/UG/HDF5_Users_Guide-Responsive%20HTML5/index.html#t=HDF5_Users_Guide%2FDatatypes%2FHDF5_Datatypes.htm%23TOC_6_10_Data_Transferbc-26&rhtocid=6.5_2">Data
740 * Transfer: Datatype Conversion and Selection</a> section in the HDF5
741 * User's Guide.
742 *
743 * An example of how to use this function can be found in step-62.
744 */
745 template <typename number>
746 void
747 write_none();
748
749 /**
750 * This function returns the boolean query_io_mode.
751 *
752 * In cases where maximum performance has to be achieved, it is important to
753 * make sure that all MPI read/write operations are collective. The HDF5
754 * library provides API routines that can be used after the read/write I/O
755 * operations to query the I/O mode. If query_io_mode is set to true, then
756 * after every read/write operation the deal.II's HDF5 interface calls the
757 * routines
758 * [H5Pget_mpio_actual_io_mode()](https://support.hdfgroup.org/HDF5/doc/RM/RM_H5P.html#Property-GetMpioActualIoMode)
759 * and
760 * [H5Pget_mpio_no_collective_cause()](https://support.hdfgroup.org/HDF5/doc/RM/RM_H5P.html#Property-GetMpioNoCollectiveCause).
761 * The results are stored in io_mode, local_no_collective_cause and
762 * global_no_collective_cause. We suggest to query the I/O mode only in
763 * Debug mode because it requires calling additional HDF5 routines.
764 */
765 bool
766 get_query_io_mode() const;
767
768 /**
769 * This function sets the boolean query_io_mode.
770 */
771 void
772 set_query_io_mode(const bool new_query_io_mode);
773
774 /**
775 * This function returns the I/O mode that was used on the last
776 * parallel I/O call. See <a
777 * href="https://support.hdfgroup.org/HDF5/doc/RM/RM_H5P.html#Property-GetMpioActualIoMode">H5Pget_mpio_actual_io_mode</a>.
778 *
779 * The return value is a `std::string` and can be
780 * Value | Meaning
781 * ------------------------------ | -------
782 * H5D_MPIO_NO_COLLECTIVE | No collective I/O was performed. Collective I/O was not requested or collective I/O isn't possible on this dataset.
783 * H5D_MPIO_CHUNK_INDEPENDENT | HDF5 performed chunk collective optimization schemes and each chunk was accessed independently.
784 * H5D_MPIO_CHUNK_COLLECTIVE | HDF5 performed chunk collective optimization and each chunk was accessed collectively.
785 * H5D_MPIO_CHUNK_MIXED | HDF5 performed chunk collective optimization and some chunks were accessed independently, some collectively.
786 * H5D_MPIO_CONTIGUOUS_COLLECTIVE | Collective I/O was performed on a contiguous dataset.
787 */
788 std::string
789 get_io_mode();
790
791 /**
792 * This function returns the I/O mode that was used on the last
793 * parallel I/O call. See <a
794 * href="https://support.hdfgroup.org/HDF5/doc/RM/RM_H5P.html#Property-GetMpioActualIoMode">H5Pget_mpio_actual_io_mode</a>.
795 * The return type is `H5D_mpio_actual_io_mode_t` which corresponds to the
796 * value returned by H5Pget_mpio_actual_io_mode.
797 *
798 * The return value can be
799 * Value | Meaning
800 * ------------------------------ | -------
801 * H5D_MPIO_NO_COLLECTIVE | No collective I/O was performed. Collective I/O was not requested or collective I/O isn't possible on this dataset.
802 * H5D_MPIO_CHUNK_INDEPENDENT | HDF5 performed chunk collective optimization and each chunk was accessed independently.
803 * H5D_MPIO_CHUNK_COLLECTIVE | HDF5 performed chunk collective optimization and each chunk was accessed collectively.
804 * H5D_MPIO_CHUNK_MIXED | HDF5 performed chunk collective optimization and some chunks were accessed independently, some collectively.
805 * H5D_MPIO_CONTIGUOUS_COLLECTIVE | Collective I/O was performed on a contiguous dataset.
806 */
807 H5D_mpio_actual_io_mode_t
808 get_io_mode_as_hdf5_type();
809
810 /**
811 * This function returns the local causes that broke collective I/O on the
812 * last parallel I/O call. See <a
813 * href="https://support.hdfgroup.org/HDF5/doc/RM/RM_H5P.html#Property-GetMpioNoCollectiveCause">H5Pget_mpio_no_collective_cause</a>.
814 *
815 * The return value is a string and can be
816 * Value | Meaning
817 * ------------------------------------------ | -------
818 * H5D_MPIO_COLLECTIVE | Collective I/O was performed successfully.
819 * H5D_MPIO_SET_INDEPENDENT | Collective I/O was not performed because independent I/O was requested.
820 * H5D_MPIO_DATATYPE_CONVERSION | Collective I/O was not performed because datatype conversions were required.
821 * H5D_MPIO_DATA_TRANSFORMS | Collective I/O was not performed because data transforms needed to be applied.
822 * H5D_MPIO_SET_MPIPOSIX | Collective I/O was not performed because the selected file driver was MPI-POSIX.
823 * H5D_MPIO_NOT_SIMPLE_OR_SCALAR_DATASPACES | Collective I/O was not performed because one of the dataspaces was neither simple nor scalar.
824 * H5D_MPIO_POINT_SELECTIONS | Collective I/O was not performed because there were point selections in one of the dataspaces.
825 * H5D_MPIO_NOT_CONTIGUOUS_OR_CHUNKED_DATASET | Collective I/O was not performed because the dataset was neither contiguous nor chunked.
826 * H5D_MPIO_FILTERS | Collective I/O was not performed because filters needed to be applied.
827 */
828 std::string
829 get_local_no_collective_cause();
830
831 /**
832 * This function returns the local causes that broke collective I/O on the
833 * last parallel I/O call. See <a
834 * href="https://support.hdfgroup.org/HDF5/doc/RM/RM_H5P.html#Property-GetMpioNoCollectiveCause">H5Pget_mpio_no_collective_cause</a>.
835 * The return type is `std::uint32_t` and corresponds to the value returned
836 * by
837 * [H5Pget_mpio_no_collective_cause](https://support.hdfgroup.org/HDF5/doc/RM/RM_H5P.html#Property-GetMpioNoCollectiveCause).
838 *
839 * The return value can be
840 * Value | Meaning
841 * ------------------------------------------ | -------
842 * H5D_MPIO_COLLECTIVE | Collective I/O was performed successfully.
843 * H5D_MPIO_SET_INDEPENDENT | Collective I/O was not performed because independent I/O was requested.
844 * H5D_MPIO_DATATYPE_CONVERSION | Collective I/O was not performed because datatype conversions were required.
845 * H5D_MPIO_DATA_TRANSFORMS | Collective I/O was not performed because data transforms needed to be applied.
846 * H5D_MPIO_SET_MPIPOSIX | Collective I/O was not performed because the selected file driver was MPI-POSIX.
847 * H5D_MPIO_NOT_SIMPLE_OR_SCALAR_DATASPACES | Collective I/O was not performed because one of the dataspaces was neither simple nor scalar.
848 * H5D_MPIO_POINT_SELECTIONS | Collective I/O was not performed because there were point selections in one of the dataspaces.
849 * H5D_MPIO_NOT_CONTIGUOUS_OR_CHUNKED_DATASET | Collective I/O was not performed because the dataset was neither contiguous nor chunked.
850 * H5D_MPIO_FILTERS | Collective I/O was not performed because filters needed to be applied.
851 */
852 std::uint32_t
853 get_local_no_collective_cause_as_hdf5_type();
854
855 /**
856 * This function retrieves the global causes that broke collective I/O on
857 * the last parallel I/O call. See <a
858 * href="https://support.hdfgroup.org/HDF5/doc/RM/RM_H5P.html#Property-GetMpioNoCollectiveCause">H5Pget_mpio_no_collective_cause</a>.
859 *
860 * The return value is a std::string and can be
861 * Value | Meaning
862 * ------------------------------------------ | -------
863 * H5D_MPIO_COLLECTIVE | Collective I/O was performed successfully.
864 * H5D_MPIO_SET_INDEPENDENT | Collective I/O was not performed because independent I/O was requested.
865 * H5D_MPIO_DATATYPE_CONVERSION | Collective I/O was not performed because datatype conversions were required.
866 * H5D_MPIO_DATA_TRANSFORMS | Collective I/O was not performed because data transforms needed to be applied.
867 * H5D_MPIO_SET_MPIPOSIX | Collective I/O was not performed because the selected file driver was MPI-POSIX.
868 * H5D_MPIO_NOT_SIMPLE_OR_SCALAR_DATASPACES | Collective I/O was not performed because one of the dataspaces was neither simple nor scalar.
869 * H5D_MPIO_POINT_SELECTIONS | Collective I/O was not performed because there were point selections in one of the dataspaces.
870 * H5D_MPIO_NOT_CONTIGUOUS_OR_CHUNKED_DATASET | Collective I/O was not performed because the dataset was neither contiguous nor chunked.
871 * H5D_MPIO_FILTERS | Collective I/O was not performed because filters needed to be applied.
872 */
873 std::string
874 get_global_no_collective_cause();
875
876 /**
877 * This function returns the global causes that broke collective I/O on the
878 * last parallel I/O call. See <a
879 * href="https://support.hdfgroup.org/HDF5/doc/RM/RM_H5P.html#Property-GetMpioNoCollectiveCause">H5Pget_mpio_no_collective_cause</a>.
880 * The return type is `std::uint32_t` and corresponds to the value returned
881 * by H5Pget_mpio_no_collective_cause.
882 *
883 * The return value can be
884 * Value | Meaning
885 * ------------------------------------------ | -------
886 * H5D_MPIO_COLLECTIVE | Collective I/O was performed successfully.
887 * H5D_MPIO_SET_INDEPENDENT | Collective I/O was not performed because independent I/O was requested.
888 * H5D_MPIO_DATATYPE_CONVERSION | Collective I/O was not performed because datatype conversions were required.
889 * H5D_MPIO_DATA_TRANSFORMS | Collective I/O was not performed because data transforms needed to be applied.
890 * H5D_MPIO_SET_MPIPOSIX | Collective I/O was not performed because the selected file driver was MPI-POSIX.
891 * H5D_MPIO_NOT_SIMPLE_OR_SCALAR_DATASPACES | Collective I/O was not performed because one of the dataspaces was neither simple nor scalar.
892 * H5D_MPIO_POINT_SELECTIONS | Collective I/O was not performed because there were point selections in one of the dataspaces.
893 * H5D_MPIO_NOT_CONTIGUOUS_OR_CHUNKED_DATASET | Collective I/O was not performed because the dataset was neither contiguous nor chunked.
894 * H5D_MPIO_FILTERS | Collective I/O was not performed because filters needed to be applied.
895 */
896 std::uint32_t
897 get_global_no_collective_cause_as_hdf5_type();
898
899 /**
900 * This function returns the dimensions of the dataset. The vector
901 * dimensions is a one-dimensional array of size rank specifying the size of
902 * each dimension of the dataset.
903 */
904 std::vector<hsize_t>
905 get_dimensions() const;
906
907 /**
908 * This function returns the total number of elements in the dataset.
909 */
910 unsigned int
911 get_size() const;
912
913 /**
914 * This function returns the rank of the dataset.
915 */
916 unsigned int
917 get_rank() const;
918
919 private:
920 /**
921 * Rank of the DataSet
922 */
923 unsigned int rank;
924
925 /**
926 * The vector `dimensions` is a one-dimensional array of size rank
927 * specifying the size of each dimension of the dataset.
928 */
929 std::vector<hsize_t> dimensions;
930
931 /**
932 * HDF5 dataspace identifier.
933 */
934 std::shared_ptr<hid_t> dataspace;
935
936 /**
937 * Total number of elements in the dataset.
938 */
939 unsigned int size;
940
941 /**
942 * If query_io_mode is set to true, then after every read/write operation
943 * the deal.II's HDF5 interface calls the routines
944 * [H5Pget_mpio_actual_io_mode()](https://support.hdfgroup.org/HDF5/doc/RM/RM_H5P.html#Property-GetMpioActualIoMode)
945 * and
946 * [H5Pget_mpio_no_collective_cause()](https://support.hdfgroup.org/HDF5/doc/RM/RM_H5P.html#Property-GetMpioNoCollectiveCause).
947 * The results are stored in io_mode, local_no_collective_cause and
948 * global_no_collective_cause.
949 */
950 bool query_io_mode;
951
952 /**
953 * I/O mode that was performed on the last parallel I/O call.
954 */
955 H5D_mpio_actual_io_mode_t io_mode;
956
957 /**
958 * Local causes that broke collective I/O on the
959 * last parallel I/O call. See <a
960 * href="https://support.hdfgroup.org/HDF5/doc/RM/RM_H5P.html#Property-GetMpioNoCollectiveCause">H5Pget_mpio_no_collective_cause</a>.
961 */
962 std::uint32_t local_no_collective_cause;
963
964 /**
965 * Global causes that broke collective I/O on the
966 * last parallel I/O call. See <a
967 * href="https://support.hdfgroup.org/HDF5/doc/RM/RM_H5P.html#Property-GetMpioNoCollectiveCause">H5Pget_mpio_no_collective_cause</a>.
968 */
969 std::uint32_t global_no_collective_cause;
970 };
971
972 /**
973 * This class implements an HDF5 Group
974 */
975 class Group : public HDF5Object
976 {
977 protected:
978 /**
979 * Group access mode
980 */
981 enum class GroupAccessMode
982 {
983 /**
984 * Opens an existing group
985 */
986 open,
987 /**
988 * Creates a new group
989 */
990 create
991 };
992 /**
993 * This constructor creates or opens a group depending on the value of
994 * @p mode. The group will be placed inside the group @p parent_group. The
995 * parameter @p mpi defines if the I/O operations are serial or
996 * parallel. This is an internal constructor, the functions open_group() and
997 * create_group() of the current class should be used to open or create a
998 * group.
999 */
1000 Group(const std::string &name,
1001 const Group &parent_group,
1002 const bool mpi,
1003 const GroupAccessMode mode);
1004
1005 /**
1006 * Internal constructor used by File. The constructor sets the protected
1007 * const members of HDF5Group: @p name and @p mpi. It does not create or
1008 * open a Group.
1009 */
1010 Group(const std::string &name, const bool mpi);
1011
1012 public:
1013 /**
1014 * Opens a sub-group of the current Group or File.
1015 */
1016 Group
1017 open_group(const std::string &name) const;
1018
1019 /**
1020 * Creates a sub-group in the current Group or File.
1021 */
1022 Group
1023 create_group(const std::string &name) const;
1024
1025 /**
1026 * Opens a dataset.
1027 */
1028 DataSet
1029 open_dataset(const std::string &name) const;
1030
1031 /**
1032 * Creates a dataset. @p number can be `float`, `double`,
1033 * `std::complex<float>`, `std::complex<double>`, `int` or `unsigned int`.
1034 *
1035 * Datatype conversion takes place at the time of a read or write and is
1036 * automatic. See the <a
1037 * href="https://support.hdfgroup.org/HDF5/doc/UG/HDF5_Users_Guide-Responsive%20HTML5/index.html#t=HDF5_Users_Guide%2FDatatypes%2FHDF5_Datatypes.htm%23TOC_6_10_Data_Transferbc-26&rhtocid=6.5_2">Data
1038 * Transfer: Datatype Conversion and Selection</a> section in the HDF5
1039 * User's Guide.
1040 */
1041 template <typename number>
1042 DataSet
1043 create_dataset(const std::string &name,
1044 const std::vector<hsize_t> &dimensions) const;
1045
1046 /**
1047 * Create and write data to a dataset. @p number can be `float`, `double`,
1048 * `std::complex<float>`, `std::complex<double>`, `int` or `unsigned int`.
1049 *
1050 * Datatype conversion takes place at the time of a read or write and is
1051 * automatic. See the <a
1052 * href="https://support.hdfgroup.org/HDF5/doc/UG/HDF5_Users_Guide-Responsive%20HTML5/index.html#t=HDF5_Users_Guide%2FDatatypes%2FHDF5_Datatypes.htm%23TOC_6_10_Data_Transferbc-26&rhtocid=6.5_2">Data
1053 * Transfer: Datatype Conversion and Selection</a> section in the HDF5
1054 * User's Guide.
1055 *
1056 * `Container` can be `std::vector<float>`, `std::vector<double>`,
1057 * `std::vector<std::complex<float>>`, `std::vector<std::complex<double>>`,
1058 * `std::vector<int>`, `std::vector<unsigned int>`, `Vector<float>`,
1059 * `Vector<double>`, `Vector<std::complex<float>>`,
1060 * `Vector<std::complex<double>>`, `FullMatrix<float>`,
1061 * `FullMatrix<double>`, `FullMatrix<std::complex<float>>` or
1062 * `FullMatrix<std::complex<double>>`.
1063 */
1064 template <typename Container>
1065 void
1066 write_dataset(const std::string &name, const Container &data) const;
1067 };
1068
1069 /**
1070 * This class implements an HDF5 File
1071 */
1072 class File : public Group
1073 {
1074 public:
1075 /**
1076 * File access mode
1077 */
1078 enum class FileAccessMode
1079 {
1080 /**
1081 * Read/write, file must exist
1082 */
1083 open,
1084 /**
1085 * Create file, truncate if exists
1086 */
1087 create
1088 };
1089
1090 /**
1091 * Creates or opens an HDF5 file for serial operations. This call does not
1092 * require MPI support. It creates or opens an HDF5 file depending on the
1093 * value of @p mode.
1094 */
1095 File(const std::string &name, const FileAccessMode mode);
1096
1097 /**
1098 * Creates or opens an HDF5 file in parallel using MPI. This requires that
1099 * deal.II and HDF5 were compiled with MPI support. It creates or opens a
1100 * HDF5 file depending on the value of @p mode. @p mpi_communicator
1101 * defines the processes that participate in this call; `MPI_COMM_WORLD` is
1102 * a common value for the MPI communicator.
1103 */
1104 File(const std::string &name,
1105 const FileAccessMode mode,
1106 const MPI_Comm mpi_communicator);
1107
1108 private:
1109 /**
1110 * Delegation internal constructor.
1111 * File(const std::string &, const MPI_Comm , const Mode);
1112 * and
1113 * File(const std::string &, const Mode)
1114 * should be used to open or create HDF5 files.
1115 */
1116 File(const std::string &name,
1117 const FileAccessMode mode,
1118 const bool mpi,
1119 const MPI_Comm mpi_communicator);
1120 };
1121
1122 namespace internal
1123 {
1124 /**
1125 * This function returns the HDF5 datatype corresponding to the C++ type.
1126 * In the case of std::complex types the HDF5 handlers are automatically
1127 * freed using the destructor of `std::shared_ptr`. `std::shared_ptr` is
1128 * used instead of `std::unique_ptr` because the destructor of
1129 * `std::shared_ptr` doesn't have to be defined in the template argument. In
1130 * the other hand, the destructor of `std::unique` has to be defined in the
1131 * template argument. Native types such as `H5T_NATIVE_DOUBLE` do not
1132 * require a destructor, but compound types such as std::complex<double>
1133 * require a destructor to free the HDF5 resources.
1134 */
1135 template <typename number>
1136 std::shared_ptr<hid_t>
1137 get_hdf5_datatype();
1138
1139 /**
1140 * Return the dimensions of `data`. For a std::vector this function returns
1141 * `std::vector<hsize_t>{vector_size}`.
1142 *
1143 * Several HDF5 functions such as H5Screate_simple() require a
1144 * one-dimensional array that specifies the size of each dimension of the
1145 * container, see:
1146 * https://support.hdfgroup.org/HDF5/doc1.8/RM/RM_H5S.html#Dataspace-CreateSimple
1147 */
1148 template <typename number>
1149 std::vector<hsize_t>
1150 get_container_dimensions(const std::vector<number> &data);
1151
1152 /**
1153 * Return the dimensions of `data`. For a Vector this function returns
1154 * `std::vector<hsize_t>{vector_size}`.
1155 */
1156 template <typename number>
1157 std::vector<hsize_t>
1158 get_container_dimensions(const Vector<number> &data);
1159
1160 /**
1161 * Return the dimensions of `data`. For a FullMatrix the function returns
1162 * `std::vector<hsize_t>{rows, columns}`.
1163 */
1164 template <typename number>
1165 std::vector<hsize_t>
1166 get_container_dimensions(const FullMatrix<number> &data);
1167
1168 /**
1169 * This function returns the total size of the container. For a std::vector
1170 * the function returns `int(vector_size)`.
1171 */
1172 template <typename number>
1173 unsigned int
1174 get_container_size(const std::vector<number> &data);
1175
1176 /**
1177 * This function returns the total size of the container. For a Vector the
1178 * function returns `int(vector_size)`.
1179 */
1180 template <typename number>
1181 unsigned int
1182 get_container_size(const Vector<number> &data);
1183
1184 /**
1185 * This function returns the total size of the container. For a FullMatrix
1186 * the function returns `int(rows*columns)`.
1187 */
1188 template <typename number>
1189 unsigned int
1190 get_container_size(const FullMatrix<number> &data);
1191
1192 /**
1193 * This function initializes and returns a container of type std::vector,
1194 * Vector or FullMatrix. The function does not set the values of the
1195 * elements of the container. The container can store data of a HDF5 dataset
1196 * or a HDF5 selection. The dimensions parameter holds the dimensions of the
1197 * HDF5 dataset or selection.
1198 *
1199 * In the case of a std::vector, the size of the vector will be the total
1200 * size given by dimensions. For example in the case of a dataset of rank 3,
1201 * the dimensions are `std::vector<hsize_t>{dim_0,dim_1,dim_2}`. The size of
1202 * the returned std::vector will be `dim_0*dim_1*dim_2`.
1203 *
1204 * In the case of a dealii::Vector, the size of the returned dealii::Vector
1205 * will be as well `dim_0*dim_1*dim_2`.
1206 *
1207 * A FullMatrix can store only data of HDF5 datasets with rank 2. The size
1208 * of the FullMatrix will be FullMatrix(dim_0,dim_2)
1209 */
1210 template <typename Container>
1211 std::enable_if_t<
1212 std::is_same_v<Container, std::vector<typename Container::value_type>>,
1213 Container>
1214 initialize_container(const std::vector<hsize_t> &dimensions);
1215
1216 /**
1217 * Same as above.
1218 */
1219 template <typename Container>
1220 std::enable_if_t<
1221 std::is_same_v<Container, Vector<typename Container::value_type>>,
1222 Container>
1223 initialize_container(const std::vector<hsize_t> &dimensions);
1224
1225 /**
1226 * Same as above.
1227 */
1228 template <typename Container>
1229 std::enable_if_t<
1230 std::is_same_v<Container, FullMatrix<typename Container::value_type>>,
1231 Container>
1232 initialize_container(const std::vector<hsize_t> &dimensions);
1233
1234 /**
1235 * This helper function sets the property list of the read and write
1236 * operations of DataSet. A property list has to be created for the MPI
1237 * driver. For the serial driver the default H5P_DEFAULT can be used. In
1238 * addition H5Pset_dxpl_mpio is used to set the MPI mode to collective.
1239 */
1240 inline void
1241 set_plist(hid_t &plist, const bool mpi);
1242
1243 /**
1244 * This helper function releases the property list handler of the read and
1245 * write operations of DataSet. For the serial version there is no need to
1246 * release the property list handler because H5P_DEFAULT has been used. If
1247 * query_io_mode is True then H5Pget_mpio_actual_io_mode and
1248 * H5Pget_mpio_no_collective_cause are used to check if the operation has
1249 * been collective.
1250 */
1251 inline void
1252 release_plist(hid_t &plist,
1253 H5D_mpio_actual_io_mode_t &io_mode,
1254 std::uint32_t &local_no_collective_cause,
1255 std::uint32_t &global_no_collective_cause,
1256 const bool mpi,
1257 const bool query_io_mode);
1258
1259 /**
1260 * Convert a HDF5 no_collective_cause code to a human readable string.
1261 */
1262 inline std::string
1263 no_collective_cause_to_string(const std::uint32_t no_collective_cause);
1264 } // namespace internal
1265
1266
1267
1268 // definitions
1269
1270 namespace internal
1271 {
1272 template <typename number>
1273 std::shared_ptr<hid_t>
1274 get_hdf5_datatype()
1275 {
1276 static_assert(std::is_same_v<number, float> ||
1277 std::is_same_v<number, double> ||
1278 std::is_same_v<number, int> ||
1279 std::is_same_v<number, bool> ||
1280 std::is_same_v<number, unsigned int> ||
1281 std::is_same_v<number, std::complex<float>> ||
1282 std::is_same_v<number, std::complex<double>>,
1283 "The data type you are trying to get the HDF5 tag for "
1284 "is not supported by this function.");
1285
1286 if (std::is_same_v<number, float>)
1287 {
1288 return std::make_shared<hid_t>(H5T_NATIVE_FLOAT);
1289 }
1290 else if (std::is_same_v<number, double>)
1291 {
1292 return std::make_shared<hid_t>(H5T_NATIVE_DOUBLE);
1293 }
1294 else if (std::is_same_v<number, int>)
1295 {
1296 return std::make_shared<hid_t>(H5T_NATIVE_INT);
1297 }
1298 else if (std::is_same_v<number, unsigned int>)
1299 {
1300 return std::make_shared<hid_t>(H5T_NATIVE_UINT);
1301 }
1302 else if (std::is_same_v<number, bool>)
1303 {
1304 return std::make_shared<hid_t>(H5T_NATIVE_HBOOL);
1305 }
1306 else if (std::is_same_v<number, std::complex<float>>)
1307 {
1308 std::shared_ptr<hid_t> t_type =
1309 std::shared_ptr<hid_t>(new hid_t, [](hid_t *pointer) {
1310 // Release the HDF5 resource
1311 const herr_t ret = H5Tclose(*pointer);
1312 AssertNothrow(ret >= 0, ExcInternalError());
1313 delete pointer;
1314 });
1315
1316 *t_type = H5Tcreate(H5T_COMPOUND, sizeof(std::complex<float>));
1317 // The C++ standards committee agreed to mandate that the storage
1318 // format used for the std::complex type be binary-compatible with
1319 // the C99 type, i.e. an array T[2] with consecutive real [0] and
1320 // imaginary [1] parts.
1321 herr_t ret = H5Tinsert(*t_type, "r", 0, H5T_NATIVE_FLOAT);
1322 Assert(ret >= 0, ExcInternalError());
1323 ret = H5Tinsert(*t_type, "i", sizeof(float), H5T_NATIVE_FLOAT);
1324 Assert(ret >= 0, ExcInternalError());
1325 (void)ret;
1326 return t_type;
1327 }
1328 else if (std::is_same_v<number, std::complex<double>>)
1329 {
1330 std::shared_ptr<hid_t> t_type =
1331 std::shared_ptr<hid_t>(new hid_t, [](hid_t *pointer) {
1332 // Release the HDF5 resource
1333 const herr_t ret = H5Tclose(*pointer);
1334 AssertNothrow(ret >= 0, ExcInternalError());
1335 delete pointer;
1336 });
1337 *t_type = H5Tcreate(H5T_COMPOUND, sizeof(std::complex<double>));
1338 // The C++ standards committee agreed to mandate that the storage
1339 // format used for the std::complex type be binary-compatible with
1340 // the C99 type, i.e. an array T[2] with consecutive real [0] and
1341 // imaginary [1] parts.
1342 herr_t ret = H5Tinsert(*t_type, "r", 0, H5T_NATIVE_DOUBLE);
1343 Assert(ret >= 0, ExcInternalError());
1344 ret = H5Tinsert(*t_type, "i", sizeof(double), H5T_NATIVE_DOUBLE);
1345 Assert(ret >= 0, ExcInternalError());
1346 (void)ret;
1347 return t_type;
1348 }
1349
1350 // The function should not reach this point
1351 DEAL_II_ASSERT_UNREACHABLE();
1352 return {};
1353 }
1354
1355
1356
1357 template <typename number>
1358 std::vector<hsize_t>
1359 get_container_dimensions(const std::vector<number> &data)
1360 {
1361 std::vector<hsize_t> dimensions = {data.size()};
1362 return dimensions;
1363 }
1364
1365
1366
1367 template <typename number>
1368 std::vector<hsize_t>
1369 get_container_dimensions(const Vector<number> &data)
1370 {
1371 std::vector<hsize_t> dimensions = {data.size()};
1372 return dimensions;
1373 }
1374
1375
1376
1377 template <typename number>
1378 std::vector<hsize_t>
1379 get_container_dimensions(const FullMatrix<number> &data)
1380 {
1381 std::vector<hsize_t> dimensions = {data.m(), data.n()};
1382 return dimensions;
1383 }
1384
1385
1386
1387 template <typename number>
1388 unsigned int
1389 get_container_size(const std::vector<number> &data)
1390 {
1391 return static_cast<unsigned int>(data.size());
1392 }
1393
1394
1395
1396 template <typename number>
1397 unsigned int
1398 get_container_size(const Vector<number> &data)
1399 {
1400 return static_cast<unsigned int>(data.size());
1401 }
1402
1403
1404
1405 template <typename number>
1406 unsigned int
1407 get_container_size(const FullMatrix<number> &data)
1408 {
1409 return static_cast<unsigned int>(data.m() * data.n());
1410 }
1411
1412
1413
1414 template <typename Container>
1415 std::enable_if_t<
1416 std::is_same_v<Container, std::vector<typename Container::value_type>>,
1417 Container>
1418 initialize_container(const std::vector<hsize_t> &dimensions)
1419 {
1420 return Container(std::accumulate(
1421 dimensions.begin(), dimensions.end(), 1, std::multiplies<int>()));
1422 }
1423
1424
1425
1426 template <typename Container>
1427 std::enable_if_t<
1428 std::is_same_v<Container, Vector<typename Container::value_type>>,
1429 Container>
1430 initialize_container(const std::vector<hsize_t> &dimensions)
1431 {
1432 return Container(std::accumulate(
1433 dimensions.begin(), dimensions.end(), 1, std::multiplies<int>()));
1434 }
1435
1436
1437
1438 template <typename Container>
1439 std::enable_if_t<
1440 std::is_same_v<Container, FullMatrix<typename Container::value_type>>,
1441 Container>
1442 initialize_container(const std::vector<hsize_t> &dimensions)
1443 {
1444 // If the rank is higher than 2, then remove single-dimensional entries
1445 // from the shape defined by dimensions. This is equivalent to the squeeze
1446 // function of python/numpy. For example the following code would convert
1447 // the vector {1,3,1,2} to {3,2}
1448 std::vector<hsize_t> squeezed_dimensions;
1449
1450 if (dimensions.size() > 2)
1451 {
1452 for (const auto &dimension : dimensions)
1453 {
1454 if (dimension > 1)
1455 squeezed_dimensions.push_back(dimension);
1456 }
1457 }
1458 else
1459 {
1460 squeezed_dimensions = dimensions;
1461 }
1462
1463 AssertDimension(squeezed_dimensions.size(), 2);
1464 return Container(squeezed_dimensions[0], squeezed_dimensions[1]);
1465 }
1466
1467
1468 inline void
1469 set_plist(hid_t &plist, const bool mpi)
1470 {
1471 if (mpi)
1472 {
1473 # ifdef DEAL_II_WITH_MPI
1474 plist = H5Pcreate(H5P_DATASET_XFER);
1475 Assert(plist >= 0, ExcInternalError());
1476 const herr_t ret = H5Pset_dxpl_mpio(plist, H5FD_MPIO_COLLECTIVE);
1477 (void)ret;
1478 Assert(ret >= 0, ExcInternalError());
1479 # else
1480 AssertThrow(false, ExcNotImplemented());
1481 # endif
1482 }
1483 else
1484 {
1485 plist = H5P_DEFAULT;
1486 }
1487
1488 (void)plist;
1489 (void)mpi;
1490 }
1491
1492
1493 inline void
1494 release_plist(hid_t &plist,
1495 H5D_mpio_actual_io_mode_t &io_mode,
1496 std::uint32_t &local_no_collective_cause,
1497 std::uint32_t &global_no_collective_cause,
1498 const bool mpi,
1499 const bool query_io_mode)
1500 {
1501 if (mpi)
1502 {
1503 # ifdef DEAL_II_WITH_MPI
1504 herr_t ret;
1505 (void)ret;
1506 if (query_io_mode)
1507 {
1508 ret = H5Pget_mpio_actual_io_mode(plist, &io_mode);
1509 Assert(ret >= 0, ExcInternalError());
1510 ret =
1511 H5Pget_mpio_no_collective_cause(plist,
1512 &local_no_collective_cause,
1513 &global_no_collective_cause);
1514 Assert(ret >= 0, ExcInternalError());
1515 }
1516 ret = H5Pclose(plist);
1517 Assert(ret >= 0, ExcInternalError());
1518 # else
1519 AssertThrow(false, ExcNotImplemented());
1520 # endif
1521 }
1522
1523 (void)plist;
1524 (void)io_mode;
1525 (void)local_no_collective_cause;
1526 (void)global_no_collective_cause;
1527 (void)mpi;
1528 (void)query_io_mode;
1529 }
1530
1531
1532 inline std::string
1533 no_collective_cause_to_string(const std::uint32_t no_collective_cause)
1534 {
1535 std::string message;
1536
1537 auto append_to_message = [&message](const char *p) {
1538 if (message.size() > 0)
1539 message += ", ";
1540 message += p;
1541 };
1542
1543 // The first is not a bitmask comparison, the rest are bitmask
1544 // comparisons.
1545 // https://support.hdfgroup.org/HDF5/doc/RM/RM_H5P.html#Property-GetMpioNoCollectiveCause
1546 // See H5Ppublic.h
1547 // Hex codes are used because the HDF5 Group can deprecate some of the
1548 // enum codes. For example the enum code H5D_MPIO_FILTERS is not defined
1549 // in 1.10.2 because it is possible to use compressed datasets with the
1550 // MPI/IO driver.
1551
1552 // H5D_MPIO_COLLECTIVE
1553 if (no_collective_cause == 0x00)
1554 {
1555 append_to_message("H5D_MPIO_COLLECTIVE");
1556 }
1557 // H5D_MPIO_SET_INDEPENDENT
1558 if ((no_collective_cause & 0x01) == 0x01)
1559 {
1560 append_to_message("H5D_MPIO_SET_INDEPENDENT");
1561 }
1562 // H5D_MPIO_DATATYPE_CONVERSION
1563 if ((no_collective_cause & 0x02) == 0x02)
1564 {
1565 append_to_message("H5D_MPIO_DATATYPE_CONVERSION");
1566 }
1567 // H5D_MPIO_DATA_TRANSFORMS
1568 if ((no_collective_cause & 0x04) == 0x04)
1569 {
1570 append_to_message("H5D_MPIO_DATA_TRANSFORMS");
1571 }
1572 // H5D_MPIO_NOT_SIMPLE_OR_SCALAR_DATASPACES
1573 if ((no_collective_cause & 0x10) == 0x10)
1574 {
1575 append_to_message("H5D_MPIO_NOT_SIMPLE_OR_SCALAR_DATASPACES");
1576 }
1577 // H5D_MPIO_NOT_CONTIGUOUS_OR_CHUNKED_DATASET
1578 if ((no_collective_cause & 0x20) == 0x20)
1579 {
1580 append_to_message("H5D_MPIO_NOT_CONTIGUOUS_OR_CHUNKED_DATASET");
1581 }
1582 // H5D_MPIO_FILTERS
1583 if ((no_collective_cause & 0x40) == 0x40)
1584 {
1585 append_to_message("H5D_MPIO_FILTERS");
1586 }
1587 return message;
1588 }
1589 } // namespace internal
1590
1591
1592 template <typename T>
1593 T
1594 HDF5Object::get_attribute(const std::string &attr_name) const
1595 {
1596 const std::shared_ptr<hid_t> t_type = internal::get_hdf5_datatype<T>();
1597 T value;
1598 hid_t attr;
1599 herr_t ret;
1600
1601 attr = H5Aopen(*hdf5_reference, attr_name.data(), H5P_DEFAULT);
1602 Assert(attr >= 0, ExcMessage("Error at H5Aopen"));
1603 (void)ret;
1604 ret = H5Aread(attr, *t_type, &value);
1605 Assert(ret >= 0, ExcMessage("Error at H5Aread"));
1606 (void)ret;
1607 ret = H5Aclose(attr);
1608 Assert(ret >= 0, ExcMessage("Error at H5Aclose"));
1609
1610 return value;
1611 }
1612
1613
1614
1615 template <>
1616 inline std::string
1617 HDF5Object::get_attribute(const std::string &attr_name) const
1618 {
1619 // Reads a UTF8 variable string
1620 //
1621 // code inspired from
1622 // https://support.hdfgroup.org/ftp/HDF5/examples/misc-examples/vlstratt.c
1623 //
1624 // In the case of a variable length string the user does not have to reserve
1625 // memory for string_out. H5Aread will reserve the memory and the
1626 // user has to free the memory.
1627 //
1628 // Todo:
1629 // - Use H5Dvlen_reclaim instead of free
1630
1631 char *string_out;
1632 hid_t attr;
1633 hid_t type;
1634 herr_t ret;
1635
1636 /* Create a datatype to refer to. */
1637 type = H5Tcopy(H5T_C_S1);
1638 Assert(type >= 0, ExcInternalError());
1639
1640 // Python strings are encoded in UTF8
1641 ret = H5Tset_cset(type, H5T_CSET_UTF8);
1642 Assert(type >= 0, ExcInternalError());
1643
1644 ret = H5Tset_size(type, H5T_VARIABLE);
1645 Assert(ret >= 0, ExcInternalError());
1646
1647 attr = H5Aopen(*hdf5_reference, attr_name.data(), H5P_DEFAULT);
1648 Assert(attr >= 0, ExcInternalError());
1649
1650 ret = H5Aread(attr, type, &string_out);
1651 Assert(ret >= 0, ExcInternalError());
1652
1653 std::string string_value(string_out);
1654 // The memory of the variable length string has to be freed.
1655 // H5Dvlen_reclaim could be also used
1656 std::free(string_out);
1657 ret = H5Tclose(type);
1658 Assert(ret >= 0, ExcInternalError());
1659
1660 ret = H5Aclose(attr);
1661 Assert(ret >= 0, ExcInternalError());
1662
1663 (void)ret;
1664 return string_value;
1665 }
1666
1667
1668
1669 template <typename T>
1670 void
1671 HDF5Object::set_attribute(const std::string &attr_name, const T value)
1672 {
1673 hid_t attr;
1674 hid_t aid;
1675 herr_t ret;
1676
1677 const std::shared_ptr<hid_t> t_type = internal::get_hdf5_datatype<T>();
1678
1679
1680 /*
1681 * Create scalar attribute.
1682 */
1683 aid = H5Screate(H5S_SCALAR);
1684 Assert(aid >= 0, ExcMessage("Error at H5Screate"));
1685 attr = H5Acreate2(*hdf5_reference,
1686 attr_name.data(),
1687 *t_type,
1688 aid,
1689 H5P_DEFAULT,
1690 H5P_DEFAULT);
1691 Assert(attr >= 0, ExcMessage("Error at H5Acreate2"));
1692
1693 /*
1694 * Write scalar attribute.
1695 */
1696 ret = H5Awrite(attr, *t_type, &value);
1697 Assert(ret >= 0, ExcMessage("Error at H5Awrite"));
1698
1699 ret = H5Sclose(aid);
1700 Assert(ret >= 0, ExcMessage("Error at H5Sclose"));
1701 ret = H5Aclose(attr);
1702 Assert(ret >= 0, ExcMessage("Error at H5Aclose"));
1703
1704 (void)ret;
1705 }
1706
1707
1708
1709 template <>
1710 inline void
1711 HDF5Object::set_attribute(const std::string &attr_name,
1712 const std::string value) // NOLINT
1713 {
1714 // Writes a UTF8 variable string
1715 //
1716 // code inspired from
1717 // https://support.hdfgroup.org/ftp/HDF5/examples/misc-examples/vlstratt.c
1718
1719 hid_t attr;
1720 hid_t aid;
1721 hid_t t_type;
1722 herr_t ret;
1723
1724 /* Create a datatype to refer to. */
1725 t_type = H5Tcopy(H5T_C_S1);
1726 Assert(t_type >= 0, ExcInternalError());
1727
1728 // Python strings are encoded in UTF8
1729 ret = H5Tset_cset(t_type, H5T_CSET_UTF8);
1730 Assert(t_type >= 0, ExcInternalError());
1731
1732 ret = H5Tset_size(t_type, H5T_VARIABLE);
1733 Assert(ret >= 0, ExcInternalError());
1734
1735 /*
1736 * Create scalar attribute.
1737 */
1738 aid = H5Screate(H5S_SCALAR);
1739 Assert(aid >= 0, ExcMessage("Error at H5Screate"));
1740 attr = H5Acreate2(
1741 *hdf5_reference, attr_name.data(), t_type, aid, H5P_DEFAULT, H5P_DEFAULT);
1742 Assert(attr >= 0, ExcMessage("Error at H5Acreate2"));
1743
1744 /*
1745 * Write scalar attribute.
1746 * In most of the cases H5Awrite and H5Dwrite take a pointer to the data.
1747 * But in the particular case of a variable length string, H5Awrite takes
1748 * the address of the pointer of the string.
1749 */
1750 const char *c_string_value = value.c_str();
1751 ret = H5Awrite(attr, t_type, &c_string_value);
1752 Assert(ret >= 0, ExcInternalError());
1753
1754 ret = H5Sclose(aid);
1755 Assert(ret >= 0, ExcMessage("Error at H5Sclose"));
1756 ret = H5Aclose(attr);
1757 Assert(ret >= 0, ExcMessage("Error at H5Aclose"));
1758
1759 (void)ret;
1760 }
1761
1762
1763
1764 template <typename Container>
1765 Container
1766 DataSet::read()
1767 {
1768 const std::shared_ptr<hid_t> t_type =
1769 internal::get_hdf5_datatype<typename Container::value_type>();
1770 hid_t plist;
1771 herr_t ret;
1772
1773 Container data = internal::initialize_container<Container>(dimensions);
1774
1775 internal::set_plist(plist, mpi);
1776
1777 ret = H5Dread(*hdf5_reference,
1778 *t_type,
1779 H5S_ALL,
1780 H5S_ALL,
1781 plist,
1782 make_array_view(data).data());
1783 Assert(ret >= 0, ExcInternalError());
1784
1785
1786 internal::release_plist(plist,
1787 io_mode,
1788 local_no_collective_cause,
1789 global_no_collective_cause,
1790 mpi,
1791 query_io_mode);
1792
1793 (void)ret;
1794 return data;
1795 }
1796
1797
1798
1799 template <typename Container>
1800 Container
1801 DataSet::read_selection(const std::vector<hsize_t> &coordinates)
1802 {
1803 Assert(coordinates.size() % rank == 0,
1804 ExcMessage(
1805 "The dimension of coordinates has to be divisible by the rank"));
1806 const std::shared_ptr<hid_t> t_type =
1807 internal::get_hdf5_datatype<typename Container::value_type>();
1808 hid_t plist;
1809 hid_t memory_dataspace;
1810 herr_t ret;
1811
1812 std::vector<hsize_t> data_dimensions{
1813 static_cast<hsize_t>(coordinates.size() / rank)};
1814
1815 Container data = internal::initialize_container<Container>(data_dimensions);
1816
1817 memory_dataspace = H5Screate_simple(1, data_dimensions.data(), nullptr);
1818 Assert(memory_dataspace >= 0, ExcMessage("Error at H5Screate_simple"));
1819 ret = H5Sselect_elements(*dataspace,
1820 H5S_SELECT_SET,
1821 data.size(),
1822 coordinates.data());
1823 Assert(ret >= 0, ExcMessage("Error at H5Sselect_elements"));
1824
1825 internal::set_plist(plist, mpi);
1826
1827 ret = H5Dread(*hdf5_reference,
1828 *t_type,
1829 memory_dataspace,
1830 *dataspace,
1831 plist,
1832 make_array_view(data).data());
1833 Assert(ret >= 0, ExcMessage("Error at H5Dread"));
1834
1835 internal::release_plist(plist,
1836 io_mode,
1837 local_no_collective_cause,
1838 global_no_collective_cause,
1839 mpi,
1840 query_io_mode);
1841
1842 ret = H5Sclose(memory_dataspace);
1843 Assert(ret >= 0, ExcMessage("Error at H5SClose"));
1844
1845 (void)ret;
1846 return data;
1847 }
1848
1849
1850
1851 template <typename Container>
1852 Container
1853 DataSet::read_hyperslab(const std::vector<hsize_t> &offset,
1854 const std::vector<hsize_t> &count)
1855 {
1856 const std::shared_ptr<hid_t> t_type =
1857 internal::get_hdf5_datatype<typename Container::value_type>();
1858 hid_t plist;
1859 hid_t memory_dataspace;
1860 herr_t ret;
1861
1862 // In this particular overload of read_hyperslab the data_dimensions are
1863 // the same as count
1864 std::vector<hsize_t> data_dimensions = count;
1865
1866 Container data = internal::initialize_container<Container>(data_dimensions);
1867
1868 memory_dataspace =
1869 H5Screate_simple(data_dimensions.size(), data_dimensions.data(), nullptr);
1870 Assert(memory_dataspace >= 0, ExcMessage("Error at H5Screate_simple"));
1871 ret = H5Sselect_hyperslab(*dataspace,
1872 H5S_SELECT_SET,
1873 offset.data(),
1874 nullptr,
1875 count.data(),
1876 nullptr);
1877 Assert(ret >= 0, ExcMessage("Error at H5Sselect_hyperslab"));
1878
1879 internal::set_plist(plist, mpi);
1880
1881 ret = H5Dread(*hdf5_reference,
1882 *t_type,
1883 memory_dataspace,
1884 *dataspace,
1885 plist,
1886 make_array_view(data).data());
1887 Assert(ret >= 0, ExcMessage("Error at H5Dread"));
1888
1889 internal::release_plist(plist,
1890 io_mode,
1891 local_no_collective_cause,
1892 global_no_collective_cause,
1893 mpi,
1894 query_io_mode);
1895
1896 ret = H5Sclose(memory_dataspace);
1897 Assert(ret >= 0, ExcMessage("Error at H5SClose"));
1898
1899 (void)ret;
1900 return data;
1901 }
1902
1903
1904
1905 template <typename Container>
1906 Container
1907 DataSet::read_hyperslab(const std::vector<hsize_t> &data_dimensions,
1908 const std::vector<hsize_t> &offset,
1909 const std::vector<hsize_t> &stride,
1910 const std::vector<hsize_t> &count,
1911 const std::vector<hsize_t> &block)
1912 {
1913 const std::shared_ptr<hid_t> t_type =
1914 internal::get_hdf5_datatype<typename Container::value_type>();
1915 hid_t plist;
1916 hid_t memory_dataspace;
1917 herr_t ret;
1918
1919 Container data = internal::initialize_container<Container>(data_dimensions);
1920
1921 memory_dataspace =
1922 H5Screate_simple(data_dimensions.size(), data_dimensions.data(), nullptr);
1923 Assert(memory_dataspace >= 0, ExcMessage("Error at H5Screate_simple"));
1924 ret = H5Sselect_hyperslab(*dataspace,
1925 H5S_SELECT_SET,
1926 offset.data(),
1927 stride.data(),
1928 count.data(),
1929 block.data());
1930 Assert(ret >= 0, ExcMessage("Error at H5Sselect_hyperslab"));
1931
1932 internal::set_plist(plist, mpi);
1933
1934 ret = H5Dread(*hdf5_reference,
1935 *t_type,
1936 memory_dataspace,
1937 *dataspace,
1938 plist,
1939 make_array_view(data).data());
1940 Assert(ret >= 0, ExcMessage("Error at H5Dread"));
1941
1942 internal::release_plist(plist,
1943 io_mode,
1944 local_no_collective_cause,
1945 global_no_collective_cause,
1946 mpi,
1947 query_io_mode);
1948
1949 ret = H5Sclose(memory_dataspace);
1950 Assert(ret >= 0, ExcMessage("Error at H5SClose"));
1951
1952 (void)ret;
1953 return data;
1954 }
1955
1956
1957
1958 template <typename number>
1959 void
1960 DataSet::read_none()
1961 {
1962 const std::shared_ptr<hid_t> t_type = internal::get_hdf5_datatype<number>();
1963 const std::vector<hsize_t> data_dimensions = {0};
1964
1965 hid_t memory_dataspace;
1966 hid_t plist;
1967 herr_t ret;
1968
1969 memory_dataspace = H5Screate_simple(1, data_dimensions.data(), nullptr);
1970 Assert(memory_dataspace >= 0, ExcMessage("Error at H5Screate_simple"));
1971 ret = H5Sselect_none(*dataspace);
1972 Assert(ret >= 0, ExcMessage("H5Sselect_none"));
1973
1974 internal::set_plist(plist, mpi);
1975
1976 // The pointer of data can safely be nullptr, see the discussion at the HDF5
1977 // forum:
1978 // https://forum.hdfgroup.org/t/parallel-i-o-does-not-support-filters-yet/884/17
1979 ret = H5Dread(
1980 *hdf5_reference, *t_type, memory_dataspace, *dataspace, plist, nullptr);
1981 Assert(ret >= 0, ExcMessage("Error at H5Dread"));
1982
1983 internal::release_plist(plist,
1984 io_mode,
1985 local_no_collective_cause,
1986 global_no_collective_cause,
1987 mpi,
1988 query_io_mode);
1989
1990 ret = H5Sclose(memory_dataspace);
1991 Assert(ret >= 0, ExcMessage("Error at H5SClose"));
1992
1993 (void)ret;
1994 }
1995
1996
1997
1998 template <typename Container>
1999 void
2000 DataSet::write(const Container &data)
2001 {
2002 AssertDimension(size, internal::get_container_size(data));
2003 const std::shared_ptr<hid_t> t_type =
2004 internal::get_hdf5_datatype<typename Container::value_type>();
2005 hid_t plist;
2006 herr_t ret;
2007
2008 internal::set_plist(plist, mpi);
2009
2010 ret = H5Dwrite(*hdf5_reference,
2011 *t_type,
2012 H5S_ALL,
2013 H5S_ALL,
2014 plist,
2015 make_array_view(data).data());
2016 Assert(ret >= 0, ExcMessage("Error at H5Dwrite"));
2017
2018 internal::release_plist(plist,
2019 io_mode,
2020 local_no_collective_cause,
2021 global_no_collective_cause,
2022 mpi,
2023 query_io_mode);
2024
2025 (void)ret;
2026 }
2027
2028
2029
2030 template <typename Container>
2031 void
2032 DataSet::write_selection(const Container &data,
2033 const std::vector<hsize_t> &coordinates)
2034 {
2035 AssertDimension(coordinates.size(), data.size() * rank);
2036 const std::shared_ptr<hid_t> t_type =
2037 internal::get_hdf5_datatype<typename Container::value_type>();
2038 const std::vector<hsize_t> data_dimensions =
2039 internal::get_container_dimensions(data);
2040
2041 hid_t memory_dataspace;
2042 hid_t plist;
2043 herr_t ret;
2044
2045
2046 memory_dataspace = H5Screate_simple(1, data_dimensions.data(), nullptr);
2047 Assert(memory_dataspace >= 0, ExcMessage("Error at H5Screate_simple"));
2048 ret = H5Sselect_elements(*dataspace,
2049 H5S_SELECT_SET,
2050 data.size(),
2051 coordinates.data());
2052 Assert(ret >= 0, ExcMessage("Error at H5Sselect_elements"));
2053
2054 internal::set_plist(plist, mpi);
2055
2056 ret = H5Dwrite(*hdf5_reference,
2057 *t_type,
2058 memory_dataspace,
2059 *dataspace,
2060 plist,
2061 make_array_view(data).data());
2062 Assert(ret >= 0, ExcMessage("Error at H5Dwrite"));
2063
2064 internal::release_plist(plist,
2065 io_mode,
2066 local_no_collective_cause,
2067 global_no_collective_cause,
2068 mpi,
2069 query_io_mode);
2070
2071 ret = H5Sclose(memory_dataspace);
2072 Assert(ret >= 0, ExcMessage("Error at H5SClose"));
2073
2074 (void)ret;
2075 }
2076
2077
2078
2079 template <typename Container>
2080 void
2081 DataSet::write_hyperslab(const Container &data,
2082 const std::vector<hsize_t> &offset,
2083 const std::vector<hsize_t> &count)
2084 {
2085 AssertDimension(std::accumulate(count.begin(),
2086 count.end(),
2087 1,
2088 std::multiplies<unsigned int>()),
2089 internal::get_container_size(data));
2090 const std::shared_ptr<hid_t> t_type =
2091 internal::get_hdf5_datatype<typename Container::value_type>();
2092 // In this particular overload of write_hyperslab the data_dimensions are
2093 // the same as count
2094 const std::vector<hsize_t> &data_dimensions = count;
2095
2096 hid_t memory_dataspace;
2097 hid_t plist;
2098 herr_t ret;
2099
2100 memory_dataspace =
2101 H5Screate_simple(data_dimensions.size(), data_dimensions.data(), nullptr);
2102 Assert(memory_dataspace >= 0, ExcMessage("Error at H5Screate_simple"));
2103 ret = H5Sselect_hyperslab(*dataspace,
2104 H5S_SELECT_SET,
2105 offset.data(),
2106 nullptr,
2107 count.data(),
2108 nullptr);
2109 Assert(ret >= 0, ExcMessage("Error at H5Sselect_hyperslab"));
2110
2111 internal::set_plist(plist, mpi);
2112
2113 ret = H5Dwrite(*hdf5_reference,
2114 *t_type,
2115 memory_dataspace,
2116 *dataspace,
2117 plist,
2118 make_array_view(data).data());
2119 Assert(ret >= 0, ExcMessage("Error at H5Dwrite"));
2120
2121 internal::release_plist(plist,
2122 io_mode,
2123 local_no_collective_cause,
2124 global_no_collective_cause,
2125 mpi,
2126 query_io_mode);
2127
2128 ret = H5Sclose(memory_dataspace);
2129 Assert(ret >= 0, ExcMessage("Error at H5Sclose"));
2130
2131 (void)ret;
2132 }
2133
2134
2135
2136 template <typename Container>
2137 void
2138 DataSet::write_hyperslab(const Container &data,
2139 const std::vector<hsize_t> &data_dimensions,
2140 const std::vector<hsize_t> &offset,
2141 const std::vector<hsize_t> &stride,
2142 const std::vector<hsize_t> &count,
2143 const std::vector<hsize_t> &block)
2144 {
2145 const std::shared_ptr<hid_t> t_type =
2146 internal::get_hdf5_datatype<typename Container::value_type>();
2147
2148 hid_t memory_dataspace;
2149 hid_t plist;
2150 herr_t ret;
2151
2152 memory_dataspace =
2153 H5Screate_simple(data_dimensions.size(), data_dimensions.data(), nullptr);
2154 Assert(memory_dataspace >= 0, ExcMessage("Error at H5Screate_simple"));
2155 ret = H5Sselect_hyperslab(*dataspace,
2156 H5S_SELECT_SET,
2157 offset.data(),
2158 stride.data(),
2159 count.data(),
2160 block.data());
2161 Assert(ret >= 0, ExcMessage("Error at H5Sselect_hyperslab"));
2162
2163 internal::set_plist(plist, mpi);
2164
2165 ret = H5Dwrite(*hdf5_reference,
2166 *t_type,
2167 memory_dataspace,
2168 *dataspace,
2169 plist,
2170 make_array_view(data).data());
2171 Assert(ret >= 0, ExcMessage("Error at H5Dwrite"));
2172
2173 internal::release_plist(plist,
2174 io_mode,
2175 local_no_collective_cause,
2176 global_no_collective_cause,
2177 mpi,
2178 query_io_mode);
2179
2180 ret = H5Sclose(memory_dataspace);
2181 Assert(ret >= 0, ExcMessage("Error at H5Sclose"));
2182
2183 (void)ret;
2184 }
2185
2186
2187
2188 template <typename number>
2189 void
2190 DataSet::write_none()
2191 {
2192 std::shared_ptr<hid_t> t_type = internal::get_hdf5_datatype<number>();
2193 std::vector<hsize_t> data_dimensions = {0};
2194
2195 hid_t memory_dataspace;
2196 hid_t plist;
2197 herr_t ret;
2198
2199 memory_dataspace = H5Screate_simple(1, data_dimensions.data(), nullptr);
2200 Assert(memory_dataspace >= 0, ExcMessage("Error at H5Screate_simple"));
2201 ret = H5Sselect_none(*dataspace);
2202 Assert(ret >= 0, ExcMessage("Error at H5PSselect_none"));
2203
2204 internal::set_plist(plist, mpi);
2205
2206 // The pointer of data can safely be nullptr, see the discussion at the HDF5
2207 // forum:
2208 // https://forum.hdfgroup.org/t/parallel-i-o-does-not-support-filters-yet/884/17
2209 ret = H5Dwrite(
2210 *hdf5_reference, *t_type, memory_dataspace, *dataspace, plist, nullptr);
2211 Assert(ret >= 0, ExcMessage("Error at H5Dwrite"));
2212
2213 internal::release_plist(plist,
2214 io_mode,
2215 local_no_collective_cause,
2216 global_no_collective_cause,
2217 mpi,
2218 query_io_mode);
2219
2220 ret = H5Sclose(memory_dataspace);
2221 Assert(ret >= 0, ExcMessage("Error at H5Sclose"));
2222
2223 (void)ret;
2224 }
2225
2226
2227
2228 template <typename number>
2229 DataSet
2230 Group::create_dataset(const std::string &name,
2231 const std::vector<hsize_t> &dimensions) const
2232 {
2233 std::shared_ptr<hid_t> t_type = internal::get_hdf5_datatype<number>();
2234 return {name, *hdf5_reference, dimensions, t_type, mpi};
2235 }
2236
2237
2238
2239 template <typename Container>
2240 void
2241 Group::write_dataset(const std::string &name, const Container &data) const
2242 {
2243 std::vector<hsize_t> dimensions = internal::get_container_dimensions(data);
2244 auto dataset =
2245 create_dataset<typename Container::value_type>(name, dimensions);
2246 dataset.write(data);
2247 }
2248 } // namespace HDF5
2249
2250 DEAL_II_NAMESPACE_CLOSE
2251
2252
2253 #else
2254
2255 // Make sure the scripts that create the C++20 module input files have
2256 // something to latch on if the preprocessor #ifdef above would
2257 // otherwise lead to an empty content of the file.
2258 DEAL_II_NAMESPACE_OPEN
2259 DEAL_II_NAMESPACE_CLOSE
2260
2261 #endif // DEAL_II_WITH_HDF5
2262
2263 #endif // dealii_hdf5_h