h5pp
h5pp is a high-level C++17 interface for the HDF5 C library. With simplicity in
mind, h5pp lets users store common C++ data types into portable binary HDF5 files.
Latest release
Documentation
Go to examples to learn how to use h5pp.
Go to quickstart to see ways of installing h5pp.
Table of Contents
Introduction
HDF5 is a portable file format for storing large datasets efficiently. HDF5 has
official low-level API’s for C and Fortran with wrappers
for C++ and Java, and third-party bindings for Python, Julia, Matlab and many other languages. This makes HDF5 a
great tool for handling data in a collaborative setting.
Although well documented, the low-level C API is vast and using it directly can be challenging. There are many
high-level wrappers already that help the user experience, but as a matter of opinion, things could be even simpler.
Goals
h5pp is a high-level C++17 interface for the HDF5 C library which aims to be simple to use:
- Read and write common C++ types in a single line of code.
- Meaningful logs and error messages.
- No prior knowledge of HDF5 is required.
- Simple access to HDF5 features like tables, compression, chunking and hyperslabs.
- Simple installation with opt-in automatic installation of dependencies.
- Simple documentation.
Features
- Header-only C++17 template library.
- High-level front-end to the C API of the HDF5 library.
- Type support:
- all numeric types:
(u)int#_t, float, double, long double.
std::complex<> with any of the types above.- CUDA-style POD-structs with
x,y or x,y,z members as atomic type, such as float3 or double2. These work
with any of the types above. In h5pp these go by the name Scalar2<> and Scalar3<>.
- Contiguous containers with a
.data() member, such as std::vector<>.
- Raw C-style arrays or pointer to buffer + dimensions.
- Eigen types such as
Eigen::Matrix<>, Eigen::Array<> and Eigen::Tensor<>,
with automatic conversion to/from row-major storage
- Text types
std::string, char arrays, and std::vector<std::string>.
- Structs as HDF5 Compound types (example)
- Structs as HDF5 Tables (with user-defined compound HDF5 types for entries)
- Ragged “variable-length” data in HDF5 Table columns using
h5pp::varr_t<> and h5pp::vstr_t.
- Modern CMake installation of
h5pp and (opt-in) installation of dependencies.
- Multi-platform: Linux, Windows, OSX. (Developed under Linux).
Examples
Write an std::vector
#include <h5pp/h5pp.h>
int main() {
std::vector<double> v = {1.0, 2.0, 3.0}; // Define a vector
h5pp::File file("somePath/someFile.h5"); // Create a file
file.writeDataset(v, "myStdVector"); // Write the vector into a new dataset "myStdVector"
}
Read an std::vector
#include <h5pp/h5pp.h>
int main() {
h5pp::File file("somePath/someFile.h5", h5pp::FileAccess::READWRITE); // Open (or create) a file
auto v = file.readDataset<std::vector<double>>("myStdVector"); // Read the dataset from file
}
Find more code examples in the examples directory.
Get h5pp
There are currently 3 ways to obtain h5pp:
Requirements
- C++17 capable compiler. GCC version >= 7 or Clang version >= 7.0
- CMake version >= 3.15
- HDF5 library, version >= 1.8
Optional dependencies
- Eigen >= 3.3.4: Store Eigen containers. Enable with
#define H5PP_USE_EIGEN3.
- spdlog >= 1.3.1: Logging library. Enable with
#define H5PP_USE_SPDLOG.
- fmt >= 6.1.2: String formatting (used in
spdlog). Enable with #define H5PP_USE_FMT.
NOTE: Logging works the same with or without Spdlog enabled. When Spdlog is *
not* found, a hand-crafted logger is used in its place to give identical output but without any performance
considerations (implemented with STL lists, strings and streams).
Install
Read the instructions here or see installation
examples under quickstart. Find a summary below.
Option 1: Install with Conan (Recommended)
Install and configure conan, then run the following command to install
from conan center:
> conan install h5pp/1.11.2
Option 2: Install with CMake Presets
Git clone and use one of the bundled CMake Presets to configure and build the project.
In this case we choose release-cmake to install all the dependencies using just CMake.
git clone https://github.com/DavidAce/h5pp.git
cd h5pp
cmake --preset=release-cmake # Configure. Optionally add -DCMAKE_INSTALL_PREFIX=<install-dir>
cmake --build --preset=release-cmake # Builds tests and examples. Optionally add --parallel=<num cores>
cmake --install build/release-cmake # Install to <install-dir> (default is ./install)
ctest --preset=release-cmake # Optionally run tests
Read more about h5pp CMake options in the documentation
h5pp is header-only. Copy the files under include to your project and then add #include <h5pp/h5pp.h>.
Read more about linking h5pp to its dependencies here
To-do
- For version 2.0.0
- Single header
- Compiled-library mode
In no particular order
- Continue adding documentation
- Expand the pointer-to-data interface
- Expand testing using catch2 for more edge-cases in
- filesystem permissions
- user-defined types
- tables
- Expose more of the C-API:
- More support for parallel read/write with MPI
评论