dft_tools/doc/reference/plotting_protocols/hdf5/protocol1.rst

.. _HDF_Protocol1:

Solution 1. The class provides the transformation into a dict of hdf-compliant objects
----------------------------------------------------------------------------------------------------

Principle
^^^^^^^^^^^^^^

The object which can be reduced to and reconstructed from a dictionary whose keys are strings,
and whose values are of one of the following types: 

    - a scalar (int, float, complex ....)
    - a numpy array of scalars 
    - an hdf-compliant object 
    - a list, a tuple or a dict of any of the types above.

A class `cls` has to implement :
    
.. py:method:: __reduce_to_dict__() 

   Returns a dictionary of objects implementing :ref:`hdf-compliant <HDF_Protocol>` 
   or basic objects as number, strings, and arrays of numbers (any type and shape).
   
   :rtype:  a dictionary

.. py:classmethod:: __factory_from_dict__(cls,D) :

   A **classmethod** which reconstructs a new object of type `cls`
   from the dictionary  returned by :func:`__reduce_to_dict__`.

   :param cls: the class 
   :param D: the dictionary returned by __reduce_to_dict__.
   :rtype: a new object of type `cls`
 
Example
^^^^^^^^^^^^^

A little example::

 class Example:

    def __init__(self,d,t): 
        self.d,self.t = d,t # some data

    def __reduce_to_dict__(self): 
        return {'d': self.d, 't': self.t}

    @classmethod
    def __factory_from_dict__(cls,D) :
        return cls(D['d'],D['t'])
 
 # registering my class
 from pytriqs.archive.hdf_archive_schemes import register_class
 register_class (myclass)

 # Testing it: 
 HDFArchive("myfile2.h5")['e'] = Example( [1,2,3], 56)


What happens in details  ? 
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Let us consider an object `Ob` of class `Cls`, interacting with and :py:class:`~pytriqs.archive.hdf_archive.HDFArchive`/:py:class:`~pytriqs.archive.hdf_archive.HDFArchiveGroup`  `H`.

* **Writing** ::

    H[Name] = Ob

  * a subgroup `S` of path `Root_of_H/Name` is created.
  * Ob.__reduce_to_dict__() is called and returns a dictionary `D` of  scalar/numpy arrays/hdf-compliant objects.
  * The objects in `D` are then stored `S` in a regular way (scalar/arrays) or using the same recursive procedure (other objects).
  * `S` is tagged with the attribute `HDF5_data_scheme` of `Cls`.


* **Reading** ::
  
      res = H[Name]

  * The subgroup `S` of path `Root_of_H/Name` is explored. All objects are taken to build a dictionary `D`: name -> values.
    This procedure is recursive: the hdf-compliant objects in the subgroup are rebuilt. 
  * An attribute `HDF5_data_scheme` is searched for `S`.
     
     * If it is found and it corresponds to a registered class `Cls` :
        
       * Cls.__factory_from_dict__(D) is called and returns a new object Obj of type Cls, which is returned as `res`.
   
     * Otherwise, a new :py:class:`~pytriqs.archive.hdf_archive.HDFArchiveGroup` is constructed with `S` as root, and returned as `res`.