Refactor ramp rates a little more

Signed-off-by: Davey Elder <iandavidelder@gmail.com>

Author: idelder

temoa/components/operations.py

@@ -20,6 +20,8 @@
 from temoa.components import time
 
 if TYPE_CHECKING:
+    from pyomo.core.base import Expression
+
     from temoa.core.model import TemoaModel
     from temoa.types import ExprLike
     from temoa.types.core_types import Period, Region, Season, Technology, TimeOfDay, Vintage
@@ -192,7 +194,7 @@ def create_operational_vintage_sets(model: TemoaModel) -> None:
         model.is_seasonal_storage[t] = t in model.tech_seasonal_storage
 
 
-def _ramp_constraint(
+def _ramp_activity_increase(
     model: TemoaModel,
     ramp_up: bool,
     r: Region,
@@ -203,25 +205,12 @@ def _ramp_constraint(
     d_next: TimeOfDay,
     t: Technology,
     v: Vintage,
-) -> ExprLike:
-    """
-    Helper function to compute ramping constraints for both ramp-up and ramp-down.
-
-    Args:
-        model (TemoaModel): The Temoa model instance.
-        ramp_up (bool): True for ramp-up constraints, False for ramp-down constraints.
-        r (Region): The region.
-        p (Period): The period.
-        s (Season): The season.
-        d (TimeOfDay): The time of day.
-        s_next (Season): The next season.
-        d_next (TimeOfDay): The next time of day.
-        t (Technology): The technology.
-        v (Vintage): The vintage.
-
-    Returns:
-        Expression | Constraint.Skip: A tuple containing the activity increase
-        and rampable activity expressions or a constraint skip.
+) -> tuple[Expression, float] | None:
+    """Compute the hourly activity increase between adjacent time slices and the
+    ramp fraction for the given direction.
+
+    Returns ``(activity_increase, ramp_fraction)`` or ``None`` when the ramp
+    rate is so large that the constraint would never bind (skip).
     """
     ramping_param = model.ramp_up_hourly if ramp_up else model.ramp_down_hourly
 
@@ -246,19 +235,52 @@ def _ramp_constraint(
             f'Should be less than {1 / hours_elapsed:.4f}. Constraint skipped.'
         )
         logger.warning(msg.format(ramping_param.name, r, t, p, s, d, p, s_next, d_next))
-        return Constraint.Skip
+        return None
 
     activity_increase = hourly_activity_sd_next - hourly_activity_sd
-    rampable_activity = (
+    return activity_increase, ramp_fraction
+
+
+def _rampable_activity(
+    model: TemoaModel,
+    r: Region,
+    p: Period,
+    t: Technology,
+    v: Vintage,
+    ramp_fraction: float,
+) -> ExprLike:
+    """Rampable activity for the core model: fraction of total installed capacity."""
+    return (
         ramp_fraction
         * model.v_capacity[r, p, t, v]
         * value(model.capacity_to_activity[r, t])
         / (24 * value(model.days_per_period))
     )
+
+
+def _ramp_constraint(
+    model: TemoaModel,
+    ramp_up: bool,
+    r: Region,
+    p: Period,
+    s: Season,
+    d: TimeOfDay,
+    s_next: Season,
+    d_next: TimeOfDay,
+    t: Technology,
+    v: Vintage,
+) -> ExprLike:
+    """Helper that composes :func:`_ramp_activity_increase` and
+    :func:`_rampable_activity` into the core-model ramp constraint."""
+    result = _ramp_activity_increase(model, ramp_up, r, p, s, d, s_next, d_next, t, v)
+    if result is None:
+        return Constraint.Skip
+    activity_increase, ramp_fraction = result
+    rampable = _rampable_activity(model, r, p, t, v, ramp_fraction)
     if ramp_up:
-        return activity_increase <= rampable_activity
+        return activity_increase <= rampable
     else:
-        return -activity_increase <= rampable_activity
+        return -activity_increase <= rampable
 
 
 def ramp_up_constraint(

temoa/extensions/unit_commitment/components/commitment.py

@@ -16,7 +16,7 @@
 
 from pyomo.environ import Constraint, NonNegativeIntegers, quicksum, value
 
-from temoa.components import time
+from temoa.components.operations import _ramp_activity_increase
 from temoa.components.time import tod_elapsed_hours
 from temoa.components.utils import get_capacity_factor
 
@@ -445,116 +445,51 @@ def uc_min_down_time_constraint(
     return offline >= stopped_sum
 
 
-def _ramp_constraint(
+def _rampable_activity(
     model: UnitCommitmentModel,
-    ramp_up: bool,
     r: Region,
     p: Period,
     s: Season,
     d: TimeOfDay,
-    s_next: Season,
-    d_next: TimeOfDay,
     t: Technology,
     v: Vintage,
+    ramp_up: bool,
+    ramp_fraction: float,
 ) -> ExprLike:
-    r"""
-    UC-aware ramp-up / ramp-down constraint.
-
-    The core model ramp constraint bounds the change in hourly activity between
-    adjacent time slices against a fraction of **total installed capacity**:
-
-    .. math::
-
-        \Delta A \le RH_{r,t} \cdot \Delta H
-            \cdot \frac{\textbf{CAP}_{r,p,t,v} \cdot C2A_{r,t}}{24 \cdot DPP}
-
-    The UC version replaces :math:`\textbf{CAP}` with a commitment-aware
-    expression that accounts for *which* units are online and the operating
-    point assumed for units that start up or shut down during the transition:
-
-    .. math::
-
-        \Delta A \;\le\; \left[
-            RH_{r,t} \cdot \Delta H \cdot \textbf{UCN}_{r,p,s,d,t,v}
-            + f^{\min}_{\text{eff}} \cdot \textbf{UCST}_{r,p,s,d,t,v}
-            - f^{\min}_{\text{eff}} \cdot \textbf{UCSP}_{r,p,s,d,t,v}
-        \right]
-        \cdot \frac{UC_{r,t} \cdot C2A_{r,t}}{24 \cdot DPP}
-
-    (signs on :math:`\textbf{UCST}` and :math:`\textbf{UCSP}` are reversed for
-    the ramp-down direction.)
-
-    The differences from the core constraint are:
-
-    1. **Online units only.**  The rampable capacity is proportional to
-       :math:`\textbf{UCN}_{r,p,s,d,t,v} \cdot UC_{r,t}` rather than the full
-       :math:`\textbf{CAP}_{r,p,t,v}`.  Offline units contribute nothing to the
-       ramp envelope.
-
-    2. **Startup headroom (ramp-up) / startup drag (ramp-down).**  A unit that
-       starts during slice :math:`(s,d)` is assumed to begin producing at the
-       effective minimum output level :math:`f^{\min}_{\text{eff}}`.  For
-       ramp-up, this means the unit arrives part-way to its maximum output and
-       therefore provides *additional* headroom equal to
-       :math:`f^{\min}_{\text{eff}} \cdot UC_{r,t}`.  For ramp-down, the same
-       logic means a starting unit *reduces* the available ramp-down envelope
-       (it is already contributing output that cannot be instantly removed).
-
-    3. **Shutdown contribution (ramp-down headroom / ramp-up drag).**  A unit
-       that stops during slice :math:`(s,d)` was assumed to be running at
-       :math:`f^{\min}_{\text{eff}}` immediately before shutdown.  For ramp-down
-       this creates *additional* headroom (output falls by
-       :math:`f^{\min}_{\text{eff}} \cdot UC_{r,t}`); for ramp-up it reduces
-       headroom.
-
-    4. **Effective minimum fraction.**  The assumed operating point for
-       started/stopped units is
-       :math:`f^{\min}_{\text{eff}} = \max(\underline{f}_{r,t},\, RH_{r,t} \cdot \Delta H)`,
-       i.e. at least the configured minimum output fraction and at least the
-       ramp fraction itself.
-    """
-    ramping_param = model.ramp_up_hourly if ramp_up else model.ramp_down_hourly
-
-    hourly_activity_sd = _flow_out_sum(model, r, p, s, d, t, v) / time.hours_in_time_slice(
-        model, s, d
-    )
-    hourly_activity_sd_next = _flow_out_sum(
-        model, r, p, s_next, d_next, t, v
-    ) / time.hours_in_time_slice(model, s_next, d_next)
-
-    # Elapsed hours from middle of this time slice to middle of next time slice
-    hours_elapsed = time.tod_elapsed_hours(model, d, d_next)
-    ramp_fraction = hours_elapsed * value(ramping_param[r, t])
-    if ramp_fraction >= 1:
-        msg = (
-            'Warning: Rate for {}[{}, {}] is too large to be constraining from '
-            '({}, {}, {}) to ({}, {}, {}). '
-            f'Should be less than {1 / hours_elapsed:.4f}. Constraint skipped.'
-        )
-        logger.warning(msg.format(ramping_param.name, r, t, p, s, d, p, s_next, d_next))
-        return Constraint.Skip
-
-    activity_increase = hourly_activity_sd_next - hourly_activity_sd
-
     unit_cap = value(model.uc_unit_capacity[r, t])
     min_fraction = max(value(model.uc_min_output_fraction[r, t]), ramp_fraction)
     online = ramp_fraction * model.v_uc_online[r, p, s, d, t, v] * unit_cap
     startup = min_fraction * model.v_uc_started[r, p, s, d, t, v] * unit_cap
     shutdown = min_fraction * model.v_uc_stopped[r, p, s, d, t, v] * unit_cap
-    if ramp_up:
-        capacity_ramp = online + startup - shutdown
-    else:
-        capacity_ramp = online + shutdown - startup
-
-    rampable_activity = (
+    capacity_ramp = (online + startup - shutdown) if ramp_up else (online + shutdown - startup)
+    return (
         capacity_ramp
         * value(model.capacity_to_activity[r, t])
         / (24 * value(model.days_per_period))
     )
+
+
+def _ramp_constraint(
+    model: UnitCommitmentModel,
+    ramp_up: bool,
+    r: Region,
+    p: Period,
+    s: Season,
+    d: TimeOfDay,
+    s_next: Season,
+    d_next: TimeOfDay,
+    t: Technology,
+    v: Vintage,
+) -> ExprLike:
+    result = _ramp_activity_increase(model, ramp_up, r, p, s, d, s_next, d_next, t, v)
+    if result is None:
+        return Constraint.Skip
+    activity_increase, ramp_fraction = result
+    rampable = _rampable_activity(model, r, p, s, d, t, v, ramp_up, ramp_fraction)
     if ramp_up:
-        return activity_increase <= rampable_activity
+        return activity_increase <= rampable
     else:
-        return -activity_increase <= rampable_activity
+        return -activity_increase <= rampable
 
 
 def uc_ramp_up_constraint(
@@ -571,8 +506,28 @@ def uc_ramp_up_constraint(
     :code:`ramp_up_constraint` for technologies that appear in both the
     :code:`unit_commitment` and :code:`ramp_up_hourly` tables.
 
-    See :func:`_ramp_constraint` for the full mathematical description of how
-    the UC version differs from the core-model ramp constraint.
+    The ramp envelope is driven by *online units* rather than total installed
+    capacity.  Units that start during slice :math:`(s,d)` arrive part-way to
+    their maximum output, providing additional headroom; units that stop reduce
+    it:
+
+    .. math::
+       :label: uc_ramp_up
+
+        \frac{\sum_{I,O}\textbf{FO}_{r,p,s_{next},d_{next},i,t,v,o}}{H_{s_{next},d_{next}}}
+        -
+        \frac{\sum_{I,O}\textbf{FO}_{r,p,s,d,i,t,v,o}}{H_{s,d}}
+        \;\le\;
+        \left[
+            RH_{r,t} \cdot \Delta H \cdot \textbf{UCN}_{r,p,s,d,t,v}
+            + f^{\min}_{\text{eff}} \cdot \textbf{UCST}_{r,p,s,d,t,v}
+            - f^{\min}_{\text{eff}} \cdot \textbf{UCSP}_{r,p,s,d,t,v}
+        \right]
+        \cdot \frac{UC_{r,t} \cdot C2A_{r,t}}{24 \cdot DPP}
+
+    where :math:`f^{\min}_{\text{eff}} = \max(\underline{f}_{r,t},\, RH_{r,t} \cdot \Delta H)`
+    is the effective minimum output fraction for started/stopped units, and
+    :math:`\Delta H = (H_{s,d} + H_{s_{next},d_{next}}) / 2`.
     """
 
     s_next, d_next = model.time_next[s, d]
@@ -604,8 +559,26 @@ def uc_ramp_down_constraint(
     :code:`ramp_down_constraint` for technologies that appear in both the
     :code:`unit_commitment` and :code:`ramp_down_hourly` tables.
 
-    See :func:`_ramp_constraint` for the full mathematical description of how
-    the UC version differs from the core-model ramp constraint.
+    Symmetric to :func:`uc_ramp_up_constraint` with signs on
+    :math:`\textbf{UCST}` and :math:`\textbf{UCSP}` reversed: a unit that stops
+    during :math:`(s,d)` adds headroom (output falls), while a starting unit
+    reduces it:
+
+    .. math::
+       :label: uc_ramp_down
+
+        \frac{\sum_{I,O}\textbf{FO}_{r,p,s,d,i,t,v,o}}{H_{s,d}}
+        -
+        \frac{\sum_{I,O}\textbf{FO}_{r,p,s_{next},d_{next},i,t,v,o}}{H_{s_{next},d_{next}}}
+        \;\le\;
+        \left[
+            RD_{r,t} \cdot \Delta H \cdot \textbf{UCN}_{r,p,s,d,t,v}
+            + f^{\min}_{\text{eff}} \cdot \textbf{UCSP}_{r,p,s,d,t,v}
+            - f^{\min}_{\text{eff}} \cdot \textbf{UCST}_{r,p,s,d,t,v}
+        \right]
+        \cdot \frac{UC_{r,t} \cdot C2A_{r,t}}{24 \cdot DPP}
+
+    where :math:`f^{\min}_{\text{eff}} = \max(\underline{f}_{r,t},\, RD_{r,t} \cdot \Delta H)`.
     """
 
     s_next, d_next = model.time_next[s, d]