HDF5
====

.. toctree::
   :maxdepth: 1
   :caption: Contents:

About
-----

`HDF5`_ is among the most widely used libraries for creating, managing, and reading file containers with data sets. Discoverer HPC public software repository provides access to a variety of HDF5 builds supported by out HPC support team.

Supported versions
------------------

To check which `HDF5`_ versions and build types are currently supported on Discoverer, execute on the login node:

.. code-block:: bash

 module avail hdf5

.. important:: Do not stick to the builds which names include the word ``api`` unless you are very familiar with the API version backward compatibility in HDF5, or your executable code needs any of these modules, as specified by its developers.

If you wish to check or use the recipe we followed to compile the HDF5 source code, visit:

https://gitlab.discoverer.bg/vkolev/recipes/-/tree/main/hdf5/

User-supported versions
.......................

Users are welcome to bring, compile, and use their own builds of HDF5, but **those builds will not be supported by the Discoverer HPC team.**

Supported filters
-----------------

The following filters are supported (as embedded) for all versions of HDF5 installed in the public software repository:

 * deflate
 * bz2
 * szip (provided by :doc:`libaec`)
 * zstd

.. important:: HDF5 plugin support is not enabled. If its presence is absolutely necessary, inform the HPC support staff (see :doc:`help`).

Compiler and MPI library affinity
---------------------------------

Compiler affinity
.................

Each version of HDF5 installed in the public software repository is built against four compiler sets: (i) :doc:`oneapi`, (ii) :doc:`nvidia_hpc_sdk`, (iii) :doc:`aocc`, (iv) :doc:`gcc`. The corresponding HDF5 environment module names contain the name of the compiler set employed for building the HDF5 code. Loading the selected module triggers loading the corresponding compiler environment.

MPI library affinity
....................

The name of the adopted MPI library is part of the HDF5 environment module name. Loading the selected module triggers loading the corresponding MPI and compiler environment.

The following MPI libraries are supported by the HDF5 builds installed in the public software repository:

 * `Open MPI`_ 4.x
 * `MPICH`_ 4.x

.. note:: Intel oneAPI MPI library is not yet supported. The preliminary tests detected severe run-time problems (like "Segmentation fault") on AMD Zen2 processors.

Non-MPI (serial) builds
.......................

Apart from the MPI-based HDF5 builds, there are also serial builds for each of the employed compiler sets. If the name of the HDF5 environment module does not contain MPI library name, that module set access to a HDF5 serial build.

Where is h5pfc
--------------

.. warning:: The offical HDF5 builds available in the public software repository of Discoverer HPC do *not* provide ``h5pfc`` parallel compiler wrapper. It is because in the latest HDF5 versions, the ``h5fc`` compiler wrapper inherits the MPI afinity defined for the compilation of the HDF5 programming code. In other words, the ``h5fc`` compiler wrapper included in the MPI-based HDF5 builds acts exactly the way ``h5pfc`` does. For example, the module ``hdf5/1/1.14/1.14.0-intel-openmpi``, when loaded, provides access to a ``h5fc`` compiler wrapper, which you can employ for compiling any compatible Fortran code against the corresponding Open MPI library.

See also the following discussion:

https://forum.hdfgroup.org/t/can-h4fc-and-h5pfc-be-built-with-cmake/8825

Getting help
------------

See :doc:`help`

.. _`Open MPI`: https://open-mpi.org
.. _`MPICH`: https://mpich.org
.. _`Libaec`: https://github.com/MathisRosenhauer/libaec
.. _`HDF5`: https://www.hdfgroup.org/solutions/hdf5/