.. _saving_results:

Saving results
==============

In this section we look at how we can save simulation results to files that can be read externally.
All operations can be performed using the :class:`~lizzy.LizzyModel` user-facing methods. For more details about the underlying core components, please refer to the :ref:`api_reference_index` documentation.


Saving to file
--------------

Results are saved in the `XDMF <https://www.xdmf.org/>`_ format, backed by an HDF5 binary file. This format is natively supported by `Paraview <https://www.paraview.org/>`_ and can be loaded directly for time-series visualisation.

To save results, use the :meth:`~lizzy.LizzyModel.save_results` method:

.. code-block::

    model.save_results()

This creates two files in a ``results/`` folder in the current working directory:

- ``<name>_RES.xdmf``: the XDMF descriptor file (open this in Paraview).
- ``<name>_RES.h5``: the HDF5 binary file containing all field data.

By default, ``<name>`` is taken from the mesh file name. A custom name can be provided as the second argument:

.. code-block::

    model.save_results(result_name="my_simulation")



The following fields are saved at each write-out time step:

- **FillFactor**: fill factor at each node (0 = empty, 1 = filled).
- **FreeSurface**: flow front indicator.
- **Pressure**: pressure field [Pa].
- **Velocity**: Darcy velocity field [m/s].

To these, we can also add optionally the full 3×3 permeability tensor for each element as a cell field, by passing ``save_permeability=True``:

.. code-block::

    model.save_results(save_permeability=True)
.. note::

    If the model is run in "Lighweight mode", Lizzy does not create any :class:`~lizzy.datatypes.Solution` object and :meth:`~lizzy.LizzyModel.save_results` cannot be called (will throw a ConfigurationError).

Viewing results in Paraview
----------------------------

To open the results from the ``.xdmf`` file in Paraview, it is necessary to select the reader **Xdmf3 Reader S**. This will be normally prompted for selection when the file is opened.

.. figure:: ../../images/paraview_result_example.png
   :width: 80%
   :align: center

   Example of simulation results visualised in Paraview