Generalize planning reserves and add operating reserves to unit commitment

docs/source/computational_implementation.rst

@@ -505,7 +505,7 @@ The Temoa model code is organized into clear, purpose-driven packages:
   * ``flows.py`` - Commodity flow balance constraints
   * ``capacity.py`` - Capacity and activity constraints
   * ``emissions.py`` - Emission accounting and constraints
-  * ``reserves.py`` - Reserve margin requirements
+  * ``reserves.py`` - Planning reserve margin and shared reserve helpers
   * ``limits.py`` - Various limit constraints (capacity, activity, emissions, etc.)
   * ``storage.py`` - Energy storage constraints
   * ``operations.py`` - Baseload and ramping constraints for generators

docs/source/database.rst

@@ -110,18 +110,26 @@ recommend that you populate input tables in the following order:
 Group Region and Technology Constraints
 ---------------------------------------
 
-Some constraint tables support summation over groups of regions or technologies. Note that each row in these tables will still only create one constraint, but that constraint will be a summation over the defined group. For example, the ``limit_capacity`` table will limit the total summed capacity of all technologies in the technology group (if used) and over all the regions in the region group (if used). Consider behaviour carefully. For example, the ``limit_annual_capacity_factor`` table will constrain the total summed capacity factor of the group, which would allow for varying capacity factors of processes within that group as long as the limit is met in aggregate.
+Some constraint tables support summation over groups of regions or technologies.
+Note that each row in these tables will still only create one constraint, but
+that constraint will be a summation over the defined group. For example, the
+``limit_capacity`` table will limit the total summed capacity of all technologies
+in the technology group (if used) and over all the regions in the region group (if used).
+Consider behaviour carefully. For example, the ``limit_annual_capacity_factor`` table will
+constrain the total summed capacity factor of the group, which would allow for varying
+capacity factors of processes within that group as long as the limit is met in aggregate.
 
 **Group Regions:**
 
 For the supported tables, the ``region`` column can be populated with either a single region (e.g., ``"east"``), a subset of regions delineated with a ``+`` (e.g., ``"east+west"``), or ``"global"`` to indicate summation over all model regions.
 
 .. important::
-   When grouped or global region constraints are used with exchange technologies,
-   exchange flows are only counted if the relevant exchange-technology keys are
+   When ``+`` delineated region summations are used with exchange technologies,
+   exchange flows are only counted if the relevant exchange-technology region pairs are
    explicitly included in the region string used by the constraint row.
-   Exchange-technology keys are directional and use a hyphen to separate the
-   two regions (e.g., ``east-west`` and ``west-east`` are distinct keys).
+   Exchange-technology regions are directional and use a hyphen to separate the
+   two regions (e.g., ``east-west`` and ``west-east`` are distinct keys). ``"global"``
+   *does* include all exchange flows by default.
 
    For example, to constrain activity across the ``east`` and ``west`` regions
    including all exchange flows between them, the region string should be:
@@ -132,7 +140,13 @@ For the supported tables, the ``region`` column can be populated with either a s
 
    If exchange keys are omitted (e.g., using only ``east+west``), flows through
    exchange technologies between those regions will *not* be included in the
-   constrained summation.
+   constraint summation.
+
+   The only exception to this rule is reserve margin constraints,
+   :code:`planning_reserve_margin` and :code:`operating_reserve_margin`
+   (:ref:`unit_commitment extension <extension-unit-commitment>`),
+   which automatically include all exchange flows into and out of the region
+   or region group due to their specific logic requiring this behaviour.
 
 Supported tables:
 
@@ -146,18 +160,17 @@ Supported tables:
 * limit_capacity_share
 * limit_new_capacity_share
 * limit_emission
-* limit_growth_capacity
-* limit_growth_new_capacity
-* limit_growth_new_capacity_delta
-* limit_degrowth_capacity
-* limit_degrowth_new_capacity
-* limit_degrowth_new_capacity_delta
+* planning_reserve_margin
+* operating_reserve_margin (unit_commitment extension)
 
 **Technology Groups:**
 
-For the supported tables, the following columns accept either technologies or technology groups, over which the constraint is summed. Technology groups are defined in the ``tech_group`` and ``tech_group_member`` tables.
+For the supported tables, the following columns accept either technologies or
+technology groups, over which the constraint is summed. Technology groups are
+defined in the ``tech_group`` and ``tech_group_member`` tables.
+
+Technology group columns:
 
-* tech
 * tech_or_group
 * sub_group
 * super_group
@@ -173,18 +186,14 @@ Supported tables:
 * limit_activity_share
 * limit_capacity_share
 * limit_new_capacity_share
