dft_tools/doc/reference/python/data_analysis/hdf5/ref.rst

Reference manual
##############################

The :class:`HDFArchive` class offers a convenient interface between the python objects and the HDF5 files, 
similar to a dictionary (or a shelve).

The module contains two classes : 

* :class:`HDFArchiveGroup` : operates on a subtree of the HDF5 file
* :class:`HDFArchive` : an :class:`HDFArchiveGroup` at the root path, with a simple constructor.
* :class:`HDFArchiveInert` : 

Typically, one constructs an :class:`HDFArchive` explicitely, the :class:`HDFArchiveGroup` is created during operations, e.g.::

  h = HDFArchive( "myfile.h5", 'r') 
  g = h['subgroup1'] # g is a HDFArchiveGroup.
  
Apart from the root path and the constructor, the classes are the same (in fact :class:`HDFArchive` `is a` :class:`HDFArchiveGroup`).
Let us first document :class:`HDFArchive`.

.. warning::  

   :class:`HDFArchive` and :class:`HDFArchiveGroup` do **NOT** handle parallelism.
   Check however the :class:`HDFArchiveInert` below.   
 
HDFArchive
=======================================

.. autoclass::  pytriqs.archive.HDFArchive



HDFArchiveGroup
=======================================

.. class::  HDFArchiveGroup

   There is no explicit constructor for the user of the class.

   The :class:`HDFArchiveGroup` support most of the operations supported by dictionaries. In the following, *H* is a :class:`HDFArchiveGroup`. 

   .. describe:: len(H)

      Return the number of items in the :class:`HDFArchiveGroup` *H*.

   .. describe:: H[key]

      Return the item of *H* with key *key*, retrieved from the file.  Raises a :exc:`KeyError` if *key*
      is not in the :class:`HDFArchiveGroup`.

   .. method:: get_raw (key)

      Returns the subgroup key, **without any reconstruction**, ignoring the HDF5_data_scheme.

   .. describe:: H[key] = value

      Set ``H[key]`` to *value*.

   .. describe:: del H[key]

      Remove ``H[key]`` from *H*.  Raises a :exc:`KeyError` if *key* is not in the
      :class:`HDFArchiveGroup`.

   .. describe:: key in H

      Return ``True`` if *H* has a key *key*, else ``False``.

   .. describe:: key not in H

      Equivalent to ``not key in H``.

   .. describe:: iter(H)

      Return an iterator over the keys of the dictionary.  This is a shortcut
      for :meth:`iterkeys`.

   .. method:: items()

      Generator returning couples (key, values) in the group.

   .. warning::

      Note that in all these iterators, the objects will only be retrieved from the file and loaded into memory 
      one by one. 


   .. method:: keys()

      Generator returning the keys of the group.

   .. method:: update(d)

      Add into the archive the content of any mapping *d* : keys->values, with 
      hfd-compliant values.

   .. method:: values()

      Generator returning the values in the group
      
   .. method:: create_group(K)

      Creates a new subgroup named `K` to the root path of the group. 
      Raises exception if the subgroup already exists.
  
   .. method:: is_group(K)
   
      Return True iif K is a subgroup.

   .. method::  is_data(K)
   
      Return True iif K is a leaf.

   .. method:: read_attr(AttributeName) 

      Return the attribute `AttributeName` of the root path of the group.
      If there is no attribute, return None.

   .. method:: root_path()

      Return the root path of the group

   .. method:: apply_on_leaves (f) 

       For each named leaf (name,value) of the tree, it calls `f(name,value)`.

       f should return : 
      
           - `None`                    : no action is taken
           - an `empty tuple` ()       : the leaf is removed from the tree
           - an hdf-compliant value    : the leaf is replaced by the value
 
HDFArchiveInert
=======================================


.. class:: HDFArchiveInert
 
   :class:`HDFArchive` and :class:`HDFArchiveGroup` do **NOT** handle parallelism.
   In general, it is good practive to write/read only on the master node. Reading from all nodes on a cluster may lead to communication problems.

   To simplify the writing of code, the simple HDFArchiveInert class may be useful.
   It is basically inert but does not fail.

   .. describe:: H[key]

      Return H and never raise exception. E.g. H['a']['b'] never raises an exception.

   .. describe:: H[key] = value
       
      Does nothing.

   Usage in a mpi code, e.g. ::

     R = HDFArchive("Results.h5",'w') if mpi.is_master_node() else HDFArchiveInert()
     a= mpi.bcast(R['a'])       # properly broadcast the R['a'] from the master to the nodes.
     R['b'] = X                 # sets R['b'] in the file on the master only, does nothing on the nodes.


.. highlight:: python

.. _HDF_Protocol:

Hdf-compliant objects
=======================================

By definition, hdf-compliant objects are those which can be stored/retrieved in an :class:`HDFArchive`.
In order to be hdf-compliant, a class must : 

* have a `HDF5_data_scheme` tag properly registered.
* implement one of the two protocols described below.

.. _HDF_Protocol_data_scheme:

HDF5 data scheme
-----------------------

To each hdf-compliant object, we associate
a `data scheme` which describes how the data is stored in the hdf5 tree, 
i.e. the tree structure with the name of the nodes and their contents.
This `data scheme` is added in the attribute `HDF5_data_scheme` 
at the node corresponding to the object in the file.

For a given class `Cls`, the `HDF5_data_scheme` is `Cls._hdf5_data_scheme_` if it exists or the name of the class `Cls.__name__`.
The `HDF5_data_scheme` of a class must be registered in order for :class:`HDFArchive` to properly reconstruct the object when rereading.
The class is registered using the module `hdf_archive_schemes` ::

 class myclass :
   pass #....
   
 from pytriqs.archive.hdf_archive_schemes import register_class
 register_class (myclass)

The function is 

.. py:function:: register_class (cls [, doc = None] ) 

     :param cls: the class to be registered.
     :param doc: a doc directory

     Register the class for :class:`HDFArchive` use.
      
     The name of `data scheme` will be `myclass._hdf5_data_scheme_` if it is defined, or the name of the class otherwise.

.. _HDF_Protocol_details:

How does a class become hdf-compliant ?
---------------------------------------

There are two ways in which a class can become hdf-compliant: 

.. toctree::
  :maxdepth: 1

  protocol1
  protocol2