.. _exporting-label:

====================
Exporting of results
====================

General overview
================

Results can be exported via the API using several methods:

- Exporting to ``results.h5``
- Exporting via a user-defined python exporter

By default, exporting is *disabled*. Exporting is configured via the global
settings, and is triggered by the ``export_results`` function.

.. code-block:: python

    # Uses whatever export options are specified in the model
    session.export_results()

The following parameters affect the behavior of ``export_results``:

- `model.global_settings.export_target` - Specifies exporter target type
- `model.global_settings.export_directory_path` - Directory to export to
- `model.global_settings.export_settings` - Specifies which data to export

The following property can be used to inject an exporter:

- `model.exporter`

Exporting to ``results.h5``
===========================

First, a model must have been executed. Here is a basic example of that:

.. code-block:: python

    # Load and execute a model
    mod = pyltm.LtmApiModule("my_session")
    mod.load(filename=filename)
    mod.write_model()
    mod.execute_model()
    model = mod.model

Once a model has been executed successfully, we can export to Hdf5 by specifying
an export target, an export directory path, and then call the export function.

.. code-block:: python

    # export_target specifies which exporter to use
    model.global_settings.export_target = pyltm.ExportTarget.Hdf5

    # export_directory_path specifies which folder to export to
    model.global_settings.export_directory_path = "./run_export"

    # Export to results.h5
    mod.export_results()

Exporting via a user-specified exporter
=======================================

An exporter can be implemented in Python, and will receive the data to be
exported. The exporter will only be used if the export target is set to User,
and ``model.exporter`` has been specified.

Note that the exporter will be invoked several times with partial
data.

.. code-block:: python

    class MyCustomExporter(pyltm.Exporter):
    def __init__(self):
        self.db = MyBackendDb()

    def export_data(self, exported: pyltm.ExportedData):
            # data is a wrapper that may contain one of several types of data

            # Which type it is can be determined with isinstance:
            if isinstance(exported.data, pyltm.WindData):
                self.export_wind_data(exported.data)
            elif isinstance(exported.data, pyltm.WaterValueData):
                self.export_water_value_data(exported.data)
            else:
                raise RuntimeError(f"Unknown data type: {repr(exported.data)}")

    def export_wind_data(self, data: pyltm.WindData):
        # Wind data contgains one time series per busbar
        for data_per_busbar in data.busbar_tses:
            name = data_per_busbar.busbar_name
            txy = data_per_busbar.txy
            self.db.save_wind_data(name, txy)

    def export_water_value_data(self, data: pyltm.WaterValueData):
        # Water values contains a N-dimensional array per busbar
        for data_per_busbar in data.busbar_water_values:
            name = data_per_busbar.busbar_name
            water_values = data_per_busbar.water_values
            self.db.save_water_value_data(name, water_values)

    model.global_settings.export_target = pyltm.ExportTarget.User
    model.global_settings.export_directory_path = "./run_export"
    model.exporter = MyCustomExporter()

    # Export to results.h5
    mod.export_results()

Selective exporting
===================

The ``export_settings`` property can be used to select what to export.

.. code-block:: python

    model.global_settings.export_settings.export_water_values = True
    model.global_settings.export_settings.export_wind_data = False
    mod.export_results()