.. _api_time_dependent_piecewise_linear_constraints:

Time dependent piecewise linear constraints
-------------------------------------------

Time dependent piecewise linear constraint in the LTM-core are:

 - **min_bypass_curve**
 - **max_bypass_curve**
 - **min_discharge_curve**
 - **max_discharge_curve**
 - **min_volume_curve**
 - **max_volume_curve**

in addition to the **reference_curve**. The linearisation is performed in the LTM-core.

In the LtmApi the :ref:`txylin-label` datatype is used to specify these time dependent constaints.
At least **two TxyLin value-pairs are required** to make a linear function which represents the piecewise linear time dependent constaints.
TxyLin value-pairs in the TxyLin datatype referes to points which are used for linearisation, these points must be specified correctly,
thus a stricter handling of the the TxyLin datatype than the Txy datatype is necessary, see :ref:`txylin-label` for details.

Below are examples of how to specify a maximum volum constraint for a reservoir object with linearisation between the points.

.. code-block::

    "max_volume_curve": {
        "timestamps": [
            "2024-W17",
            "2024-W30",
            "2024-W39"
        ],
        "scenarios": [
            [
                0.0,
                70.0,
                85.0
            ]
        ]
    }

The following example shows how to specify a maximum discharge constraint for a plant object.
Note the break-point behavoir of the resulting curve.

.. code-block::

    "max_discharge_curve": {
        "timestamps": [
            "2024-W01",
            "2024-W17",
            "2024-W18",
            "2024-W39",
            "2024-W40",
            "2024-W52"
        ],
        "scenarios": [
            [
                15.0,
                15.0,
                10.0,
                10.0,
                15.0,
                15.0
            ]
        ]
    }

These examples are shown in Fig. 1.

.. figure:: ../../ltm-core/core/hydropower_LTM/cyclic_curve.png
    :scale: 80%
    :align: center

    Fig. 1: Cyclic piecewise linear curve, i.e. repeated each year for the whole data period

.. _api_cyclic_piecewise_linear_constraints:

Cyclic piecewise linear constaints
----------------------------------

Cyclic curves are curves that will repeat for each year in the data period. Limitations are:

* Only for curves of type ``TxyLin``.
* Only 1 year (52 weeks) can be repeated.

When a curve is strictly within year 1703 + 52 weeks, the API will automatically repeat it for each year in the data period.

The criteria for selecting year 1703 as the base year is:

* It starts on monday 1st of January.
* It is the first year after the Julian and Gregarian calendar split to feature Monday on Jan 1st.
* It is far enough into the past, but not too far into the past.
* Year 1900 was considered, however, we have many examples with time series starting in 1900, that should not be repeated.

.. warning::

    Mixing timestamps for year 1703 and other years is not allowed and will result in an error message.

The easiest way to define a cyclic curve, is to use the modified ISO-week notation where the year is omitted.

.. code-block:: json

    "min_bypass_curve": {
        "timestamps": [
            "W05",
            "W20",
            "W35",
            "W50"
        ],
        "scenarios": [
            [
                1,
                2,
                2,
                1
            ]
        ]
    }

.. figure:: cyclic-minimum-bypass-curve.png
    :align: center

    Fig. 2: Bypass curve showing minimum bypass repeated for each of the 10 years in the data period.

A complete working example can be found in this notebook:

.. toctree::
   :maxdepth: 1
   :glob:

   cyclic-curves/cyclic-curves.ipynb

Cyclic PQ-curves
----------------

Plants can have a yearly cycle of PQ-curves. The easiest is to use weeks ``W01-W52`` when defining ``pq_curves`` and ``discharge_energy_equivalent`` attributes on the Plant object.

.. warning::

    The timestamps for both ``pq_curves`` and ``discharge_energy_equivalent`` must both be within, or outside of the cyclic range. A hard error will be issued if there is a mix between cyclic and non-cyclic timestamps.

Example of a constant discharge energy equivalent with a cyclic PQ-curve.

.. code-block:: json
    "discharge_energy_equivalent": {
        "timestamps": [
            "W01"
        ],
        "scenarios": [
            [
                0.7900
            ]
        ]
    },
    "pq_curves": {
        "W01": {
            "x": [
                0.0,
                100.0
            ],
            "y": [
                0.0,
                100.0
            ]
        },
        "W20": {
            "x": [
                0.0,
                170.0
            ],
            "y": [
                0.0,
                150.0
            ]
        },
        "W40": {
            "x": [
                0.0,
                90.30
            ],
            "y": [
                0.0,
                90.0
            ]
        }
    }