.. _data_tools:

piegy.data_tools
================

This section documents the data saving and reading tools.

.. py:function:: data_tools.save(mod, dirs = '', print_msg = True)

    .. line-block::
        Saves parameters and data of a model.
        Direcotries will be created if does not exist.

    :param mod: where the parameters of the model and data are stored. 
    :type mod: ``piegy.simulation.model`` object

    :param dirs: where to save data, should be the path of a folder. If ``''`` or ``'.'`` is given, will save in root directory. ``/`` will be added if not at the end of ``dirs``.
    :type dirs: str

    :param print_msg: whether to print a message after data is saved.
    :type print_msg: bool

|

.. py:function:: data_tools.load(dirs)

    .. line-block::
        Reads and returns a model from a directory.

    :param dirs: where the data is saved, should be path of the parent folder of data. ``/`` will be added if not at the end of ``dirs``.
    :type dirs: str

    :return: a model with its parameters and data.
    :rtype: ``piegy.simulation.model`` object

|

Examples
---------

.. line-block::
    We provide some small examples for ``piegy.data_tools`` functions. 

    First please import the ``piegy.data_tools.save`` and ``piegy.data_tools.load`` functions:

.. code-block:: python

    from piegy.data_tools import save, load


Assume you ran simulation on ``sim`` variable (``piegy.simulation.model`` object). Then save ``sim`` at ``some_directory`` directory by:

.. code-block:: python

    save(mod, 'some_directory')

``some_directory`` will be created if it does not exist.

You can read data by:

.. code-block:: python

    sim2 = load('some_directory')

Please pass in the same directory name as the one you used to save ``sim``.

Note that the data size can be very large. You can reduce size at the expense of losing accuracy by calling ``compress_data`` method of :ref:`piegy.simulation.model <simulation>`