Price Series ============= The price series are divided into two groups: ``main`` and ``secondary`` price series. The structure is the same for both objects and accepts a Txy with the prices and an optional list of doubles describing the probabilities. The API accepts a single main price series and a list of secondary price series. Due to a restriction in the JSON serialization library (which is hopefully resolved soon), the main price series must be provided as a vector with one element. Input ----- The attributes for both main and secondary price series are: - **series** (*Txy*): The prices as time series data. - **probabilities** (*std::optional>*): An optional vector of probabilities associated with the price series. Additionally for a Main price series, it is possible to provide a vector of percentiles for the water value calculations. This vector will include 0 and 100 by default in addition to the provided user values. The number of provided percentiles (together with 0 and 100) will be reflected as the second dimension of the water value matrix. the API accepts the series in the following way: .. code-block:: none :caption: Example of JSON-like data "price_series_main": [ { "name": "series": "probabilities": > "percentiles_for_water_values": // Optional } ] // list of one and only one element "price_series_secondary": [ { "name": "series": "probabilities": > }, { "name": "series": "probabilities": > } ] The series attribute is a Txy. The number of scenarios must match the number of historical years in the simulation. Further each scenario may also contain a list of price scenarios. The structure of the Series Txy will then be: .. code-block:: none "series": { "name": , "timestamps": [] "scenarios": [ [1.0, 2.0, ... ], [4.4, 5.5, ... ], ..., ] } The probabilities are optional, and can be provided as a list of doubles. The max number of probabilities are 16, and if less than 16 probabilities are provided, the remaining probabilites will be zeros. .. code-block:: json "probabilities": [0.1, 0.2, 0.3, 0.4] Model type ----------- The ``global settings`` attribute ``model type`` (EMPS or EOPS) will influence both the allowed input and the output. For a model type, one and only one main price series is allowed, and a list of secondary price series. For an EOPS model type, only one main price series is allowed (no secondary price series). If the EOPS model type is chosen, the API will use a flex script to convert the exogenous_prices.h5 into a corresponding .csv file. Output ------- The price series will be written to ``exogenous_prices.h5``. The probabilites will also be written to ``exogenous_prices.h5`` under the ``PSANN`` attribute. Additionally, a reference to the main price series will be written to all .enmd files as group 17. If the simulation type is EOPS, the ``exogenous_prices.h5`` will be automatically converted to .csv files. Connecting Market Steps ----------------------- To connect a Market Step with the price series, a category 12, or 13 market step must be used. According to Table 2b from ``utkast_nye_applikasjoner_i_LTM_versjon_10.pdf`` (a copy provided below), a category 12 or 13 market step will not have a price. The model interprets a market step without price as a category 12, or 13, and will convert it to the correct step based on the sign of the prices (positive prices will be 23, and negative prices will be 13) Copy of Tabell 2b from utkast_nye_applikasjoner_i_LTM_versjon_10.pdf --------------------------------------------------------------------- .. list-table:: Title :header-rows: 1 :widths: 30 20 20 20 20 20 * - Navn - Kjøp referert tidsserie - Salg referert tidsserie - Fra spotmarked (eksogen prisrekke) - Til spotmarked (eksogen prisrekke) - Gjenkjøp referert tidsserie * - Kategori nummer - 10 - 11 - 12 - 13 - 14 * - Denne nye API-type kontrakt, erstatter følgende gamle type kontrakter - 1, 3, 8 - 2, 9 - 6 - 7 - 4 * - Trinnummer - B - B - B - B - B * - Trinnavn - B - B - B - B - B * - Eget system - M - M - M - M - M * - Referanse til fast kontrakt - - - - - B * - Tilgjengelighet (%) - B - - - - * - Referanse til eksogen prisrekke - - - B - B - * - Mengde (%) - - - - - B * - Mengde (GWh) - B - B - B - B - * - Mengde v.v.ber (GWh) - - - M - M - * - Pris (Valuta/enhet) - B - B - - - B Market Steps ------------ The *exogenous prices market step* functionality allows market steps in EMPS to use externally defined price series. This feature is **only available in EMPS**. If a market step does not specify a fixed price directly, it is assumed to use the *exogenous price functionality*. In this case, the price is calculated dynamically as a combination of the **main price series**, an optional **secondary price series**, and a constant, using the following formula: :: Price(t) = a * X(t) + b * Y(t) + c Where: - ``X(t)`` is the **main price series**, shared across the entire model. - ``Y(t)`` is the **secondary price series**. - ``a``, ``b``, and ``c`` are scalar coefficients. There is only one main price series, which is globally defined and implicitly available to all market steps. Multiple secondary price series may be defined, but each market step may reference **only one** of them. Configuration Options --------------------- There are two supported methods for associating an exogenous price with a market step: 1. Direct Input of a 2D TXY Time Series ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A secondary price series can be provided directly within the market step definition as a 2D TXY time series, where values depend on time and scenario. This method does **not** support custom coefficients. Instead, the default values ``a = 0``, ``b = 1``, and ``c = 0`` are applied. As a result, the market step price will exactly follow the specified **secondary price series**, without reference to the main price series. **Example:** .. code-block:: json { "market_steps": [ { "name": "ms1", "exogenous_price": { "name": "price_ms1", "timestamps": [], "scenarios": [[]] } } ] } 2. Weighted Combination of Price Series ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Alternatively, a market step may reference an existing **secondary price series** by name and define coefficients ``a``, ``b``, and ``c``. This configuration enables a flexible weighted combination of the **main price series** and the referenced **secondary price series**. If no coefficients are provided, the default values ``a = 0``, ``b = 1``, and ``c = 0`` are applied — equivalent to using the secondary price series directly. **Example:** .. code-block:: json { "market_steps": [ { "name": "ms1", "secondary_price_series_name": "spot_forecast_2025", "price_series_coefficients": { "a": 0.5, "b": 0.2, "c": 1.8 } } ] } Implementation Notes -------------------- - Each market step must **either** define an inline ``exogenous_price`` or reference a named ``secondary_price_series_name``. - Only **one secondary price series** can be connected to each market step. - The **main price series** is implicitly available and does not require a connection. - If neither a direct price nor an exogenous price definition is provided, the market step configuration is considered invalid. Generated Output ---------------- When using the exogenous price functionality: - The market steps are assigned to categories ``ENMD.prefeansetrinn`` 12 and 13. - Energy volume time series are stored in: ``TidsserieData.h5``. - Price time series are stored in: ``exogenous_prices.h5``.