DLR Severity Map
================

The **Dynamic Line Rating (DLR) severity map** shows how ambient weather conditions affect the
thermal capacity of overhead transmission lines across Europe, based on the latest DestinE
Extremes Digital Twin forecast.

Background
----------

The thermal capacity (ampacity) of an overhead line depends primarily on:

* **Ambient temperature** — higher temperatures reduce the conductor's ability to shed heat.
* **Wind speed** — stronger crosswinds improve convective cooling and increase capacity.

DLR conditions are classified using a **CIGRE-based multi-parameter composite algorithm**.
Two severity indices are computed from the extracted meteorological fields:

* **BASE index** — wind speed (extrapolated to conduit height) and 2-metre ambient temperature.
  These two parameters account for approximately 80–90% of cooling-capacity variation and form
  the primary scoring signal.
* **EXTENDED index** — adds solar radiation as a Joule-heating penalty (worsening conditions)
  and precipitation as an evaporative-cooling benefit (improving conditions).

The composite score maps meteorological state to a **five-class ordinal scale**:

.. list-table::
   :header-rows: 1
   :widths: 10 20 70

   * - Class
     - Label
     - Conditions
   * - 1
     - Very Favorable
     - High winds and low temperatures — excellent line cooling capacity.
   * - 2
     - Favorable
     - Good wind and/or precipitation providing sufficient cooling.
   * - 3
     - Moderate
     - Average conditions — moderate cooling, no significant hazard.
   * - 4
     - Unfavorable
     - Low winds and/or elevated temperatures reducing line capacity.
   * - 5
     - Critical
     - Minimal wind combined with heatwave conditions — high risk of overloading.
   * - 6
     - Super-Critical
     - Near-zero wind (IEEE 738 still-air regime) combined with heatwave — extreme overloading risk.

This indicator-based approach is consistent with ENTSO-E scoring frameworks.  For further
methodological detail see Schicker et al. (2026) — *Combining High Resolution Forecasts with
Dynamic Line Rating*, Symposium Energieinnovation, Graz.

.. note::

   **On ampacity precision:** Comparison of IEEE 738 and CIGRE thermal model outputs against
   physical sensor measurements revealed substantial uncertainty between both standardized methods.
   The service therefore prioritises **robust favorable/unfavorable condition classification**
   over precise ampacity values.  Users requiring exact ampacity figures should apply their own
   derating methodology to the supplied meteorological variables.

Using the DLR severity page
-----------------------------

1. Click **Severity Map** in the navigation bar.
2. Use the forecast hour slider (0–23 h) to step through the forecast window.
3. Each grid cell is colour-coded by DLR severity class (1 = Very Favorable to 6 = Super-Critical).
4. Refer to the on-screen legend to interpret the colour scale.

The map is rendered server-side and delivered as a PNG image via the
``GET /api/v1/dlr/map/severity`` endpoint.  Images for all forecast timesteps are pre-generated
when new data arrives, so navigation between hours is near-instant.

API access
----------

.. list-table::
   :header-rows: 1
   :widths: 20 15 65

   * - Parameter
     - Type
     - Description
   * - ``time_index``
     - integer (≥ 0)
     - Index of the forecast timestep (0 = current hour).

Example:

.. code-block:: bash

   curl "https://hirenext.dev.desp.space/backend/api/v1/dlr/map/severity?time_index=6" \
     -H "Cookie: access_token=<your-token>" \
     --output severity_h6.png

The response is a PNG image (``image/png``).