.. _import-directory:

=====================================
Importing a classic runtime directory
=====================================

A first and experimental version of ``import_directory`` is available from pyltm release 0.19.0. It is not complete and will not cover all edge cases.

Currently implemented features:
===============================

There may be bugs and uncovered edge cases.

Only EMPS is implemented. Import from an EOPS runtime directory is not implemented.

Import of time periods
----------------------

The API will parse ``LtmSystem.XML`` when importing a directory. From the time periods defined in the XML file, the API will calculate historical period, data period and simulation period. If FBMC is active, it will open the corresponding ``ptdf_constraints.h5`` file to reconstruct number of active weeks with FBMC.

.. note::
    Intra week timesteps is hardcoded to 168. ``PRISAVSNITT.DATA`` is not read when importing a runtime folder.

Import DETD with all restrictions
---------------------------------

Import of DETD (detailed hydro specification) is complete. All modules, plants, hydraulic couplings and pumps with restrictions and timeseries is complete.

Import of DCLines
-----------------

DCLines are read from a file named ``MASKENETT.DATA``.

Supported inputs are:

* Capacities in capfile (``Cap_file.h5``)
* Constant capacities in maskenett.

If there are multiple capacities present in maskenett, the API will throw and error message and refuse to continue. If there are multiple capacities, it is possible to use LTM CLI to convert it into a format supported by LTM-API. Use convert capfile functionality with ``konv_cap_file``.

.. note::

    Care must be taken when transferring the dataset from Windows to Linux. Casing of filenames are important. The correct casing for maskenett is ``MASKENETT.DATA``. If the file is lower-case, the API will not be able to find it and will throw an error.

    Rename the file to ``MASKENETT.DATA``.

TODO
====

A small list of items not imported in alphabetical order.

* Import of Aggregated Hydro (Enmag)
* Import of Battery
* Import of EOPS model type
* Import of FBMC (Flytbasert markedsklarering)
* Import of Loads (Preferansetrinn)
* Import of Market Steps (Markedssteg)
* Import of Outage and Breakdown (Havari)
* Import of Price Segments (Prisavsnitt)
* Import of Price Series (Prisrekker)
* Import of Scenario Dependent Loads (TidsserieData.h5)
* Anything not mentioned.

Example code
============

This is a simple import-and-dump example. Given a path to an existing EMPS runtime folder, ``/path/to/ltm/runtime/directory``, it will read that directory, import data, and write the API model to the relative path ``dump_output_path``. The path is relative to the current working directory for the invoking process.

Output files are ``model.json`` and ``model.h5``. They contain the complete API model with topology and references to timeseries in ``model.h5``. The timeseries are API-compatible, and not LTM-compatible.

.. code:: python

    import pyltm
    from pyltmapi import LtmSession, LtmDot

    # Create a session
    session = pyltm.LtmApiModule("import_session_name")

    # Path to read from
    path = "/path/to/ltm/runtime/directory"
    session.import_directory(path)

    session.dump_model(
        "dump_output_path",
        model_filename="model.json",
        timeseries_filename="model.h5",
    )

    print("Busbars:")
    for bb in session.model.busbars():
        print(f"\n{bb}:\n")
        # Uncomment to display detailed hydro topology for this area
        # LtmDot.display_dot_image(bb.build_connection_tree())

    print("DCLines:")
    for dc in session.model.dclines():
        print(
            f" - {dc.name.strip()}: {dc.from_busbar.strip()} -> {dc.to_busbar.strip()}"
        )