feat(reserves): support thermal reserves

alembic/versions/665f7b1d7575_add_thermal_reserve_.py

@@ -0,0 +1,62 @@
+"""add_thermal_reserve_tables
+
+Revision ID: 665f7b1d7575
+Revises: 80fdf2408ede
+Create Date: 2026-06-23 13:41:03.310148
+
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = '665f7b1d7575'
+down_revision = '80fdf2408ede'
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Certifications
+    op.create_table(
+        "thermal_reserve_certifications",
+        sa.Column("study_id", sa.String(36), nullable=False),
+        sa.Column("area_id", sa.String(255), nullable=False),
+        sa.Column("thermal_id", sa.String(255), nullable=False),
+        sa.Column("reserve_id", sa.String(255), nullable=False),
+        sa.Column("max_power", sa.Float(), nullable=False),
+        sa.Column("max_power_off", sa.Float(), nullable=False),
+        sa.Column("participation_cost", sa.Float(), nullable=False),
+        sa.Column("participation_cost_off", sa.Float(), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["study_id", "area_id", "thermal_id"],
+            ["thermal_cluster.study_id", "thermal_cluster.area_id", "thermal_cluster.thermal_id"],
+            ondelete="CASCADE",
+        ),
+        sa.ForeignKeyConstraint(
+            ["study_id", "area_id", "reserve_id"],
+            ["reserve_definition.study_id", "reserve_definition.area_id", "reserve_definition.reserve_id"],
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("study_id", "area_id", "thermal_id", "reserve_id"),
+    )
+
+    # Symmetries
+    op.create_table(
+        "thermal_reserve_symmetries",
+        sa.Column("study_id", sa.String(36), nullable=False),
+        sa.Column("area_id", sa.String(255), nullable=False),
+        sa.Column("thermal_id", sa.String(255), nullable=False),
+        sa.Column("symmetries", sa.String(), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["study_id", "area_id", "thermal_id"],
+            ["thermal_cluster.study_id", "thermal_cluster.area_id", "thermal_cluster.thermal_id"],
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("study_id", "area_id", "thermal_id"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("thermal_reserve_certifications")
+    op.drop_table("thermal_reserve_symmetries")

antarest/core/exceptions.py

@@ -150,6 +150,12 @@ def __init__(self, area_id: str, reserve_id: str):
         super().__init__(HTTPStatus.NOT_FOUND, msg)
 
 
+class ReserveDefinitionsNotFound(HTTPException):
+    def __init__(self, invalid_reserve_ids: dict[str, set[str]]):
+        msg = f"Reserve definitions not found: {invalid_reserve_ids}"
+        super().__init__(HTTPStatus.NOT_FOUND, msg)
+
+
 # ============================================================
 # Duplicate (409)
 # ============================================================
@@ -857,3 +863,9 @@ class SevenZipNotSupportedOnThisMachine(Exception):
     def __init__(self) -> None:
         msg = "7z command line is not supported on this machine. Consider installing it if you want to unarchive these files."
         super().__init__(msg)
+
+
+class ThermalReserveCertificationNotFound(HTTPException):
+    def __init__(self, area_id: str, thermal_id: str, reserve_ids: set[str]):
+        msg = f"Certifications for reserve(s) '{reserve_ids}' on thermal cluster '{thermal_id}' not found in area '{area_id}'"
+        super().__init__(HTTPStatus.NOT_FOUND, msg)

antarest/study/business/areas/reserve_certification_management.py

@@ -0,0 +1,58 @@
+# Copyright (c) 2026, RTE (https://www.rte-france.com)
+#
+# See AUTHORS.txt
+#
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+#
+# SPDX-License-Identifier: MPL-2.0
+#
+# This file is part of the Antares project.
+from antarest.study.business.model.thermal_reserve_certification_model import (
+    ReserveCertifications,
+)
+from antarest.study.business.study_interface import StudyInterface
+from antarest.study.storage.variantstudy.model.command.icommand import ICommand
+from antarest.study.storage.variantstudy.model.command.replace_thermal_reserve_certifications import (
+    ReplaceThermalReserveCertifications,
+)
+from antarest.study.storage.variantstudy.model.command_context import CommandContext
+
+
+class ReserveCertificationsManager:
+    def __init__(self, command_context: CommandContext) -> None:
+        self._command_context = command_context
+
+    def get_certifications(self, study: StudyInterface, area_id: str) -> ReserveCertifications:
+        thermals = study.get_study_dao().get_thermal_reserve_certifications(area_id)
+        return ReserveCertifications(thermals=thermals)
+
+    def set_certifications(
+        self,
+        study: StudyInterface,
+        area_id: str,
+        data: ReserveCertifications,
+    ) -> ReserveCertifications:
+        commands: list[ICommand] = []
+
+        # Thermals part
+        if data.thermals:
+            command = ReplaceThermalReserveCertifications(
+                area_id=area_id,
+                certifications=data.thermals,
+                study_version=study.version,
+                command_context=self._command_context,
+            )
+            commands.append(command)
+
+        # St-Storage part
+        # todo
+
+        # Hydro part
+        # todo
+
+        # Apply the modifications
+        if commands:
+            study.add_commands(commands)
+        return data

antarest/study/business/areas/reserve_symmetries_management.py

@@ -0,0 +1,38 @@
+# Copyright (c) 2026, RTE (https://www.rte-france.com)
+#
+# See AUTHORS.txt
+#
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+#
+# SPDX-License-Identifier: MPL-2.0
+#
+# This file is part of the Antares project.
+from antarest.study.business.model.reserve_symmetries_model import ReserveSymmetries
+from antarest.study.business.study_interface import StudyInterface
+from antarest.study.dao.common import ThermalId
+from antarest.study.storage.variantstudy.model.command.replace_thermal_reserve_symmetries import (
+    ReplaceThermalReserveSymmetries,
+)
+from antarest.study.storage.variantstudy.model.command_context import CommandContext
+
+
+class ReserveSymmetriesManager:
+    def __init__(self, command_context: CommandContext) -> None:
+        self._command_context = command_context
+
+    def get_thermal_symmetries(self, study: StudyInterface, area_id: str) -> dict[ThermalId, ReserveSymmetries]:
+        return study.get_study_dao().get_thermal_reserve_symmetries(area_id)
+
+    def set_thermal_symmetries(
+        self, study: StudyInterface, area_id: str, data: dict[ThermalId, ReserveSymmetries]
+    ) -> dict[ThermalId, ReserveSymmetries]:
+        command = ReplaceThermalReserveSymmetries(
+            area_id=area_id,
+            symmetries=data,
+            command_context=self._command_context,
+            study_version=study.version,
+        )
+        study.add_commands([command])
+        return data

antarest/study/business/model/reserve_symmetries_model.py

@@ -0,0 +1,28 @@
+# Copyright (c) 2026, RTE (https://www.rte-france.com)
+#
+# See AUTHORS.txt
+#
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+#
+# SPDX-License-Identifier: MPL-2.0
+#
+# This file is part of the Antares project.
+from typing import Annotated, TypeAlias
+
+from pydantic import BeforeValidator
+
+from antarest.study.business.model.reserve_definition_model import ReserveDefinitionId
+
+
+def _symmetry_validator(data: list[str]) -> list[str]:
+    if len(data) < 2:
+        raise ValueError(f"Reserve symmetries should have at least 2 elements, and was {data}")
+    if len(set(data)) != len(data):
+        raise ValueError(f"Reserve symmetries should not contain duplicates, and was {data}")
+    return sorted(data)
+
+
+ReserveSymmetry: TypeAlias = Annotated[list[ReserveDefinitionId], BeforeValidator(_symmetry_validator)]
+ReserveSymmetries: TypeAlias = list[ReserveSymmetry]

antarest/study/business/model/thermal_reserve_certification_model.py

@@ -0,0 +1,49 @@
+# Copyright (c) 2026, RTE (https://www.rte-france.com)
+#
+# See AUTHORS.txt
+#
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+#
+# SPDX-License-Identifier: MPL-2.0
+#
+# This file is part of the Antares project.
+from typing import Annotated, TypeAlias
+
+from pydantic import ConfigDict, Field
+from pydantic.alias_generators import to_camel
+
+from antarest.core.serde import AntaresBaseModel
+from antarest.study.business.model.reserve_definition_model import ReserveDefinitionId
+
+Cost = Annotated[float, Field(ge=0)]
+Power = Annotated[float, Field(ge=0)]
+
+##########################
+# Thermal part
+##########################
+
+
+class ThermalReserveCertification(AntaresBaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, extra="forbid", populate_by_name=True)
+
+    max_power: Power = 0.0
+    max_power_off: Power = 0.0
+    participation_cost: Cost = 0.0
+    participation_cost_off: Cost = 0.0
+
+
+ThermalId: TypeAlias = str
+ThermalReserveCertificationMapping = dict[ReserveDefinitionId, dict[ThermalId, ThermalReserveCertification]]
+
+
+##########################
+# Whole model
+##########################
+
+
+class ReserveCertifications(AntaresBaseModel):
+    model_config = ConfigDict(alias_generator=to_camel, extra="forbid", populate_by_name=True)
+
+    thermals: ThermalReserveCertificationMapping

antarest/study/dao/api/common.py

@@ -0,0 +1,36 @@
+# Copyright (c) 2026, RTE (https://www.rte-france.com)
+#
+# See AUTHORS.txt
+#
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+#
+# SPDX-License-Identifier: MPL-2.0
+#
+# This file is part of the Antares project.
+from antarest.study.business.model.reserve_definition_model import ReserveDefinitionId
+from antarest.study.business.model.reserve_symmetries_model import ReserveSymmetries
+
+
+def remove_reserve_symmetries_by_cascade(
+    symmetries_dict: dict[str, ReserveSymmetries], reserve_ids_to_remove: set[ReserveDefinitionId]
+) -> dict[str, ReserveSymmetries] | None:
+    """
+    When removing a reserve, we should also remove it from the symmetries.
+
+    Returns:
+        The updated symmetries dictionary or None if no symmetries were updated.
+    """
+    should_update_symmetries = False
+    for symmetries in symmetries_dict.values():
+        for i, symmetry in enumerate(symmetries):
+            symmetries[i] = [reserve_id for reserve_id in symmetry if reserve_id not in reserve_ids_to_remove]
+            if len(symmetries[i]) != len(symmetry):
+                should_update_symmetries = True
+            if len(symmetries[i]) == 1:
+                # We only have one reserve left in the symmetry, we should remove it
+                symmetries[i] = []
+    if should_update_symmetries:
+        return symmetries_dict
+    return None

antarest/study/dao/api/reserve_certification_dao.py

@@ -0,0 +1,49 @@
+# Copyright (c) 2026, RTE (https://www.rte-france.com)
+#
+# See AUTHORS.txt
+#
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+#
+# SPDX-License-Identifier: MPL-2.0
+#
+# This file is part of the Antares project.
+from abc import ABC, abstractmethod
+
+from antarest.study.business.model.thermal_reserve_certification_model import (
+    ThermalReserveCertificationMapping,
+)
+from antarest.study.dao.common import AreaId
+
+
+class ReadOnlyReserveCertificationDao(ABC):
+    @abstractmethod
+    def get_all_thermal_reserve_certifications(self) -> dict[AreaId, ThermalReserveCertificationMapping]:
+        """
+        Returns the thermal reserve certifications of the whole study.
+
+        Design notes:
+        - If an area has no certification, it won't be present in the returned data.
+        - If a thermal cluster has no certification, it also won't be present in the returned data.
+
+        """
+        raise NotImplementedError()
+
+    @abstractmethod
+    def get_thermal_reserve_certifications(self, area_id: AreaId) -> ThermalReserveCertificationMapping:
+        raise NotImplementedError()
+
+
+class ReserveCertificationDao(ReadOnlyReserveCertificationDao):
+    @abstractmethod
+    def save_thermal_reserve_certifications(self, data: dict[AreaId, ThermalReserveCertificationMapping]) -> None:
+        """
+        Replace the thermal reserve certifications with the given one.
+
+        Design notes:
+        - If an area is absent from the given data, its certifications are not modified.
+        - If a thermal cluster is absent from in the given data, its certifications will be removed.
+
+        """
+        raise NotImplementedError()