.. _market_steps:

============
Market Steps
============

A **market_step** in the LTM represents a contract where the load/generation or sales/purchaces can be turned on and off depending on the spot price (Group 4 in the .enmd-files). Multiple such contracts can be defined for each area in the model.

The **market_steps** parameters are listed below.

To define a *market step* in the API, the following fields may be provided:

Parameters **name**, **capacity** are obligatory, while *price* or *exogenous_price* are obligatory and there others are optional.

.. list-table:: MarketStep Parameters
   :header-rows: 1
   :widths: 30 30 60

   * - Parameter
     - Datatype
     - Unit
   * - **name**
     - string
     - Object/area name
   * - **capacity** (MW)
     - :ref:`txy-label`
     - The capacity of the contract.
   * - *price (€/MWh)*
     - :ref:`txy-label`, optional
     - Price time series.
   * - capacity_vv
     - :ref:`txy-label`, optional
     - Capacity time series used for the water value calculation.
   * - *exogenous_price*
     - :ref:`txy-label`, optional
     - Exogenous price time series.
   * - price_series_coefficients
     - price_series_coeff_type_optional
     - Coefficients for price series.
   * - secondary_price_series_name
     - string, optional
     - Name of connected seconday price series.
   * - #comment
     - string, optional
     - Optional comment
   * - area_name
     - string
     - output, Market step is connected to area
   * - load_name
     - string
     - output, market step is connected to the load name, used for repurchases
   * - id
     - int
     - Output
   * - metadata
     - json
     - Output

The contract types available are sales, purchaces and repurchases.

 - **Sales/purchaces** contracts can be an export/import option defined by a time-dependent capacity and a time-dependent price.
 - **Repurchases** of loads can been seen as a mild form of curtailment (rationing).
 - **Thermal power generation** unit or a **Nuclear power plant** with defined capacity and price can be modelled as an purchace contract.
 - **Excess power** which has no load/buyer is dumped to a market step with a very low price. The excess power market step is automatically added to all areas.
 - **Curtailment** step is market step with a very high price (the highest defined price). The curtailment market step is automatically added to all areas.

Below are examples of market_steps for a thermal power generation unit, an export or sales option and and import or purchase option. All have defined capacities and prices.

.. collapse:: Thermal power generation, export and import examples

    .. code-block:: json

        "market_steps": [
            {
                "name": "Thermal power generation unit",
                "price": {
                    "timestamps": [
                        "2023-01-01T00:00:00Z",
                        "2024-01-01T00:00:00Z"
                    ],
                    "scenarios": [
                        [
                            70,
                            100
                        ]
                    ]
                },
                "capacity": {
                    "timestamps": [
                        "2023-01-01T00:00:00Z"
                    ],
                    "scenarios": [
                        [
                            150
                        ]
                    ]
                }
            },
            {
                "name": "export",
                "price": {
                    "timestamps": [
                        "2023-01-01T00:00:00Z",
                        "2024-01-01T00:00:00Z"
                    ],
                    "scenarios": [
                        [
                            70,
                            60
                        ]
                    ]
                },
                "capacity": {
                    "timestamps": [
                        "2023-01-01T00:00:00Z"
                    ],
                    "scenarios": [
                        [
                            -40
                        ]
                    ]
                }
            },
            {
                "name": "import",
                "price": {
                    "timestamps": [
                        "2023-01-01T00:00:00Z",
                        "2024-01-01T00:00:00Z"
                    ],
                    "scenarios": [
                        [
                            20,
                            10
                        ]
                    ]
                },
                "capacity": {
                    "timestamps": [
                        "2023-01-01T00:00:00Z"
                    ],
                    "scenarios": [
                        [
                            20
                        ]
                    ]
                }
            }
        ],

Repurchases
-----------

Repurchases can be seen as a mild curtailment.

It is possible to define several repurchase market steps for one load obligation. The sum of repurchase market step capacities must be lower than the load's capacity.

In the following example (collapsed, press the arrow-head) a repurchase on the load named `Seasonal` is added to the market step `repurchase`. This allows for
a time-varying repurchase of 4.99 - 9 MW of the load at a time-dependent price between 55 - 70 €/MWh.