-* limit_growth_capacity
-* limit_growth_new_capacity
-* limit_growth_new_capacity_delta
-* limit_degrowth_capacity
-* limit_degrowth_new_capacity
-* limit_degrowth_new_capacity_delta
+* planning_reserve_margin
+* operating_reserve_margin (unit_commitment extension)
 
 
 For help getting started, consider using the ``temoa tutorial``
 command to generate a template project or inspect the example SQL file at
 ``temoa/tutorial_assets/utopia.sql``. To begin building your own database file, use
-``temoa/db_schema/temoa_schema_v4.sql``, which is a database file with the requisite
+``temoa/db_schema/temoa_schema_v4_1.sql``, which is a database file with the requisite
 structure but no data added. We recommend leaving the database structure intact,
 and simply adding data to the schema file, or constructing an empty database
 from the schema file and then using a script or database editor to import data.

docs/source/database_schema.mmd

@@ -1,12 +1,19 @@
 erDiagram
-capacity_credit {
- INTEGER period PK
+planning_reserve_credit {
+   TEXT reserve_name PK
    TEXT region PK
    TEXT tech PK
-   INTEGER vintage PK
    REAL credit
    TEXT notes
 }
+planning_reserve_margin {
+   TEXT reserve_name PK
+   TEXT region PK
+   TEXT tech_or_group PK
+   TEXT type
+   REAL margin
+   TEXT notes
+}
 technology {
  TEXT tech PK
    INTEGER annual
@@ -16,7 +23,6 @@ technology {
    INTEGER exchange
    TEXT flag
    INTEGER flex
-   INTEGER reserve
    INTEGER retire
    INTEGER seas_stor
    TEXT sector
@@ -539,11 +545,6 @@ output_storage_level {
    REAL level
    TEXT sector
 }
-planning_reserve_margin {
- TEXT region PK
-   REAL margin
-   TEXT notes
-}
 ramp_down_hourly {
  TEXT region PK
    TEXT tech PK
@@ -556,22 +557,6 @@ ramp_up_hourly {
    TEXT notes
    REAL rate
 }
-reserve_capacity_derate {
- INTEGER period PK
-   TEXT region PK
-   TEXT season PK
-   TEXT tech PK
-   INTEGER vintage PK
-   REAL factor
-   TEXT notes
-}
-rps_requirement {
- TEXT notes
-   INTEGER period
-   TEXT region
-   REAL requirement
-   TEXT tech_group
-}
 tech_group {
  TEXT group_name PK
    TEXT notes
@@ -621,8 +606,8 @@ time_segment_fraction {
    TEXT notes
    REAL segment_fraction
 }
-technology one or zero--0+ capacity_credit : has
-time_period one or zero--0+ capacity_credit : has
+planning_reserve_margin one or zero--0+ planning_reserve_credit : has
+technology one or zero--0+ planning_reserve_credit : has
 technology_type 1--0+ technology : has
 time_period_type one or zero--0+ time_period : has
 technology one or zero--0+ capacity_factor_process : has
@@ -698,15 +683,9 @@ operator 1--0+ limit_capacity : has
 time_period one or zero--0+ limit_capacity : has
 time_period one or zero--0+ limit_capacity_share : has
 operator 1--0+ limit_capacity_share : has
-operator 1--0+ limit_degrowth_capacity : has
-operator 1--0+ limit_degrowth_new_capacity : has
-operator 1--0+ limit_degrowth_new_capacity_delta : has
 commodity one or zero--0+ limit_emission : has
 operator 1--0+ limit_emission : has
 time_period one or zero--0+ limit_emission : has
-operator 1--0+ limit_growth_capacity : has
-operator 1--0+ limit_growth_new_capacity : has
-operator 1--0+ limit_growth_new_capacity_delta : has
 time_period one or zero--0+ limit_new_capacity : has
 operator 1--0+ limit_new_capacity : has
 operator 1--0+ limit_new_capacity_share : has
@@ -797,15 +776,8 @@ sector_label one or zero--0+ output_storage_level : has
 time_period one or zero--0+ output_storage_level : has
 season_label one or zero--0+ output_storage_level : has
 time_of_day one or zero--0+ output_storage_level : has
-region one or zero--1 planning_reserve_margin : has
 technology one or zero--0+ ramp_down_hourly : has
 technology one or zero--0+ ramp_up_hourly : has
-technology one or zero--0+ reserve_capacity_derate : has
-time_period one or zero--0+ reserve_capacity_derate : has
-season_label one or zero--0+ reserve_capacity_derate : has
-time_period 1--0+ rps_requirement : has
-tech_group 1--0+ rps_requirement : has
-region 1--0+ rps_requirement : has
 tech_group one or zero--0+ tech_group_member : has
 technology one or zero--0+ tech_group_member : has
 time_period one or zero--0+ time_season : has