py21cmfast.io.h5
================

.. py:module:: py21cmfast.io.h5

.. autoapi-nested-parse::

   Module defining HDF5 backends for reading/writing output structures.

   These functions are those used by default in the caching system of 21cmFAST.
   In the future, it is possible that other backends might be implemented.

   As of version 4, all cache files from 21cmFAST will have the following heirarchical
   structure::

       /attrs/
         |-- 21cmFAST-version
         |-- [redshift]
       /<OutputStructName>/
         /InputParameters/
           /attrs/
             |-- 21cmFAST-version
             |-- random_seed
           /simulation_options/
           /matter_options/
           /cosmo_params/
           /astro_options/
           /astro_params/
           /node_redshifts/
         /OutputFields/
           /attrs/
             |-- [primitive_field_1]
             |-- [primitive_field_2]
             |-- [...]
           /[field_1]/
           /[field_2]/
           /.../

   ..
       !! processed by numpydoc !!


Exceptions
----------

.. toctree::
   :hidden:

   /autoapi/py21cmfast/io/h5/HDF5FileStructureError

.. autoapisummary::

   py21cmfast.io.h5.HDF5FileStructureError


Functions
---------

.. autoapisummary::

   py21cmfast.io.h5.hdf5_to_dict
   py21cmfast.io.h5.read_inputs
   py21cmfast.io.h5.read_output_struct
   py21cmfast.io.h5.write_output_to_hdf5
   py21cmfast.io.h5.write_outputs_to_group


Module Contents
---------------

.. py:function:: hdf5_to_dict(grp)

   
   Load all data from an HDF5 Group into a dict.

   Essentially the same as toml.load() but for HDF5.















   ..
       !! processed by numpydoc !!

.. py:function:: read_inputs(group, safe = True)

   
   Read the InputParameters from a cache file.

   :Parameters: * **group** (*h5py.Group | Path | h5py.File*) -- A file, or HDF5 Group within a file, to read the input parameters from.
                * **safe** (*bool, optional*) -- If in safe mode, errors will be raised if keys exist in the file that are not
                  valid attributes of the InputParameters. Otherwise, only warnings will be raised.

   :returns: **inputs** (*InputParameters*) -- The input parameters contained in the file.















   ..
       !! processed by numpydoc !!

.. py:function:: read_output_struct(path, group = '/', struct = None, safe = True)

   
   Read an output struct from an HDF5 file.

   :Parameters: * **path** (*Path*) -- The path to the HDF5 file.
                * **group** (*str, optional*) -- A path within the HDF5 heirarchy to the top-level of the OutputStruct. This is
                  usually the root of the file.
                * **struct** -- A string specifying the kind of OutputStruct to read (e.g. InitialConditions).
                  Generally, this does not need to be provided, as cache files contain just a
                  single output struct.
                * **safe** -- Whether to read the file in "safe" mode. If True, keys found in the file that
                  are not valid attributes of the struct will raise an exception. If False, only
                  a warning will be raised.

   :returns: *OutputStruct* -- An OutputStruct that is contained in the cache file.















   ..
       !! processed by numpydoc !!

.. py:function:: write_output_to_hdf5(output, path, group = None, mode = 'w')

   
   Write an output struct in standard HDF5 format.

   :Parameters: * **output** -- The OutputStruct to write.
                * **path** (*Path*) -- The path to write the output struct to.
                * **group** (*str, optional*) -- The HDF5 group into which to write the object. By default, this is the root.
                * **mode** (*str*) -- The mode in which to open the file.















   ..
       !! processed by numpydoc !!

.. py:function:: write_outputs_to_group(output, group)

   
   Write the compute fields of an OutputStruct to a particular HDF5 subgroup.

   Here we are careful to close the file only if a raw Path is given, and keep it open
   if a h5py.File/Group is given (since then this is likely being called from another
   function that is also writing other objects to the same file).

   :Parameters: * **output** -- The OutputStruct to write.
                * **group** -- The HDF5 group into which to write the object. A new group "OutputFields" will
                  be created inside this group/file.















   ..
       !! processed by numpydoc !!