.. collapse:: Repurchase example

    .. code-block:: json

        "loads": [
            {
                "name": "Seasonal",
                "capacity": {
                    "timestamps": [
                        "2024-01-01T00:00:00Z",
                        "2024-03-01T00:00:00Z",
                        "2024-06-01T00:00:00Z",
                        "2024-09-01T00:00:00Z",
                        "2024-12-01T00:00:00Z",
                        "2025-01-01T00:00:00Z",
                        "2025-03-01T00:00:00Z",
                        "2025-06-01T00:00:00Z",
                        "2025-09-01T00:00:00Z",
                        "2025-12-01T00:00:00Z",
                        "2026-01-01T00:00:00Z",
                        "2026-03-01T00:00:00Z",
                        "2026-06-01T00:00:00Z",
                        "2026-09-01T00:00:00Z",
                        "2026-12-01T00:00:00Z"
                    ],
                    "scenarios": [
                        [
                            13.0,
                            10.48,
                            8.99,
                            14.48,
                            18.0,
                            13.0,
                            10.48,
                            8.99,
                            14.48,
                            18.0,
                            13.0,
                            10.48,
                            8.99,
                            14.48,
                            18.0
                        ]
                    ]
                }
            },
        ]
        "market_steps": [
            {
                "name": "repurchase",
                "load_name": "Seasonal",
                "price": {
                    "#comment": "type: time series / txy",
                    "timestamps": [
                        "2024-01-01T00:00:00Z",
                        "2024-03-01T00:00:00Z",
                        "2024-06-01T00:00:00Z",
                        "2024-09-01T00:00:00Z",
                        "2024-12-01T00:00:00Z",
                        "2025-01-01T00:00:00Z",
                        "2025-03-01T00:00:00Z",
                        "2025-06-01T00:00:00Z",
                        "2025-09-01T00:00:00Z",
                        "2025-12-01T00:00:00Z",
                        "2026-01-01T00:00:00Z",
                        "2026-03-01T00:00:00Z",
                        "2026-06-01T00:00:00Z",
                        "2026-09-01T00:00:00Z",
                        "2026-12-01T00:00:00Z"
                    ],
                    "scenarios": [
                        [
                            60,
                            58,
                            60,
                            56,
                            55,
                            59,
                            60,
                            55,
                            70,
                            65,
                            50,
                            70,
                            62,
                            61,
                            57
                        ]
                    ]
                },
                "capacity": {
                    "timestamps": [
                        "2024-01-01T00:00:00Z",
                        "2024-03-01T00:00:00Z",
                        "2024-06-01T00:00:00Z",
                        "2024-09-01T00:00:00Z",
                        "2024-12-01T00:00:00Z",
                        "2025-01-01T00:00:00Z",
                        "2025-03-01T00:00:00Z",
                        "2025-06-01T00:00:00Z",
                        "2025-09-01T00:00:00Z",
                        "2025-12-01T00:00:00Z",
                        "2026-01-01T00:00:00Z",
                        "2026-03-01T00:00:00Z",
                        "2026-06-01T00:00:00Z",
                        "2026-09-01T00:00:00Z",
                        "2026-12-01T00:00:00Z"
                    ],
                    "scenarios": [
                        [
                            7.0,
                            5.48,
                            4.99,
                            7.48,
                            9.0,
                            7.0,
                            5.48,
                            4.99,
                            7.48,
                            9.0,
                            7.0,
                            5.48,
                            4.99,
                            7.48,
                            9.0
                        ]
                    ]
                }
            },
        ]


Exogenous prices
----------------

.. note::
    The use of exogenous prices is licensed, contact SINTEF for license questions.

For areas without fundamental modelling of the power system exogenous price series, or price forecasts, can be applied to set the power price.
In addition, secondary exogenous price series can be defined together with price series coefficients.
They allow for having different power prices in areas with exogenous prices series. The main exogenous price series and the secondary price series are used
simultaneously following a weighted linear relation according to the equation below, to represent the area power price:

.. math::

   X_a = a X_{mps} + b X_{sps} + c
   \qquad [\text{€/MWh},\ \text{cent/kWh}]

where :math:`X_a` = modified price used in the simulations, :math:`a` = conversion factor for the price forecast (p, u), :math:`X_{mps}` = prices stored in the price forecast,
:math:`b` = conversion factor for the price forecast for other uncertainties (p, u), :math:`X_{sps}` = prices stored in the price forecast for other uncertainties and
:math:`c` = fixed additions or reductions to the original price.

Example using exogenous prices below (collapsed, press the arrow-head).

