README.md
1# HighFive - HDF5 header-only C++ Library
2
3[](https://travis-ci.org/BlueBrain/HighFive)
4[](https://scan.coverity.com/projects/highfive)
5[](https://BlueBrain.github.io/HighFive)
6[](https://codecov.io/gh/BlueBrain/HighFive)
7
8## Brief
9
10HighFive is a modern header-only C++11 friendly interface for libhdf5.
11
12HighFive supports STL vector/string, Boost::UBLAS, Boost::Multi-array, Eigen and Xtensor. It handles C++ from/to HDF5 with automatic type mapping.
13HighFive does not require additional libraries (see dependencies) and supports both HDF5 thread safety and Parallel HDF5 (contrary to the official hdf5 cpp)
14
15It integrates nicely with other CMake projects by defining (and exporting) a HighFive target.
16
17
18### Design
19- Simple C++-ish minimalist interface
20- No other dependency than libhdf5
21- Zero overhead
22- Support C++11
23
24### Feature support
25- create/read/write files, datasets, attributes, groups, dataspaces.
26- automatic memory management / ref counting
27- automatic conversion of `std::vector` and nested `std::vector` from/to any dataset with basic types
28- automatic conversion of `std::string` to/from variable length string dataset
29- selection() / slice support
30- parallel Read/Write operations from several nodes with Parallel HDF5
31- Advanced types: Compound, Enum, Arrays of Fixed-length strings, References
32- etc... (see [ChangeLog](./CHANGELOG.md))
33
34### Dependencies
35- hdf5 (dev)
36- hdf5-mpi (optional, opt-in with -D*HIGHFIVE_PARALLEL_HDF5*=ON)
37- boost >= 1.41 (recommended, opt-out with -D*HIGHFIVE_USE_BOOST*=OFF)
38- eigen3 (optional, opt-in with -D*HIGHFIVE_USE_EIGEN*=ON)
39- xtensor (optional, opt-in with -D*HIGHFIVE_USE_XTENSOR*=ON)
40
41
42## Examples
43
44#### Write a std::vector<int> to 1D HDF5 dataset and read it back
45
46```c++
47#include <highfive/H5File.hpp>
48
49using namespace HighFive;
50// we create a new hdf5 file
51File file("/tmp/new_file.h5", File::ReadWrite | File::Create | File::Truncate);
52
53std::vector<int> data(50, 1);
54
55// let's create a dataset of native integer with the size of the vector 'data'
56DataSet dataset = file.createDataSet<int>("/dataset_one", DataSpace::From(data));
57
58// let's write our vector of int to the HDF5 dataset
59dataset.write(data);
60
61// read back
62std::vector<int> result;
63dataset.read(result);
64```
65
66**Note:** `H5File.hpp` is the top-level header of HighFive core which should be always included.
67
68**Note:** If you can use `DataSpace::From` on your data, you can combine the create and write into one statement.
69Such shortcut syntax is available for both `createDataSet` and `createAttribute`.
70```c++
71DataSet dataset = file.createDataSet("/dataset_one", data);
72```
73
74#### Write a 2 dimensional C double float array to a 2D HDF5 dataset
75
76See [create_dataset_double.cpp](src/examples/create_dataset_double.cpp)
77
78#### Write and read a matrix of double float (boost::ublas) to a 2D HDF5 dataset
79
80See [boost_ublas_double.cpp](src/examples/boost_ublas_double.cpp)
81
82#### Write and read a subset of a 2D double dataset
83
84See [select_partial_dataset_cpp11.cpp](src/examples/select_partial_dataset_cpp11.cpp)
85
86#### Create, write and list HDF5 attributes
87
88See [create_attribute_string_integer.cpp](src/examples/create_attribute_string_integer.cpp)
89
90#### And others
91
92See [src/examples/](src/examples/) subdirectory for more info.
93
94
95### Compiling with HighFive
96
97```bash
98c++ -o program -I/path/to/highfive/include source.cpp -lhdf5
99```
100
101### H5Easy
102
103For several 'standard' use cases the [highfive/H5Easy.hpp](include/highfive/H5Easy.hpp) interface is available. It allows:
104
105* Reading/writing in a single line of:
106
107 - scalars (to/from an extendible DataSet),
108 - strings,
109 - vectors (of standard types),
110 - [Eigen::Matrix](http://eigen.tuxfamily.org) (optional, enable CMake option `HIGHFIVE_USE_EIGEN`),
111 - [xt::xarray](https://github.com/QuantStack/xtensor) and [xt::xtensor](https://github.com/QuantStack/xtensor)
112 (optional, enable CMake option `HIGHFIVE_USE_XTENSOR`).
113 - [cv::Mat_](https://docs.opencv.org/master/df/dfc/classcv_1_1Mat__.html)
114 (optional, enable CMake option `HIGHFIVE_USE_OPENCV`).
115
116* Getting in a single line:
117
118 - the size of a DataSet,
119 - the shape of a DataSet.
120
121#### Example
122
123```cpp
124#include <highfive/H5Easy.hpp>
125
126int main() {
127 H5Easy::File file("example.h5", H5Easy::File::Overwrite);
128
129 int A = ...;
130 H5Easy::dump(file, "/path/to/A", A);
131
132 A = H5Easy::load<int>(file, "/path/to/A");
133}
134```
135
136whereby the `int` type of this example can be replaced by any of the above types. See [easy_load_dump.cpp](src/examples/easy_load_dump.cpp) for more details.
137
138**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.
139
140
141## CMake integration
142
143HighFive can easily be used by other C++ CMake projects.
144
145You may use HighFive from a folder in your project (typically a git submodule).
146```cmake
147cmake_minimum_required(VERSION 3.1 FATAL_ERROR)
148project(foo)
149set(CMAKE_CXX_STANDARD 11)
150
151add_subdirectory(highfive_folder)
152add_executable(bar bar.cpp)
153target_link_libraries(bar HighFive)
154```
155
156Alternativelly you can install HighFive once and use it in several projects via `find_package()`.
157
158A HighFive target will bring the compilation settings to find HighFive headers and all chosen dependencies.
159
160```cmake
161# ...
162find_package(HighFive REQUIRED)
163add_executable(bar bar.cpp)
164target_link_libraries(bar HighFive)
165```
166**Note:** Like with other libraries you may need to provide CMake the location to find highfive: `CMAKE_PREFIX_PATH=<highfive_install_dir>`
167
168**Note:** `find_package(HighFive)` will search dependencies as well (e.g. Boost if requested). In order to use the same dependencies found at HighFive install time (e.g. for system deployments) you may set `HIGHFIVE_USE_INSTALL_DEPS=YES`
169
170### Installing
171When installing via CMake, besides the headers, a HighFiveConfig.cmake is generated which provides the HighFive target, as seen before. Note: You may need to set `CMAKE_INSTALL_PREFIX`:
172```bash
173mkdir build && cd build
174# Look up HighFive CMake options, consider inspecting with `ccmake`
175cmake .. -DHIGHFIVE_EXAMPLES=OFF -DCMAKE_INSTALL_PREFIX="<highfive_install_dir>"
176make install
177```
178
179### Test Compilation
180As a header-only library, HighFive doesn't require compilation. You may however build tests and examples.
181
182```bash
183mkdir build && cd build
184cmake ../
185make # build tests and examples
186make test # build and run unit tests
187```
188
189**Note:** Unit tests require Boost. In case it's unavailable you may use `-DHIGHFIVE_USE_BOOST=OFF`.
190HighFive with disable support for Boost types as well as unit tests (though most examples will build).
191
192
193### Contributors
194
195See the list of contributors on [GitHub](https://github.com/BlueBrain/HighFive/graphs/contributors)
196
197Originally created by Adrien Devresse adrien.devresse@epfl.ch - Blue Brain Project
198
199Maintained by the Computing/HPC team, Blue Brain Project - EPFL
200
201
202### License
203
204Boost Software License 1.0
205
){kind=link}
){kind=link}
){kind=link}
){kind=link}