Generalise reserve margin constraints for region/tech groups

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,12 @@ 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`,
+   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 +159,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
 
 **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 +185,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
 
 
 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,29 @@
 erDiagram
-capacity_credit {
- INTEGER period PK
+planning_reserve_credit {
    TEXT region PK
    TEXT tech PK
-   INTEGER vintage PK
    REAL credit
    TEXT notes
 }
+operating_reserve_derate {
+   TEXT region PK
+   TEXT season PK
+   TEXT tech PK
+   REAL factor
+   TEXT notes
+}
+planning_reserve_margin {
+   TEXT region PK
+   TEXT tech_or_group PK
+   REAL margin
+   TEXT notes
+}
+operating_reserve_margin {
+   TEXT region PK
+   TEXT tech_or_group PK
+   REAL margin
+   TEXT notes
+}
 technology {
  TEXT tech PK
    INTEGER annual
@@ -16,7 +33,6 @@ technology {
    INTEGER exchange
    TEXT flag
    INTEGER flex
-   INTEGER reserve
    INTEGER retire
    INTEGER seas_stor
    TEXT sector
@@ -539,11 +555,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 +567,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 +616,11 @@ 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
+region one or zero--0+ planning_reserve_credit : has
+technology one or zero--0+ planning_reserve_credit : has
+region one or zero--0+ operating_reserve_derate : has
+technology one or zero--0+ operating_reserve_derate : has
+time_season one or zero--0+ operating_reserve_derate : 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 +696,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 +789,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

docs/source/mathematical_formulation.rst

@@ -338,19 +338,8 @@ efficiency values.  If not specified for a given process, it defaults to 1,
 meaning the base :code:`efficiency` value applies uniformly.  Note that there is
 no period index: the time-varying efficiency applies to all periods.
 
-
 .. _capacity_factor_tech:
 
-capacity_credit
-~~~~~~~~~~~~~~~
-
-:math:`{CC}_{r \in R, p \in P, t \in T, v \in V}`
-
-The capacity credit represents the fraction of total installed capacity of
-a process that can be relied upon during the time slice in which peak
-electricity demand occurs. This parameter is used in the 'static' version of
-the :math:`reserve_margin` constraint.
-
 capacity_factor_tech
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -822,13 +811,51 @@ level to vary.
 planning_reserve_margin
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-:math:`{PRM}_{r \in R}`
+:math:`{PRM}_{r \in R, t \in T}`
+
+The required excess of credited installed capacity above demand, expressed
+as a fraction of demand, keyed by a region-or-group :math:`r` and a
+technology-or-group :math:`t`.  For example, a value of 0.2 requires that
+credited capacity be at least 120% of demand.  Demand is estimated from production
+by time slice.  Any exchange region (e.g. ``r1-r2``) where exactly one endpoint
+connects to the region or group is automatically included in the
+reserve calculation; this auto-inclusion is unique to the reserve margin constraints.
+
+
+planning_reserve_credit
+~~~~~~~~~~~~~~~~~~~~~~~
+
+:math:`{PRC}_{r \in R, t \in T}`
+
+The fraction of a technology's installed capacity that can be reliably counted
+toward the reserve margin.  A firm, fully dispatchable process (e.g. a gas turbine)
+typically receives a credit near 1, while a weather-dependent process (e.g. wind
+or solar) receives a lower value.
+
+
+operating_reserve_margin
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+:math:`{ORM}_{r \in R, t \in T}`
+
+The dynamic counterpart to :code:`planning_reserve_margin`, indexed the same
+way by region-or-group and technology-or-group. Rather than crediting
+installed capacity, it requires that available (derated) generation in each
+time slice exceed the region-group's proxy demand by this margin.
+Any exchange region (e.g. ``r1-r2``) where exactly one endpoint
+connects to the region or group is automatically included in the
+reserve calculation; this auto-inclusion is unique to the reserve margin constraints.
+
+
+operating_reserve_derate
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+:math:`{ORD}_{r \in R, s \in S, t \in T}`
 
-The :code:`planning_reserve_margin` parameter specifies the capacity reserve margin
-in the electric sector by region. The capacity reserve margin represents the
-installed generating capacity — expressed as a share of peak load — that must be
-available in reserve to meet contingencies. Temoa estimates peak demand from electricity
-production by time slice.
+The fraction of a technology's available output that can be depended upon in a
+given season.  A value less than 1 reflects the fact that not all of a process's
+capacity is reliably available — for example, due to scheduled maintenance or
+seasonal resource constraints.  Defaults to 1.
 
 
 ramp_down_hourly
@@ -851,18 +878,6 @@ by which a technology can ramp output up per hour.  This is used in the
 :code:`ramp_up_constraint`.
 
 
-reserve_capacity_derate
-~~~~~~~~~~~~~~~~~~~~~~~
-
-:math:`{RCD}_{r \in R, s \in S, t \in T^{res}, v \in V}`
-
-The :code:`reserve_capacity_derate` parameter allows the modeler to derate
-the capacity of a reserve technology in specific seasons — for example, to
-account for seasonal availability.  Values default to 1 (no derate). This
-parameter is used in the 'dynamic' version of the :code:`reserve_margin`
-constraint.
-
-
 .. _segment_fraction:
 
 segment_fraction
@@ -1313,9 +1328,11 @@ various physical and operational real-world phenomena.
 
 .. autofunction:: temoa.components.operations.ramp_down_constraint
 
-.. autofunction:: temoa.components.reserves.reserve_margin_static
+.. autofunction:: temoa.components.reserves.planning_reserve_margin_constraint
+
+.. autofunction:: temoa.components.reserves.operating_reserve_margin_constraint
 
-.. autofunction:: temoa.components.reserves.reserve_margin_dynamic
+.. autofunction:: temoa.components.reserves.reserve_margin_proxy_demand
 
 .. autofunction:: temoa.components.emissions.linked_emissions_tech_constraint
 

docs/source/param_desc_and_tables.rst

@@ -24,12 +24,13 @@ characteristics**.
    :widths: 15, 20, 25, 40
 
    ":math:`\text{C2A}_{r,t}`", ":code:`capacity_to_activity`", ":code:`capacity_to_activity`", "converts from capacity to activity units"
-   ":math:`\text{CC}_{r,p,t,v}`", ":code:`capacity_credit`", ":code:`capacity_credit`", "process-specific capacity credit used in the static reserve margin constraint"
+   ":math:`\text{PRC}_{r,t}`", ":code:`planning_reserve_credit`", ":code:`planning_reserve_credit`", "fraction of installed capacity that can be relied upon (default 0)"
    ":math:`\text{CFT}_{r,s,d,t}`", ":code:`capacity_factor_tech`", ":code:`capacity_factor_tech`", "technology-specific capacity factor"
    ":math:`\text{CFP}_{r,s,d,t,v}`", ":code:`capacity_factor_process`", ":code:`capacity_factor_process`", "process-specific capacity factor; allows capacity factor to change with technology vintage"
    ":math:`\text{ECAP}_{r,t,v}`", ":code:`existing_capacity`", ":code:`existing_capacity`", "installed capacity that exists prior to first model time period"
-   ":math:`\text{PRM}_{r}`", ":code:`planning_reserve_margin`", ":code:`planning_reserve_margin`", "planning reserve margin used to ensure sufficient generating capacity"
-   ":math:`\text{RCD}_{r,s,t,v}`", ":code:`reserve_capacity_derate`", ":code:`reserve_capacity_derate`", "capacity derate factor for dynamic reserve margin constraint"
+   ":math:`\text{PRM}_{r_g,t_g}`", ":code:`planning_reserve_margin`", ":code:`planning_reserve_margin`", "required excess of credited capacity above demand in each time slice, as a fraction of demand"
+   ":math:`\text{ORM}_{r_g,t_g}`", ":code:`operating_reserve_margin`", ":code:`operating_reserve_margin`", "required excess of available (derated) output above demand in each time slice, as a fraction of that demand"
+   ":math:`\text{ORD}_{r,s,t}`", ":code:`operating_reserve_derate`", ":code:`operating_reserve_derate`", "fraction of available output that can be relied upon in a given season (default 1)"
    ":math:`\text{RUH}_{r,t}`", ":code:`ramp_up_hourly`", ":code:`ramp_up_hourly`", "hourly rate at which generation techs can ramp output up"
    ":math:`\text{RDH}_{r,t}`", ":code:`ramp_down_hourly`", ":code:`ramp_down_hourly`", "hourly rate at which generation techs can ramp output down"
 
@@ -125,7 +126,6 @@ Parameters in the table below relate to the specification of **policy**.
    :header: "Parameter", "Database Table", "Model Element", "Notes"
    :widths: 15, 20, 25, 40
 
-   "", ":code:`rps_requirement`", ":code:`renewable_portfolio_standard`", "**[Deprecated]** RPS requirements; use :code:`limit_activity_share` instead"
    ":math:`\text{LIT}_{r,t,e,t'}`", ":code:`linked_tech`", ":code:`linked_techs`", "dummy techs used to convert CO2 emissions to physical commodity"
 
 Parameters in the table below relate to the specification of **construction and

docs/source/set_desc_and_tables.rst

@@ -51,14 +51,13 @@ number of **technology subsets**.
    ":math:`\text{T}^b`", ":code:`technology, flag = pb`", ":code:`tech_baseload`", "baseload electric generators, which have constant output across intraday time segments (:math:`{T}^b \subset T`)"
    ":math:`\text{T}^s`", ":code:`technology, flag = ps`", ":code:`tech_storage`", "all storage technologies (:math:`{T}^s \subset T`)"
    ":math:`\text{T}^a`", ":code:`technology, annual = 1`", ":code:`tech_annual`", "technologies that produce constant annual output (:math:`{T}^a \subset T`)"
-   ":math:`\text{T}^{res}`", ":code:`technology, reserve = 1`", ":code:`tech_reserve`", "electric generators contributing to the reserve margin requirement (:math:`{T}^{res} \subset T`)"
-   ":math:`\text{T}^c`", ":code:`technology, curtail = 1`", ":code:`tech_curtailment`", "technologies with curtailable output and no upstream cost (:math:`{T}^c \subset (T - T^{res})`)"
+   ":math:`\text{T}^c`", ":code:`technology, curtail = 1`", ":code:`tech_curtailment`", "technologies with curtailable output and no upstream cost (:math:`{T}^c \subset T`)"
    ":math:`\text{T}^f`", ":code:`technology, flex = 1`", ":code:`tech_flex`", "technologies producing excess commodity flows (:math:`{T}^f \subset T`)"
    ":math:`\text{T}^x`", ":code:`technology, exchange = 1`", ":code:`tech_exchange`", "technologies used for interregional commodity flows (:math:`{T}^x \subset T`)"
    ":math:`\text{T}^{ur}`", ":code:`ramp_up_hourly`", ":code:`tech_upramping`", "electric generators with a ramp up hourly rate limit; derived from :code:`ramp_up_hourly` table (:math:`{T}^{ur} \subset T`)"
    ":math:`\text{T}^{dr}`", ":code:`ramp_down_hourly`", ":code:`tech_downramping`", "electric generators with a ramp down hourly rate limit; derived from :code:`ramp_down_hourly` table (:math:`{T}^{dr} \subset T`)"
    ":math:`\text{T}^{ret}`", ":code:`technology, retire = 1`", ":code:`tech_retirement`", "technologies allowed to retire before end of life (:math:`{T}^{ret} \subset (T - T^{u})`)"
-   ":math:`\text{T}^u`", ":code:`technology, unlim_cap = 1`", ":code:`tech_uncap`", "technologies that have no bound on capacity (:math:`{T}^u \subset (T - T^{res})`)"
+   ":math:`\text{T}^u`", ":code:`technology, unlim_cap = 1`", ":code:`tech_uncap`", "technologies that have no bound on capacity (:math:`{T}^u \subset T`)"
    ":math:`\text{T}^{ss}`", ":code:`technology, flag = 'ps' AND seas_stor = 1`", ":code:`tech_seasonal_storage`", "seasonal storage technologies; requires both storage flag and seas_stor column (:math:`{T}^{ss} \subset T^s`)"
    "", ":code:`tech_group`", ":code:`tech_group_names`", "named groups for use in group constraints"
    "", ":code:`tech_group_member`", ":code:`tech_group_members`", "each technology belonging to each group"

temoa/__about__.py

@@ -21,4 +21,7 @@
 
 # db is tested for match on major and >= on minor
 DB_MAJOR_VERSION = 4
-MIN_DB_MINOR_VERSION = 0
+MIN_DB_MINOR_VERSION = 1
+
+# Also needs updating in database.rst
+DB_SCHEMA = 'temoa_schema_v4_1.sql'

temoa/_internal/temoa_sequencer.py

@@ -144,6 +144,8 @@ def build_model(self) -> TemoaModel:
                     data_portal,
                     silent=self.config.silent,
                     extensions=self.config.extensions,
+                    keep_lp_file=self.config.save_lp_file,
+                    lp_path=self.config.output_path,
                 )
 
             logger.info('Model build process complete.')