.. collapse:: Exogenous prices example

    .. code-block:: json

        "market_steps": [
            {
                "name": "ms_exo_direct",
                "capacity": {
                    "timestamps": [
                        "2024-01-01T00:00:00Z",
                        "2024-01-03T00:00:00Z"
                    ],
                    "scenarios": [
                        [
                            10.0,
                            20.0
                        ]
                    ]
                },
                "exogenous_price": {
                    "timestamps": [
                        "2023-01-01T00:00:00Z"
                    ],
                    "scenarios": [
                        [
                            10.0
                        ],
                        [
                            11.0
                        ],
                        [
                            12.0
                        ],
                        [
                            13.0
                        ],
                        [
                            14.0
                        ],
                        [
                            15.0
                        ],
                        [
                            16.0
                        ],
                        [
                            17.0
                        ]
                    ]
                }
            },
            {
                "name": "ms_exo_ref",
                "capacity": {
                    "timestamps": [
                        "2024-01-01T00:00:00Z",
                        "2024-01-03T00:00:00Z"
                    ],
                    "scenarios": [
                        [
                            10.0,
                            20.0
                        ]
                    ]
                },
                "price_series_coefficients": {
                    "a": 0.2,
                    "b": 0.5,
                    "c": 1.2
                },
                "secondary_price_series_name": "sps1"
            }
        ],
        "price_series_main": [
            {
                "name": "HOVEDPRISREKKE.csv",
                "series": {
                    "timestamps": [
                        "2024-01-01T00:00:00Z",
                        "2024-01-08T00:00:00Z",
                        "2024-01-15T00:00:00Z",
                        "2024-01-22T00:00:00Z",
                        "2024-01-29T00:00:00Z",
                        "2024-02-05T00:00:00Z",
                        "2024-02-12T00:00:00Z",
                        "2024-02-19T00:00:00Z",
                        "2024-02-26T00:00:00Z",
                        "2024-03-04T00:00:00Z"
                    ],
                    "scenarios": [
                        [
                            0.0,
                            10.0,
                            20.0,
                            30.0,
                            40.0,
                            50.0,
                            60.0,
                            70.0,
                            80.0,
                            90.0
                        ],
                        [
                            1.0,
                            11.0,
                            21.0,
                            31.0,
                            41.0,
                            51.0,
                            61.0,
                            71.0,
                            81.0,
                            91.0
                        ],
                        [
                            2.0,
                            12.0,
                            22.0,
                            32.0,
                            42.0,
                            52.0,
                            62.0,
                            72.0,
                            82.0,
                            92.0
                        ],
                        [
                            3.0,
                            13.0,
                            23.0,
                            33.0,
                            43.0,
                            53.0,
                            63.0,
                            73.0,
                            83.0,
                            93.0
                        ],
                        [
                            4.0,
                            14.0,
                            24.0,
                            34.0,
                            44.0,
                            54.0,
                            64.0,
                            74.0,
                            84.0,
                            94.0
                        ],
                        [
                            5.0,
                            15.0,
                            25.0,
                            35.0,
                            45.0,
                            55.0,
                            65.0,
                            75.0,
                            85.0,
                            95.0
                        ],
                        [
                            6.0,
                            16.0,
                            26.0,
                            36.0,
                            46.0,
                            56.0,
                            66.0,
                            76.0,
                            86.0,
                            96.0
                        ],
                        [
                            7.0,
                            17.0,
                            27.0,
                            37.0,
                            47.0,
                            57.0,
                            67.0,
                            77.0,
                            87.0,
                            97.0
                        ]
                    ]
                }
            }
        ],
        "price_series_secondary": [
            {
                "name": "sps1",
                "series": {
                    "timestamps": [
                        "2024-01-01T00:00:00Z"
                    ],
                    "scenarios": [
                        [
                            0.0
                        ],
                        [
                            1.0
                        ],
                        [
                            2.0
                        ],
                        [
                            3.0
                        ],
                        [
                            4.0
                        ],
                        [
                            5.0
                        ],
                        [
                            6.0
                        ],
                        [
                            7.0
                        ]
                    ]
                }
            }
        ],
        "connections": [
            {
                "from": "ms_exo_direct",
                "to": "numedal"
            },
            {
                "from": "ms_exo_ref",
                "to": "numedal"
            }
        ]


Output Files
------------

The API generates `.enmd` files for each area, each containing a market_steps entry (group 4). The categories created in the file are 10, 11, 12, 13, 14, 20 and 40.
(purchase timeseries, sales timeseries, purchace spot market priceseries, sales spot market priceseries, repurchase timeseries, excess power and curtailment).

Connections
-----------

Each market step must be connected to an **area**.

Notes
-----

- All time series must fully align with the dataperiod.