openPMD-api
|
openPMD is an open meta-data schema that provides meaning and self-description for data sets in science and engineering. See the openPMD standard for details of this schema.
This library provides a reference API for openPMD data handling. Since openPMD is a schema (or markup) on top of portable, hierarchical file formats, this library implements various backends such as HDF5, ADIOS2 and JSON. Writing & reading through those backends and their associated files are supported for serial and MPI-parallel workflows.
Curious? Our manual shows full read & write examples, both serial and MPI-parallel!
Required:
Shipped internally (downloaded by CMake unless openPMD_SUPERBUILD=OFF
is set):
I/O backends:
while those can be built either with or without:
Optional language bindings:
Our community loves to help each other. Please report installation problems in case you should get stuck.
Choose one of the install methods below to get started:
On very old macOS versions (<10.9) or on exotic processor architectures, this install method compiles from source against the found installations of HDF5, ADIOS2, and/or MPI (in system paths, from other package managers, or loaded via a module system, ...).
If MPI-support shall be enabled, we always have to recompile:
For some exotic architectures and compilers, you might need to disable a compiler feature called link-time/interprocedural optimization if you encounter linking problems:
Additional CMake options can be passed via individual environment variables, which need to be prefixed with openPMD_CMAKE_
.
openPMD-api can also be built and installed from source using CMake:
The following options can be added to the cmake
call to control features. CMake controls options with prefixed -D
, e.g. -DopenPMD_USE_MPI=OFF
:
CMake Option | Values | Description |
---|---|---|
openPMD_USE_MPI | AUTO/ON/OFF | Parallel, Multi-Node I/O for clusters |
openPMD_USE_HDF5 | AUTO/ON/OFF | HDF5 backend (.h5 files) |
openPMD_USE_ADIOS2 | AUTO/ON/OFF | ADIOS2 backend (.bp files in BP3, BP4 or higher) |
openPMD_USE_PYTHON | AUTO/ON/OFF | Enable Python bindings |
openPMD_USE_INVASIVE_TESTS | ON/**OFF** | Enable unit tests that modify source code 1 |
openPMD_USE_VERIFY | ON/OFF | Enable internal VERIFY (assert) macro independent of build type 2 |
openPMD_INSTALL | ON/OFF | Add installation targets |
openPMD_INSTALL_RPATH | ON/OFF | Add RPATHs to installed binaries |
Python_EXECUTABLE | (newest found) | Path to Python executable |
1 e.g. changes C++ visibility keywords, breaks MSVC 2 this includes most pre-/post-condition checks, disabling without specific cause is highly discouraged
Additionally, the following libraries are downloaded via FetchContent during the configuration of the project or, if the corresponding <PACKAGENAME>_ROOT
variable is provided, can be provided externally:
By default, this will build as a shared library (libopenPMD.[so|dylib|dll]
) and installs also its headers. In order to build a static library, append -DBUILD_SHARED_LIBS=OFF
to the cmake
command. You can only build a static or a shared library at a time.
By default, the Release
version is built. In order to build with debug symbols, pass -DCMAKE_BUILD_TYPE=Debug
to your cmake
command.
By default, tests, examples and command line tools are built. In order to skip building those, pass OFF
to these cmake
options:
CMake Option | Values | Description |
---|---|---|
openPMD_BUILD_TESTING | ON/OFF | Build tests |
openPMD_BUILD_EXAMPLES | ON/OFF | Build examples |
openPMD_BUILD_CLI_TOOLS | ON/OFF | Build command-line tools |
openPMD_USE_CUDA_EXAMPLES | ON/**OFF** | Use CUDA in examples |
The install will contain header files and libraries in the path set with -DCMAKE_INSTALL_PREFIX
.
If your project is using CMake for its build, one can conveniently use our provided openPMDConfig.cmake
package, which is installed alongside the library.
First set the following environment hint if openPMD-api was not installed in a system path:
Use the following lines in your project's CMakeLists.txt
:
Alternatively, add the openPMD-api repository source directly to your project and use it via:
For development workflows, you can even automatically download and build openPMD-api from within a depending CMake project. Just replace the add_subdirectory
call with:
If your (Linux/OSX) project is build by calling the compiler directly or uses a manually written Makefile
, consider using our openPMD.pc
helper file for pkg-config
, which are installed alongside the library.
First set the following environment hint if openPMD-api was not installed in a system path:
Additional linker and compiler flags for your project are available via:
openPMD-api is developed by many people. It was initially started by the Computational Radiation Physics Group at HZDR as successor to libSplash, generalizing the successful HDF5 & ADIOS1 implementations in PIConGPU. The following people and institutions contributed to openPMD-api:
Maintained by the following research groups:
Further thanks go to improvements and contributions from:
The openPMD-api authors acknowledge support via the following programs. Supported by the CAMPA collaboration, a project of the U.S. Department of Energy, Office of Science, Office of Advanced Scientific Computing Research and Office of High Energy Physics, Scientific Discovery through Advanced Computing (SciDAC) program. Previously supported by the Consortium for Advanced Modeling of Particles Accelerators (CAMPA), funded by the U.S. DOE Office of Science under Contract No. DE-AC02-05CH11231. Supported by the Exascale Computing Project (17-SC-20-SC), a collaborative effort of two U.S. Department of Energy organizations (Office of Science and the National Nuclear Security Administration). This project has received funding from the European Unions Horizon 2020 research and innovation programme under grant agreement No 654220. This work was partially funded by the Center of Advanced Systems Understanding (CASUS), which is financed by Germany's Federal Ministry of Education and Research (BMBF) and by the Saxon Ministry for Science, Culture and Tourism (SMWK) with tax funds on the basis of the budget approved by the Saxon State Parliament. Supported by the HElmholtz Laser Plasma Metadata Initiative (HELPMI) project (ZT-I-PF-3-066), funded by the "Initiative and Networking Fund" of the Helmholtz Association in the framework of the "Helmholtz Metadata Collaboration" project call 2022.
openPMD-api stands on the shoulders of giants and we are grateful for the following projects included as direct dependencies: