****
HDF5
****


In ADIOS2, the default engine for reading and writing HDF5 files is called *"HDF5"*.
To use this engine, you can either specify it in your xml config file, with tag ``<engine type=HDF5>``
or, set it in client code. For example, here is how to create a hdf5 reader:

.. code-block:: c++

 adios2::IO h5IO = adios.DeclareIO("SomeName");
 h5IO.SetEngine("HDF5");
 adios2::Engine h5Reader = h5IO.Open(filename, adios2::Mode::Read);

In addition, with HDF5 distribution greater or equal to 1.11, one can use the engine ``HDF5Mixer``
to write files with the VDS (virtual dataset) feature from HDF5.
The corresponding tag in the xml file is: ``<engine type=HDF5Mixer>``

and a sample code for VDS writer is:

.. code-block:: c++

 adios2::IO h5IO = adios.DeclareIO("SomeName");
 h5IO.SetEngine("HDF5Mixer");
 adios2::Engine h5Writer = h5IO.Open(filename, adios2::Mode::Write);

To read back the h5 files generated with VDS to ADIOS2, one can use the HDF5 engine. Please make sure you are using the HDF5 library that has version greater than or equal to 1.11 in ADIOS2.

The h5 file generated by ADIOS2 has two levels of groups:  The top Group, ``/`` and its subgroups: ``Step0`` ... ``StepN``, where ``N`` is number of steps. All datasets belong to the subgroups.

Any other h5 file can be read back to ADIOS as well. To be consistent, when reading back to ADIOS2, we assume a default Step0, and all datasets from the original h5 file belong to that subgroup. The full path of a dataset (from the original h5 file) is used when represented in ADIOS2.

We can  pass options to HDF5 API from  ADIOS xml configuration. Currently we support CollectionIO (default false),  and  chunk specifications. The chunk specification uses  space  to  seperate values, and by default,  if a valid H5ChunkDim exists, it applies to all  variables, unless H5ChunkVar is specified.  Examples:

.. code-block:: xml

	<parameter key="H5CollectiveMPIO" value="yes"/>
	<parameter key="H5ChunkDim" value="200 200"/>
	<parameter key="H5ChunkVar" value="VarName1 VarName2"/>

We suggest to read HDF5 documentation before appling these options.
