HDF5 support

Detailed Description

HDF5 support for nda::basic_array and nda::basic_array_view objects.

nda uses the TRIQS/h5 library to provide functions to write (nda::h5_write) and read (nda::h5_read) arrays and views to and from HDF5 files.

The following example demonstrates some of these features:

#include <nda/h5.hpp>
#include <nda/nda.hpp>
 
#include <h5/h5.hpp>
 
int main(int argc, char **argv) {
  // create a 4x2 array with random values
  auto A = nda::rand(4, 2);
 
  // write the array to an HDF5 file
  h5::file file("A.h5", 'w');
  h5::write(file, "A", A);
}

Dumping the content of "A.h5":

HDF5 "A.h5" {
GROUP "/" {
   DATASET "A" {
      DATATYPE  H5T_IEEE_F64LE
      DATASPACE  SIMPLE { ( 4, 2 ) / ( 4, 2 ) }
      DATA {
      (0,0): 0.956845, 0.201094,
      (1,0): 0.995133, 0.29042,
      (2,0): 0.729235, 0.0153893,
      (3,0): 0.96194, 0.481198
      }
   }
}
}

Functions
template<MemoryArray A, typename... IRs>
void	nda::h5_read (h5::group g, std::string const &name, A &a, std::tuple< IRs... > const &slice={})
	Read into an nda::MemoryArray from an HDF5 file.
template<MemoryArray A>
void	nda::h5_write (h5::group g, std::string const &name, A const &a, bool compress=true)
	Write an nda::MemoryArray to a new dataset/subgroup into an HDF5 file.
template<MemoryArray A, typename... IRs>
void	nda::h5_write (h5::group g, std::string const &name, A const &a, std::tuple< IRs... > const &slice)
	Write an nda::MemoryArray into a slice (hyperslab) of an existing dataset in an HDF5 file.
template<size_t NDim, typename... IRs>
auto	nda::hyperslab_and_shape_from_slice (std::tuple< IRs... > const &slice, std::vector< h5::hsize_t > const &ds_shape, bool is_complex)
	Construct an h5::array_interface::hyperslab and the corresponding shape from a given slice, i.e. a tuple containing integer, nda::range, nda::range::all_t and nda::ellipsis objects.

Function Documentation

h5_read()

template<MemoryArray A, typename... IRs>

void nda::h5_read	(	h5::group	g,
		std::string const &	name,
		A &	a,
		std::tuple< IRs... > const &	slice = {} )

#include <nda/h5.hpp>

Read into an nda::MemoryArray from an HDF5 file.

The following arrays/views are supported:

• 1-dimensional arrays/views of strings: The data is read into an h5::char_buf and then copied into the array/view.
• arbitrary arrays/views of scalars: The data is read directly from an h5::dataset into the array/view. If the stride order is not C-order, the data is first read into an array with C-order layout, before it is copied into the array/view. The data to be read from the dataset can be restricted by providing a slice.
• arbitrary arrays/views of some generic type: The elements are read one-by-one from the subgroup.

Note

While array objects will always be resized to fit the shape of the data read from the file, views must have the same shape as the data to be read. If this is not the case, an exception is thrown.

Template Parameters

A	nda::MemoryArray type.
IRs	Types in the slice, i.e. integer, nda::range, nda::range::all_t or nda::ellipsis.

Parameters

g	h5::group which contains the dataset/subgroup to read from.
name	Name of the dataset/subgroup.
a	nda::MemoryArray object to be read into.
slice	Optional tuple specifying the slice of the dataset to be read.

Definition at line 308 of file h5.hpp.

h5_write() [1/2]

template<MemoryArray A>

void nda::h5_write	(	h5::group	g,
		std::string const &	name,
		A const &	a,
		bool	compress = true )

#include <nda/h5.hpp>

Write an nda::MemoryArray to a new dataset/subgroup into an HDF5 file.

The following arrays/views can be written to HDF5:

• 1-dimensional array/view of strings: It is first converted to an h5::char_buf before it is written.
• arbitrary array/view of scalars: The data is written directly into an h5::dataset with the same shape. If the stride order is not C-order, the elements of the array/view are first copied into an array with C-order layout.
• arbitrary array/view of some generic type: The elements are written one-by-one into a subgroup.

Template Parameters

A	nda::MemoryArray type.

Parameters

g	h5::group in which the dataset/subgroup is created.
name	Name of the dataset/subgroup to which the nda::MemoryArray is written.
a	nda::MemoryArray to be written.
compress	Whether to compress the dataset.

Definition at line 130 of file h5.hpp.

h5_write() [2/2]

template<MemoryArray A, typename... IRs>

void nda::h5_write	(	h5::group	g,
		std::string const &	name,
		A const &	a,
		std::tuple< IRs... > const &	slice )

#include <nda/h5.hpp>

Write an nda::MemoryArray into a slice (hyperslab) of an existing dataset in an HDF5 file.

The hyperslab in the dataset is specified by providing a tuple of integer, nda::range, nda::range::all_t or nda::ellipsis objects. It's shape must match the shape of the nda::MemoryArray to be written, otherwise an exception is thrown.

Only arrays/views with scalar types can be written to a slice.

Template Parameters

A	nda::MemoryArray type.
IRs	Types in the slice, i.e. integer, nda::range, nda::range::all_t or nda::ellipsis.

Parameters

g	h5::group which contains the dataset.
name	Name of the dataset.
a	nda::MemoryArray to be written.
slice	Tuple specifying the slice of the dataset to which the nda::MemoryArray is written.

Definition at line 256 of file h5.hpp.

hyperslab_and_shape_from_slice()

template<size_t NDim, typename... IRs>

auto nda::hyperslab_and_shape_from_slice	(	std::tuple< IRs... > const &	slice,
		std::vector< h5::hsize_t > const &	ds_shape,
		bool	is_complex )

#include <nda/h5.hpp>

Construct an h5::array_interface::hyperslab and the corresponding shape from a given slice, i.e. a tuple containing integer, nda::range, nda::range::all_t and nda::ellipsis objects.

The hyperslab will have the same number of dimensions as the underlying dataspace, whereas the shape will only contain the selected dimensions. For example, a 1-dimensional slice of a 3-dimensional dataset will return a hyperslab with 3 dimensions and a shape with 1 dimension.

Template Parameters

NDim	Number of selected dimensions (== Rank of the array/view to be written/read into).
IRs	Types in the slice, i.e. integer, nda::range, nda::range::all_t or nda::ellipsis.

Parameters

slice	Tuple specifying the slice of the dataset to which the nda::MemoryArray is written.
ds_shape	Shape of the underlying dataset.
is_complex	Whether the data is complex valued.

Returns

A pair containing the hyperslab and the shape of the selected slice.

Definition at line 173 of file h5.hpp.