:py:mod:`pyloggrid.Libs.IOLib`
==============================

.. py:module:: pyloggrid.Libs.IOLib

.. autoapi-nested-parse::

   .. _IOLib:

   A library to handle reading/writing files.



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


Functions
~~~~~~~~~

.. autoapisummary::

   pyloggrid.Libs.IOLib.store_hdf5
   pyloggrid.Libs.IOLib.load_hdf5
   pyloggrid.Libs.IOLib.read_json_settings
   pyloggrid.Libs.IOLib.update_json_settings
   pyloggrid.Libs.IOLib.load_step
   pyloggrid.Libs.IOLib.save_step
   pyloggrid.Libs.IOLib.add_drawables



.. py:function:: store_hdf5(fun: Callable) -> Callable

   Decorator to handle fail-safe saving to hdf5.

   Attempts to save to ``<path>/output.h5``, then to ``<path>/output_bk.h5``.

   .. note:: The decorated function's path argument becomes a directory instead of a file.

   :param fun: a non failsafe saving function that takes a ``path`` (hdf5 file) first argument

   .. rubric:: Example

   ::

       @store_hdf5
       def add_group(path: str, group_name: str) -> None:
           path: h5py.File  # from the decorator
           path.create_group(group_name)


.. py:function:: load_hdf5(fun: Callable) -> Callable

   Decorator to handle fail-safe loading from hdf5.

   Attempts to load from ``<path>/output.h5``, or to ``<path>/output_bk.h5`` if the first one fails.

   .. note:: The decorated function's path argument becomes a directory instead of a file.

   .. warning:: If the decorated ``path`` argument is a file instead of a directory, this will only load this file (non fail-safe).

   :param fun: a non failsafe loading function that takes a ``path`` (hdf5 file) first argument

   .. rubric:: Example

   ::

       @load_hdf5
       def load_group(f: h5py.File, group_name: str) -> dict:
           group = f[group_name]
           return {name: group[name][:] for name in group}


.. py:function:: read_json_settings(path: str) -> dict

   reads the ``settings.json`` simulation file (fail-safe), returns the data

   :param path: directory where to find the file

   :returns: the json data as a dict

   :raises AssertionError: if the path doesn't exist


.. py:function:: update_json_settings(path: str, params: dict, update: bool = False) -> None

   Save simulation parameters to ``settings.json`` file.

   This is fail-safe though the use of ``settings_bk.json``.

   :param path: directory to save the settings to
   :param params: parameters to save to file
   :param update: if True, then existing parameters will be updated according to existing keys in ``params``. Otherwise, settings are overwritten.


.. py:function:: load_step(fields_names: List[str], path: str = None, step: int = None, filepath: str = None) -> dict

   Load the data corresponding to a simulation step saved in ``output.h5``, or older legacy formats.

   Only the ``path`` and ``filepath`` arguments are necessary in the latest version.

   :param filepath: path to save file. ([legacy] If omitted, the combination of `path` and `step` will be used instead.)
   :param fields_names: [legacy] grid's fields' names.
   :param path: data's parent directory
   :param step: [legacy] step number to load

   .. warning:: The legacy support (ordered and unordered ``.npz``) may be deprecated in the future, and only exists for loading old results.

   .. todo:: Once we deprecate the legacy support (3.x ?), remove the additional obsolete arguments, and reflect in usages

   :returns: a dict containing the saved data, ``{fields: the grid's fields, t: step time, N_points: grid size, k_min: grid k min, elapsed_time: real elapsed time, k0: grid.k0}``


.. py:function:: save_step(path: str, step: int, grid: pyloggrid.LogGrid.Grid.Grid, t: float, dt: float, time_tracker: pyloggrid.Libs.misc.TimeTracker) -> None

   Save current step's fields to a .h5 file ``save.h5`` (appending if existing), as a new dataset ``step_<step>``

   :param path: folder to save to
   :param grid: grid containing the fields to save
   :param t: time of the step
   :param dt: timestep used
   :param step: # of the step
   :param time_tracker: object that tracks elapsed time


.. py:function:: add_drawables(path: str, drawables: dict) -> None

   Adds a drawables data dict to a DataExplorer result

   :param path: the path where the DataExplorer result is
   :param drawables: the dict to save