Util
====

.. automodule:: pyltm.util
   :members: make_txy
   :noindex:

``pyltm`` has a submodule named ``util``.

Some of the more useful methods are the ones to create various ``Txy``s.

``make_txy``
------------

When you want to create a ``Txy`` object, you can use the ``make_txy`` function.

Previously it was only possible to create a Txy with two distinct lists, one for ``timestamps`` and one for ``scenarios``.

With the new way, it is possible to create a ``Txy`` with a list of tuples, where each tuple contains a timestamp and a list of values for each scenario.

Consider the original method:

.. code-block:: python

    import pyltm

    # Original
    inflow = pyltm.Txy()

    inflow.timestamps = [
        datetime(2024, 1, 1),
        datetime(2024, 5, 1),
        datetime(2024, 10, 1),
    ]
    inflow.scenarios = [
        [1.01, 3.90, 2.82],
        [0.81, 3.12, 2.25],
        [0.40, 1.56, 1.13],
        [0.53, 2.03, 1.46],
        [0.44, 1.72, 1.24],
        [0.61, 2.34, 1.69],
        [0.93, 3.58, 2.59],
        [0.69, 2.65, 1.92],
    ]

With the new way:

.. code-block:: python

    import pyltm

    # New way
    inflow2 = pyltm.util.make_txy(
        [
            (
                "2024-01-01T00:00:00Z",
                [1.01, 0.81, 0.40, 0.53, 0.44, 0.61, 0.93, 0.69],
            ),
            (
                "2024-05-01T00:00:00Z",
                [3.90, 3.12, 1.56, 2.03, 1.72, 2.34, 3.58, 2.65],
            ),
            (
                "2024-10-01T00:00:00Z",
                [2.82, 2.25, 1.13, 1.46, 1.24, 1.69, 2.59, 1.92],
            ),
        ],
    )

    # Make sure they are equal
    assert inflow == inflow2

Functionally they are equivalent. It is way simpler to add a timestamp with the new way, than with the original method.

For a more complete example where ``make_txy`` is used to create timeseries for regulated and unregulated energy inflow for an aggregated hydro module.:

.. code-block:: python

    import pyltm

    # Previous
    agg_hydro_hallingdal = session.model.add(
    "enmag",
    "hallingdal_enmag_aggregated",
        {
            "reservoir_energy": 100000.0,
            "station_power": 22.0,
            "start_reservoir_energy": 60000,
            "regulated_energy_inflow": {
                "timestamps": [
                    "2024-01-01T00:00:00Z",
                    "2024-05-01T00:00:00Z",
                    "2024-10-01T00:00:00Z",
                ],
                "scenarios": [
                    [1.01, 3.90, 2.82],
                    [0.81, 3.12, 2.25],
                    [0.40, 1.56, 1.13],
                    [0.53, 2.03, 1.46],
                    [0.44, 1.72, 1.24],
                    [0.61, 2.34, 1.69],
                    [0.93, 3.58, 2.59],
                    [0.69, 2.65, 1.92],
                ],
            },
            "unregulated_energy_inflow": {
                "timestamps": [
                    "2024-01-01T00:00:00Z",
                    "2024-05-01T00:00:00Z",
                    "2024-10-01T00:00:00Z",
                ],
                "scenarios": [
                    [0.06, 0.23, 0.17],
                    [0.07, 0.28, 0.20],
                    [0.03, 0.12, 0.09],
                    [0.04, 0.16, 0.11],
                    [0.08, 0.31, 0.23],
                    [0.05, 0.19, 0.14],
                    [0.05, 0.19, 0.14],
                    [0.04, 0.14, 0.10],
                ],
            },
        },
    )

    # New way
    agg_hydro_hallingdal = pyltm.AggregatedHydroModule()
    session.model.add(agg_hydro_hallingdal)
    agg_hydro_hallingdal.name = "hallingdal_enmag_aggregated"
    agg_hydro_hallingdal.reservoir_energy = 100000.0
    agg_hydro_hallingdal.station_power = 22.0
    agg_hydro_hallingdal.start_reservoir_energy = 60000
    agg_hydro_hallingdal.regulated_power_inflow = pyltm.util.make_txy(
        [
            (
                "2024-01-01T00:00:00Z",
                [1.01, 0.81, 0.40, 0.53, 0.44, 0.61, 0.93, 0.69],
            ),
            (
                "2024-05-01T00:00:00Z",
                [3.90, 3.12, 1.56, 2.03, 1.72, 2.34, 3.58, 2.65],
            ),
            (
                "2024-10-01T00:00:00Z",
                [2.82, 2.25, 1.13, 1.46, 1.24, 1.69, 2.59, 1.92],
            ),
        ],
    )
    agg_hydro_hallingdal.unregulated_power_inflow = pyltm.util.make_txy(
        [
            (
                "2024-01-01T00:00:00Z",
                [0.06, 0.07, 0.03, 0.04, 0.08, 0.05, 0.05, 0.04],
            ),
            (
                "2024-05-01T00:00:00Z",
                [0.23, 0.28, 0.12, 0.16, 0.31, 0.19, 0.19, 0.14],
            ),
            (
                "2024-10-01T00:00:00Z",
                [0.17, 0.20, 0.09, 0.11, 0.23, 0.14, 0.14, 0.10],
            ),
        ],
    )