Home

Awesome

Note: In preparation of v3 of HighFive, we've started merging breaking changes into the main branch. More information and opportunity to comment can be found at: https://github.com/BlueBrain/HighFive/issues/864

HighFive - HDF5 header-only C++ Library

Doxygen -> gh-pages codecov HighFive_Integration_tests Zenodo

Documentation: https://bluebrain.github.io/HighFive/

Brief

HighFive is a modern header-only C++14 friendly interface for libhdf5.

HighFive supports STL vector/string, Boost::UBLAS, Boost::Multi-array and Xtensor. It handles C++ from/to HDF5 with automatic type mapping. HighFive does not require additional libraries (see dependencies).

It integrates nicely with other CMake projects by defining (and exporting) a HighFive target.

Design

Feature support

Dependencies

Versioning & Code Stability

We use semantic versioning. Currently, we're preparing v3 which contains a limited set of breaking changes required to eliminate undesireable behaviour or modernize outdated patterns. We provide a Migration Guide, please report any missing or incorrect information to help others make the switch more easily.

Known flaws

Examples

Write a std::vector<int> to 1D HDF5 dataset and read it back

#include <highfive/highfive.hpp>

using namespace HighFive;

std::string filename = "/tmp/new_file.h5";

{
    // We create an empty HDF55 file, by truncating an existing
    // file if required:
    File file(filename, File::Truncate);

    std::vector<int> data(50, 1);
    file.createDataSet("grp/data", data);
}

{
    // We open the file as read-only:
    File file(filename, File::ReadOnly);
    auto dataset = file.getDataSet("grp/data");

    // Read back, with allocating:
    auto data = dataset.read<std::vector<int>>();

    // Because `data` has the correct size, this will
    // not cause `data` to be reallocated:
    dataset.read(data);
}

Note: As of 2.8.0, one can use highfive/highfive.hpp to include everything HighFive. Prior to 2.8.0 one would include highfive/H5File.hpp.

Note: For advanced usecases the dataset can be created without immediately writing to it. This is common in MPI-IO related patterns, or when growing a dataset over the course of a simulation.

Write a 2 dimensional C double float array to a 2D HDF5 dataset

See create_dataset_double.cpp

Write and read a matrix of double float (boost::ublas) to a 2D HDF5 dataset

See boost_ublas_double.cpp

Write and read a subset of a 2D double dataset

See select_partial_dataset_cpp11.cpp

Create, write and list HDF5 attributes

See create_attribute_string_integer.cpp

And others

See src/examples/ subdirectory for more info.

H5Easy

For several 'standard' use cases the highfive/H5Easy.hpp interface is available. It allows:

Example

#include <highfive/H5Easy.hpp>

int main() {
    H5Easy::File file("example.h5", H5Easy::File::Overwrite);

    int A = ...;
    H5Easy::dump(file, "/path/to/A", A);

    A = H5Easy::load<int>(file, "/path/to/A");
}

whereby the int type of this example can be replaced by any of the above types. See easy_load_dump.cpp for more details.

Note: Classes such as H5Easy::File are just short for the regular HighFive classes (in this case HighFive::File). They can thus be used interchangeably.

CMake integration

There's two common paths of integrating HighFive into a CMake based project. The first is to "vendor" HighFive, the second is to install HighFive as a normal C++ library. Since HighFive makes choices about how to integrate HDF5, sometimes following the third Bailout Approach is needed.

Regular HDF5 CMake variables can be used. Interesting variables include:

Please consult tests/cmake_integration for examples of how to write libraries or applications using HighFive.

Vendoring HighFive

In this approach the HighFive sources are included in a subdirectory of the project (typically as a git submodule), for example in third_party/HighFive.

The projects CMakeLists.txt add the following lines

add_subdirectory(third_party/HighFive)
target_link_libraries(foo HighFive)

Note: add_subdirectory(third_party/HighFive) will search and "link" HDF5 but wont search or link any optional dependencies such as Boost.

Regular Installation of HighFive

Alternatively, HighFive can be install and "found" like regular software.

The project's CMakeLists.txt should add the following:

find_package(HighFive REQUIRED)
target_link_libraries(foo HighFive)

Note: find_package(HighFive) will search for HDF5. "Linking" to HighFive includes linking with HDF5. The two commands will not search for or "link" to optional dependencies such as Boost.

Bailout Approach

To prevent HighFive from searching or "linking" to HDF5 the project's CMakeLists.txt should contain the following:

# Prevent HighFive CMake code from searching for HDF5:
set(HIGHFIVE_FIND_HDF5 Off)

# Then "find" HighFive as usual:
find_package(HighFive REQUIRED)
# alternatively, when vendoring:
# add_subdirectory(third_party/HighFive)

# Finally, use the target `HighFive::Include` which
# doesn't add a dependency on HDF5.
target_link_libraries(foo HighFive::Include)

# Proceed to find and link HDF5 as required.

Optional Dependencies

HighFive does not attempt to find or "link" to any optional dependencies, such as Boost, Eigen, etc. Any project using HighFive with any of the optional dependencies must include the respective header:

#include <highfive/boost.hpp>
#include <highfive/eigen.hpp>

and add the required CMake code to find and link against the dependencies. For Boost the required lines might be

find_package(Boost REQUIRED)
target_link_libraries(foo PUBLIC Boost::headers)

Questions?

Do you have questions on how to use HighFive? Would you like to share an interesting example or discuss HighFive features? Head over to the Discussions forum and join the community.

For bugs and issues please use Issues.

Funding & Acknowledgment

The development of this software was supported by funding to the Blue Brain Project, a research center of the École polytechnique fédérale de Lausanne (EPFL), from the Swiss government's ETH Board of the Swiss Federal Institutes of Technology.

HighFive releases are uploaded to Zenodo. If you wish to cite HighFive in a scientific publication you can use the DOIs for the Zenodo records.

Copyright © 2015-2022 Blue Brain Project/EPFL

License

Boost Software License 1.0