flixopt 3.0.1__py3-none-any.whl → 6.0.0rc7__py3-none-any.whl

flixopt/modeling.py

@@ -1,18 +1,104 @@
 import logging
+from typing import Any
 
 import linopy
 import numpy as np
 import xarray as xr
 
 from .config import CONFIG
-from .core import TemporalData
-from .structure import Submodel
+from .structure import Submodel, VariableCategory
 
 logger = logging.getLogger('flixopt')
 
 
+def _scalar_safe_isel(data: xr.DataArray | Any, indexers: dict) -> xr.DataArray | Any:
+    """Apply isel if data has the required dimensions, otherwise return data as-is.
+
+    This allows parameters to remain compact (scalar or lower-dimensional) while still
+    being usable in constraint expressions that use .isel() for slicing.
+
+    Args:
+        data: DataArray or scalar value
+        indexers: Dictionary of {dim: indexer} for isel
+
+    Returns:
+        Sliced DataArray if dims exist, otherwise original data
+    """
+    if not isinstance(data, xr.DataArray):
+        return data
+    # Only apply isel if data has all the required dimensions
+    if all(dim in data.dims for dim in indexers):
+        return data.isel(indexers)
+    return data
+
+
+def _scalar_safe_isel_drop(data: xr.DataArray | Any, dim: str, index: int) -> xr.DataArray | Any:
+    """Apply isel with drop=True if data has the dimension, otherwise return data as-is.
+
+    Useful for cases like selecting the last value of a potentially reduced array:
+    - If data has time dimension: returns data.isel(time=-1, drop=True)
+    - If data is reduced (no time dimension): returns data unchanged (already represents constant)
+
+    Args:
+        data: DataArray or scalar value
+        dim: Dimension name to select from
+        index: Index to select (e.g., -1 for last, 0 for first)
+
+    Returns:
+        Selected value with dimension dropped if dim exists, otherwise original data
+    """
+    if not isinstance(data, xr.DataArray):
+        return data
+    if dim in data.dims:
+        return data.isel({dim: index}, drop=True)
+    return data
+
+
+def _scalar_safe_reduce(data: xr.DataArray | Any, dim: str, method: str = 'mean') -> xr.DataArray | Any:
+    """Apply reduction (mean/sum/etc) over dimension if it exists, otherwise return data as-is.
+
+    Useful for aggregating over time dimension when data may be scalar (constant):
+    - If data has time dimension: returns getattr(data, method)(dim)
+    - If data is reduced (no time dimension): returns data unchanged (already represents constant)
+
+    Args:
+        data: DataArray or scalar value
+        dim: Dimension name to reduce over
+        method: Reduction method ('mean', 'sum', 'min', 'max', etc.)
+
+    Returns:
+        Reduced value if dim exists, otherwise original data
+    """
+    if not isinstance(data, xr.DataArray):
+        return data
+    if dim in data.dims:
+        return getattr(data, method)(dim)
+    return data
+
+
+def _xr_allclose(a: xr.DataArray, b: xr.DataArray, rtol: float = 1e-5, atol: float = 1e-8) -> bool:
+    """Check if two DataArrays are element-wise equal within tolerance.
+
+    Args:
+        a: First DataArray
+        b: Second DataArray
+        rtol: Relative tolerance (default matches np.allclose)
+        atol: Absolute tolerance (default matches np.allclose)
+
+    Returns:
+        True if all elements are close (including matching NaN positions)
+    """
+    # Fast path: same dims and shape - use numpy directly
+    if a.dims == b.dims and a.shape == b.shape:
+        return np.allclose(a.values, b.values, rtol=rtol, atol=atol, equal_nan=True)
+
+    # Slow path: broadcast to common shape, then use numpy
+    a_bc, b_bc = xr.broadcast(a, b)
+    return np.allclose(a_bc.values, b_bc.values, rtol=rtol, atol=atol, equal_nan=True)
+
+
 class ModelingUtilitiesAbstract:
-    """Utility functions for modeling calculations - leveraging xarray for temporal data"""
+    """Utility functions for modeling - leveraging xarray for temporal data"""
 
     @staticmethod
     def to_binary(
@@ -60,16 +146,16 @@ class ModelingUtilitiesAbstract:
         """Count consecutive steps in the final active state of a binary time series.
 
         This function counts how many consecutive time steps the series remains "on"
-        (non-zero) at the end of the time series. If the final state is "off", returns 0.
+        (non-zero) at the end of the time series. If the final state is "inactive", returns 0.
 
         Args:
-            binary_values: Binary DataArray with values close to 0 (off) or 1 (on).
+            binary_values: Binary DataArray with values close to 0 (inactive) or 1 (active).
             dim: Dimension along which to count consecutive states.
             epsilon: Tolerance for zero detection. Uses CONFIG.Modeling.epsilon if None.
 
         Returns:
-            Sum of values in the final consecutive "on" period. Returns 0.0 if the
-            final state is "off".
+            Sum of values in the final consecutive "active" period. Returns 0.0 if the
+            final state is "inactive".
 
         Examples:
             >>> arr = xr.DataArray([0, 0, 1, 1, 1, 0, 1, 1], dims=['time'])
@@ -101,11 +187,11 @@ class ModelingUtilitiesAbstract:
         if arr.size == 1:
             return float(arr[0]) if not np.isclose(arr[0], 0, atol=epsilon) else 0.0
 
-        # Return 0 if final state is off
+        # Return 0 if final state is inactive
         if np.isclose(arr[-1], 0, atol=epsilon):
             return 0.0
 
-        # Find the last zero position (treat NaNs as off)
+        # Find the last zero position (treat NaNs as inactive)
         arr = np.nan_to_num(arr, nan=0.0)
         is_zero = np.isclose(arr, 0, atol=epsilon)
         zero_indices = np.where(is_zero)[0]
@@ -119,12 +205,12 @@ class ModelingUtilitiesAbstract:
 class ModelingUtilities:
     @staticmethod
     def compute_consecutive_hours_in_state(
-        binary_values: TemporalData,
+        binary_values: xr.DataArray,
         hours_per_timestep: int | float,
         epsilon: float = None,
     ) -> float:
         """
-        Computes the final consecutive duration in state 'on' (=1) in hours.
+        Computes the final consecutive duration in state 'active' (=1) in hours.
 
         Args:
             binary_values: Binary DataArray with 'time' dim, or scalar/array
@@ -132,7 +218,7 @@ class ModelingUtilities:
             epsilon: Tolerance for zero detection (uses CONFIG.Modeling.epsilon if None)
 
         Returns:
-            The duration of the final consecutive 'on' period in hours
+            The duration of the final consecutive 'active' period in hours
         """
         if not isinstance(hours_per_timestep, (int, float)):
             raise TypeError(f'hours_per_timestep must be a scalar, got {type(hours_per_timestep)}')
@@ -160,14 +246,14 @@ class ModelingUtilities:
         previous_values: xr.DataArray, hours_per_step: xr.DataArray | float | int
     ) -> float:
         """
-        Compute previous consecutive 'off' duration.
+        Compute previous consecutive 'inactive' duration.
 
         Args:
             previous_values: DataArray with 'time' dimension
             hours_per_step: Duration of each timestep in hours
 
         Returns:
-            Previous consecutive off duration in hours
+            Previous consecutive inactive duration in hours
         """
         if previous_values is None or previous_values.size == 0:
             return 0.0
@@ -200,28 +286,38 @@ class ModelingPrimitives:
     @staticmethod
     def expression_tracking_variable(
         model: Submodel,
-        tracked_expression,
+        tracked_expression: linopy.expressions.LinearExpression | linopy.Variable,
         name: str = None,
         short_name: str = None,
-        bounds: tuple[TemporalData, TemporalData] = None,
+        bounds: tuple[xr.DataArray, xr.DataArray] = None,
         coords: str | list[str] | None = None,
+        category: VariableCategory = None,
     ) -> tuple[linopy.Variable, linopy.Constraint]:
-        """
-        Creates variable that equals a given expression.
+        """Creates a variable constrained to equal a given expression.
 
         Mathematical formulation:
             tracker = expression
-            lower ≤ tracker ≤ upper (if bounds provided)
+            lower ≤ tracker ≤ upper  (if bounds provided)
+
+        Args:
+            model: The submodel to add variables and constraints to
+            tracked_expression: Expression that the tracker variable must equal
+            name: Full name for the variable and constraint
+            short_name: Short name for display purposes
+            bounds: Optional (lower_bound, upper_bound) tuple for the tracker variable
+            coords: Coordinate dimensions for the variable (None uses all model coords)
+            category: Category for segment expansion handling. See VariableCategory.
 
         Returns:
-            variables: {'tracker': tracker_var}
-            constraints: {'tracking': constraint}
+            Tuple of (tracker_variable, tracking_constraint)
         """
         if not isinstance(model, Submodel):
             raise ValueError('ModelingPrimitives.expression_tracking_variable() can only be used with a Submodel')
 
         if not bounds:
-            tracker = model.add_variables(name=name, coords=model.get_coords(coords), short_name=short_name)
+            tracker = model.add_variables(
+                name=name, coords=model.get_coords(coords), short_name=short_name, category=category
+            )
         else:
             tracker = model.add_variables(
                 lower=bounds[0] if bounds[0] is not None else -np.inf,
@@ -229,6 +325,7 @@ class ModelingPrimitives:
                 name=name,
                 coords=model.get_coords(coords),
                 short_name=short_name,
+                category=category,
             )
 
         # Constraint: tracker = expression
@@ -239,56 +336,72 @@ class ModelingPrimitives:
     @staticmethod
     def consecutive_duration_tracking(
         model: Submodel,
-        state_variable: linopy.Variable,
+        state: linopy.Variable,
         name: str = None,
         short_name: str = None,
-        minimum_duration: TemporalData | None = None,
-        maximum_duration: TemporalData | None = None,
+        minimum_duration: xr.DataArray | None = None,
+        maximum_duration: xr.DataArray | None = None,
         duration_dim: str = 'time',
-        duration_per_step: int | float | TemporalData = None,
-        previous_duration: TemporalData = 0,
-    ) -> tuple[linopy.Variable, tuple[linopy.Constraint, linopy.Constraint, linopy.Constraint]]:
-        """
-        Creates consecutive duration tracking for a binary state variable.
+        duration_per_step: int | float | xr.DataArray = None,
+        previous_duration: xr.DataArray | float | int | None = None,
+    ) -> tuple[dict[str, linopy.Variable], dict[str, linopy.Constraint]]:
+        """Creates consecutive duration tracking for a binary state variable.
+
+        Tracks how long a binary state has been continuously active (=1).
+        Duration resets to 0 when state becomes inactive (=0).
 
         Mathematical formulation:
-            duration[t] ≤ state[t] * M  ∀t
+            duration[t] ≤ state[t] · M  ∀t
             duration[t+1] ≤ duration[t] + duration_per_step[t]  ∀t
-            duration[t+1] ≥ duration[t] + duration_per_step[t] + (state[t+1] - 1) * M  ∀t
-            duration[0] = (duration_per_step[0] + previous_duration) * state[0]
+            duration[t+1] ≥ duration[t] + duration_per_step[t] + (state[t+1] - 1) · M  ∀t
+            duration[0] = (duration_per_step[0] + previous_duration) · state[0]
 
             If minimum_duration provided:
-                duration[t] ≥ (state[t-1] - state[t]) * minimum_duration[t-1]  ∀t > 0
+                duration[t] ≥ (state[t-1] - state[t]) · minimum_duration[t-1]  ∀t > 0
+
+        Where M is a big-M value (sum of all duration_per_step + previous_duration).
 
         Args:
-            name: Name of the duration variable
-            state_variable: Binary state variable to track duration for
-            minimum_duration: Optional minimum consecutive duration
-            maximum_duration: Optional maximum consecutive duration
-            previous_duration: Duration from before first timestep
+            model: The submodel to add variables and constraints to
+            state: Binary state variable (1=active, 0=inactive) to track duration for
+            name: Full name for the duration variable
+            short_name: Short name for display purposes
+            minimum_duration: Optional minimum consecutive duration (enforced at state transitions)
+            maximum_duration: Optional maximum consecutive duration (upper bound on duration variable)
+            duration_dim: Dimension name to track duration along (default 'time')
+            duration_per_step: Time increment per step in duration_dim
+            previous_duration: Initial duration value before first timestep. If None (default),
+                no initial constraint is added (relaxed initial state).
 
         Returns:
-            variables: {'duration': duration_var}
-            constraints: {'ub': constraint, 'forward': constraint, 'backward': constraint, ...}
+            Tuple of (variables_dict, constraints_dict).
+            variables_dict contains: 'duration'.
+            constraints_dict always contains: 'ub', 'forward', 'backward'.
+            When previous_duration is not None, also contains: 'initial'.
+            When minimum_duration is provided, also contains: 'lb'.
+            When minimum_duration is provided and previous_duration is not None and
+            0 < previous_duration < minimum_duration[0], also contains: 'initial_lb'.
         """
         if not isinstance(model, Submodel):
             raise ValueError('ModelingPrimitives.consecutive_duration_tracking() can only be used with a Submodel')
 
-        mega = duration_per_step.sum(duration_dim) + previous_duration  # Big-M value
+        # Big-M value (use 0 for previous_duration if None)
+        mega = duration_per_step.sum(duration_dim) + (previous_duration if previous_duration is not None else 0)
 
         # Duration variable
         duration = model.add_variables(
             lower=0,
             upper=maximum_duration if maximum_duration is not None else mega,
-            coords=state_variable.coords,
+            coords=state.coords,
             name=name,
             short_name=short_name,
+            category=VariableCategory.DURATION,
         )
 
         constraints = {}
 
         # Upper bound: duration[t] ≤ state[t] * M
-        constraints['ub'] = model.add_constraints(duration <= state_variable * mega, name=f'{duration.name}|ub')
+        constraints['ub'] = model.add_constraints(duration <= state * mega, name=f'{duration.name}|ub')
 
         # Forward constraint: duration[t+1] ≤ duration[t] + duration_per_step[t]
         constraints['forward'] = model.add_constraints(
@@ -302,40 +415,40 @@ class ModelingPrimitives:
             duration.isel({duration_dim: slice(1, None)})
             >= duration.isel({duration_dim: slice(None, -1)})
             + duration_per_step.isel({duration_dim: slice(None, -1)})
-            + (state_variable.isel({duration_dim: slice(1, None)}) - 1) * mega,
+            + (state.isel({duration_dim: slice(1, None)}) - 1) * mega,
             name=f'{duration.name}|backward',
         )
 
         # Initial condition: duration[0] = (duration_per_step[0] + previous_duration) * state[0]
-        constraints['initial'] = model.add_constraints(
-            duration.isel({duration_dim: 0})
-            == (duration_per_step.isel({duration_dim: 0}) + previous_duration) * state_variable.isel({duration_dim: 0}),
-            name=f'{duration.name}|initial',
-        )
+        # Skipped if previous_duration is None (unconstrained initial state)
+        if previous_duration is not None:
+            constraints['initial'] = model.add_constraints(
+                duration.isel({duration_dim: 0})
+                == (duration_per_step.isel({duration_dim: 0}) + previous_duration) * state.isel({duration_dim: 0}),
+                name=f'{duration.name}|initial',
+            )
 
         # Minimum duration constraint if provided
         if minimum_duration is not None:
             constraints['lb'] = model.add_constraints(
                 duration
-                >= (
-                    state_variable.isel({duration_dim: slice(None, -1)})
-                    - state_variable.isel({duration_dim: slice(1, None)})
-                )
-                * minimum_duration.isel({duration_dim: slice(None, -1)}),
+                >= (state.isel({duration_dim: slice(None, -1)}) - state.isel({duration_dim: slice(1, None)}))
+                * _scalar_safe_isel(minimum_duration, {duration_dim: slice(None, -1)}),
                 name=f'{duration.name}|lb',
             )
 
-            # Handle initial condition for minimum duration
-            prev = (
-                float(previous_duration)
-                if not isinstance(previous_duration, xr.DataArray)
-                else float(previous_duration.max().item())
-            )
-            min0 = float(minimum_duration.isel({duration_dim: 0}).max().item())
-            if prev > 0 and prev < min0:
-                constraints['initial_lb'] = model.add_constraints(
-                    state_variable.isel({duration_dim: 0}) == 1, name=f'{duration.name}|initial_lb'
+            # Handle initial condition for minimum duration (skip if previous_duration is None)
+            if previous_duration is not None:
+                prev = (
+                    float(previous_duration)
+                    if not isinstance(previous_duration, xr.DataArray)
+                    else float(previous_duration.max().item())
                 )
+                min0 = float(_scalar_safe_isel(minimum_duration, {duration_dim: 0}).max().item())
+                if prev > 0 and prev < min0:
+                    constraints['initial_lb'] = model.add_constraints(
+                        state.isel({duration_dim: 0}) == 1, name=f'{duration.name}|initial_lb'
+                    )
 
         variables = {'duration': duration}
 
@@ -348,23 +461,21 @@ class ModelingPrimitives:
         tolerance: float = 1,
         short_name: str = 'mutual_exclusivity',
     ) -> linopy.Constraint:
-        """
-        Creates mutual exclusivity constraint for binary variables.
+        """Creates mutual exclusivity constraint for binary variables.
 
-        Mathematical formulation:
-            Σ(binary_vars[i]) ≤ tolerance  ∀t
+        Ensures at most one binary variable can be active (=1) at any time.
 
-        Ensures at most one binary variable can be 1 at any time.
-        Tolerance > 1.0 accounts for binary variable numerical precision.
+        Mathematical formulation:
+            Σᵢ binary_vars[i] ≤ tolerance  ∀t
 
         Args:
+            model: The submodel to add the constraint to
             binary_variables: List of binary variables that should be mutually exclusive
-            tolerance: Upper bound
-            short_name: Short name of the constraint
+            tolerance: Upper bound on the sum (default 1, allows slight numerical tolerance)
+            short_name: Short name for the constraint
 
         Returns:
-            variables: {} (no new variables created)
-            constraints: {'mutual_exclusivity': constraint}
+            Mutual exclusivity constraint
 
         Raises:
             AssertionError: If fewer than 2 variables provided or variables aren't binary
@@ -394,22 +505,22 @@ class BoundingPatterns:
     def basic_bounds(
         model: Submodel,
         variable: linopy.Variable,
-        bounds: tuple[TemporalData, TemporalData],
+        bounds: tuple[xr.DataArray, xr.DataArray],
         name: str = None,
     ) -> list[linopy.constraints.Constraint]:
-        """Create simple bounds.
-        variable ∈ [lower_bound, upper_bound]
+        """Creates simple lower and upper bounds for a variable.
 
-        Mathematical Formulation:
+        Mathematical formulation:
             lower_bound ≤ variable ≤ upper_bound
 
         Args:
-            model: The optimization model instance
+            model: The submodel to add constraints to
             variable: Variable to be bounded
             bounds: Tuple of (lower_bound, upper_bound) absolute bounds
+            name: Optional name prefix for constraints
 
         Returns:
-            List containing lower_bound and upper_bound constraints
+            List of [lower_constraint, upper_constraint]
         """
         if not isinstance(model, Submodel):
             raise ValueError('BoundingPatterns.basic_bounds() can only be used with a Submodel')
@@ -426,30 +537,29 @@ class BoundingPatterns:
     def bounds_with_state(
         model: Submodel,
         variable: linopy.Variable,
-        bounds: tuple[TemporalData, TemporalData],
-        variable_state: linopy.Variable,
+        bounds: tuple[xr.DataArray, xr.DataArray],
+        state: linopy.Variable,
         name: str = None,
     ) -> list[linopy.Constraint]:
-        """Constraint a variable to bounds, that can be escaped from to 0 by a binary variable.
-        variable ∈ {0, [max(ε, lower_bound), upper_bound]}
+        """Creates bounds controlled by a binary state variable.
 
-        Mathematical Formulation:
-            - variable_state * max(ε, lower_bound) ≤ variable ≤ variable_state * upper_bound
+        Variable is forced to 0 when state=0, bounded when state=1.
 
-        Use Cases:
-            - Investment decisions
-            - Unit commitment (on/off states)
+        Mathematical formulation:
+            state · max(ε, lower_bound) ≤ variable ≤ state · upper_bound
+
+        Where ε is a small positive number (CONFIG.Modeling.epsilon) ensuring
+        numerical stability when lower_bound is 0.
 
         Args:
-            model: The optimization model instance
+            model: The submodel to add constraints to
             variable: Variable to be bounded
-            bounds: Tuple of (lower_bound, upper_bound) absolute bounds
-            variable_state: Binary variable controlling the bounds
+            bounds: Tuple of (lower_bound, upper_bound) absolute bounds when state=1
+            state: Binary variable (0=force variable to 0, 1=allow bounds)
+            name: Optional name prefix for constraints
 
         Returns:
-            Tuple containing:
-                - variables (Dict): Empty dict
-                - constraints (Dict[str, linopy.Constraint]): 'ub', 'lb'
+            List of [lower_constraint, upper_constraint] (or [fix_constraint] if lower=upper)
         """
         if not isinstance(model, Submodel):
             raise ValueError('BoundingPatterns.bounds_with_state() can only be used with a Submodel')
@@ -457,14 +567,14 @@ class BoundingPatterns:
         lower_bound, upper_bound = bounds
         name = name or f'{variable.name}'
 
-        if np.allclose(lower_bound, upper_bound, atol=1e-10, equal_nan=True):
-            fix_constraint = model.add_constraints(variable == variable_state * upper_bound, name=f'{name}|fix')
+        if _xr_allclose(lower_bound, upper_bound):
+            fix_constraint = model.add_constraints(variable == state * upper_bound, name=f'{name}|fix')
             return [fix_constraint]
 
         epsilon = np.maximum(CONFIG.Modeling.epsilon, lower_bound)
 
-        upper_constraint = model.add_constraints(variable <= variable_state * upper_bound, name=f'{name}|ub')
-        lower_constraint = model.add_constraints(variable >= variable_state * epsilon, name=f'{name}|lb')
+        upper_constraint = model.add_constraints(variable <= state * upper_bound, name=f'{name}|ub')
+        lower_constraint = model.add_constraints(variable >= state * epsilon, name=f'{name}|lb')
 
         return [lower_constraint, upper_constraint]
 
@@ -473,29 +583,25 @@ class BoundingPatterns:
         model: Submodel,
         variable: linopy.Variable,
         scaling_variable: linopy.Variable,
-        relative_bounds: tuple[TemporalData, TemporalData],
+        relative_bounds: tuple[xr.DataArray, xr.DataArray],
         name: str = None,
     ) -> list[linopy.Constraint]:
-        """Constraint a variable by scaling bounds, dependent on another variable.
-        variable ∈ [lower_bound * scaling_variable, upper_bound * scaling_variable]
+        """Creates bounds scaled by another variable.
 
-        Mathematical Formulation:
-            scaling_variable * lower_factor ≤ variable ≤ scaling_variable * upper_factor
+        Variable is bounded relative to a scaling variable (e.g., flow rate relative to size).
 
-        Use Cases:
-            - Flow rates bounded by equipment capacity
-            - Production levels scaled by plant size
+        Mathematical formulation:
+            scaling_variable · lower_factor ≤ variable ≤ scaling_variable · upper_factor
 
         Args:
-            model: The optimization model instance
+            model: The submodel to add constraints to
             variable: Variable to be bounded
-            scaling_variable: Variable that scales the bound factors
-            relative_bounds: Tuple of (lower_factor, upper_factor) relative to scaling variable
+            scaling_variable: Variable that scales the bound factors (e.g., equipment size)
+            relative_bounds: Tuple of (lower_factor, upper_factor) relative to scaling_variable
+            name: Optional name prefix for constraints
 
         Returns:
-            Tuple containing:
-                - variables (Dict): Empty dict
-                - constraints (Dict[str, linopy.Constraint]): 'ub', 'lb'
+            List of [lower_constraint, upper_constraint] (or [fix_constraint] if lower=upper)
         """
         if not isinstance(model, Submodel):
             raise ValueError('BoundingPatterns.scaled_bounds() can only be used with a Submodel')
@@ -503,7 +609,7 @@ class BoundingPatterns:
         rel_lower, rel_upper = relative_bounds
         name = name or f'{variable.name}'
 
-        if np.allclose(rel_lower, rel_upper, atol=1e-10, equal_nan=True):
+        if _xr_allclose(rel_lower, rel_upper):
             return [model.add_constraints(variable == scaling_variable * rel_lower, name=f'{name}|fixed')]
 
         upper_constraint = model.add_constraints(variable <= scaling_variable * rel_upper, name=f'{name}|ub')
@@ -516,35 +622,35 @@ class BoundingPatterns:
         model: Submodel,
         variable: linopy.Variable,
         scaling_variable: linopy.Variable,
-        relative_bounds: tuple[TemporalData, TemporalData],
-        scaling_bounds: tuple[TemporalData, TemporalData],
-        variable_state: linopy.Variable,
+        relative_bounds: tuple[xr.DataArray, xr.DataArray],
+        scaling_bounds: tuple[xr.DataArray, xr.DataArray],
+        state: linopy.Variable,
         name: str = None,
     ) -> list[linopy.Constraint]:
-        """Constraint a variable by scaling bounds with binary state control.
+        """Creates bounds scaled by a variable and controlled by a binary state.
 
-        variable ∈ {0, [max(ε, lower_relative_bound) * scaling_variable, upper_relative_bound * scaling_variable]}
+        Variable is forced to 0 when state=0, bounded relative to scaling_variable when state=1.
 
-        Mathematical Formulation (Big-M):
-            (variable_state - 1) * M_misc + scaling_variable * rel_lower ≤ variable ≤ scaling_variable * rel_upper
-            variable_state * big_m_lower ≤ variable ≤ variable_state * big_m_upper
+        Mathematical formulation (Big-M):
+            (state - 1) · M_misc + scaling_variable · rel_lower ≤ variable ≤ scaling_variable · rel_upper
+            state · big_m_lower ≤ variable ≤ state · big_m_upper
 
         Where:
-            M_misc = scaling_max * rel_lower
-            big_m_upper = scaling_max * rel_upper
-            big_m_lower = max(ε, scaling_min * rel_lower)
+            M_misc = scaling_max · rel_lower
+            big_m_upper = scaling_max · rel_upper
+            big_m_lower = max(ε, scaling_min · rel_lower)
 
         Args:
-            model: The optimization model instance
+            model: The submodel to add constraints to
             variable: Variable to be bounded
-            scaling_variable: Variable that scales the bound factors
-            relative_bounds: Tuple of (lower_factor, upper_factor) relative to scaling variable
-            scaling_bounds: Tuple of (scaling_min, scaling_max) bounds of the scaling variable
-            variable_state: Binary variable for on/off control
+            scaling_variable: Variable that scales the bound factors (e.g., equipment size)
+            relative_bounds: Tuple of (lower_factor, upper_factor) relative to scaling_variable
+            scaling_bounds: Tuple of (scaling_min, scaling_max) bounds of the scaling_variable
+            state: Binary variable (0=force variable to 0, 1=allow scaled bounds)
             name: Optional name prefix for constraints
 
         Returns:
-            List[linopy.Constraint]: List of constraint objects
+            List of [scaling_lower, scaling_upper, binary_lower, binary_upper] constraints
         """
         if not isinstance(model, Submodel):
             raise ValueError('BoundingPatterns.scaled_bounds_with_state() can only be used with a Submodel')
@@ -556,60 +662,74 @@ class BoundingPatterns:
         big_m_misc = scaling_max * rel_lower
 
         scaling_lower = model.add_constraints(
-            variable >= (variable_state - 1) * big_m_misc + scaling_variable * rel_lower, name=f'{name}|lb2'
+            variable >= (state - 1) * big_m_misc + scaling_variable * rel_lower, name=f'{name}|lb2'
         )
         scaling_upper = model.add_constraints(variable <= scaling_variable * rel_upper, name=f'{name}|ub2')
 
         big_m_upper = rel_upper * scaling_max
         big_m_lower = np.maximum(CONFIG.Modeling.epsilon, rel_lower * scaling_min)
 
-        binary_upper = model.add_constraints(variable_state * big_m_upper >= variable, name=f'{name}|ub1')
-        binary_lower = model.add_constraints(variable_state * big_m_lower <= variable, name=f'{name}|lb1')
+        binary_upper = model.add_constraints(state * big_m_upper >= variable, name=f'{name}|ub1')
+        binary_lower = model.add_constraints(state * big_m_lower <= variable, name=f'{name}|lb1')
 
         return [scaling_lower, scaling_upper, binary_lower, binary_upper]
 
     @staticmethod
     def state_transition_bounds(
         model: Submodel,
-        state_variable: linopy.Variable,
-        switch_on: linopy.Variable,
-        switch_off: linopy.Variable,
+        state: linopy.Variable,
+        activate: linopy.Variable,
+        deactivate: linopy.Variable,
         name: str,
-        previous_state=0,
+        previous_state: float | xr.DataArray | None = 0,
         coord: str = 'time',
-    ) -> tuple[linopy.Constraint, linopy.Constraint, linopy.Constraint]:
-        """
-        Creates switch-on/off variables with state transition logic.
+    ) -> tuple[linopy.Constraint, linopy.Constraint | None, linopy.Constraint]:
+        """Creates state transition constraints for binary state variables.
+
+        Tracks transitions between active (1) and inactive (0) states using
+        separate binary variables for activation and deactivation events.
 
         Mathematical formulation:
-            switch_on[t] - switch_off[t] = state[t] - state[t-1]  ∀t > 0
-            switch_on[0] - switch_off[0] = state[0] - previous_state
-            switch_on[t] + switch_off[t] ≤ 1  ∀t
-            switch_on[t], switch_off[t] ∈ {0, 1}
+            activate[t] - deactivate[t] = state[t] - state[t-1]  ∀t > 0
+            activate[0] - deactivate[0] = state[0] - previous_state
+            activate[t] + deactivate[t] ≤ 1  ∀t
+            activate[t], deactivate[t] ∈ {0, 1}
+
+        Args:
+            model: The submodel to add constraints to
+            state: Binary state variable (0=inactive, 1=active)
+            activate: Binary variable for transitions from inactive to active (0→1)
+            deactivate: Binary variable for transitions from active to inactive (1→0)
+            name: Base name for constraints
+            previous_state: State value before first timestep (default 0). If None,
+                no initial constraint is added (relaxed initial state).
+            coord: Time dimension name (default 'time')
 
         Returns:
-            variables: {'switch_on': binary_var, 'switch_off': binary_var}
-            constraints: {'transition': constraint, 'initial': constraint, 'mutex': constraint}
+            Tuple of (transition_constraint, initial_constraint, mutex_constraint).
+            initial_constraint is None when previous_state is None.
         """
         if not isinstance(model, Submodel):
-            raise ValueError('ModelingPrimitives.state_transition_bounds() can only be used with a Submodel')
+            raise ValueError('BoundingPatterns.state_transition_bounds() can only be used with a Submodel')
 
         # State transition constraints for t > 0
         transition = model.add_constraints(
-            switch_on.isel({coord: slice(1, None)}) - switch_off.isel({coord: slice(1, None)})
-            == state_variable.isel({coord: slice(1, None)}) - state_variable.isel({coord: slice(None, -1)}),
+            activate.isel({coord: slice(1, None)}) - deactivate.isel({coord: slice(1, None)})
+            == state.isel({coord: slice(1, None)}) - state.isel({coord: slice(None, -1)}),
             name=f'{name}|transition',
         )
 
-        # Initial state transition for t = 0
-        initial = model.add_constraints(
-            switch_on.isel({coord: 0}) - switch_off.isel({coord: 0})
-            == state_variable.isel({coord: 0}) - previous_state,
-            name=f'{name}|initial',
-        )
+        # Initial state transition for t = 0 (skipped if previous_state is None for unconstrained)
+        if previous_state is not None:
+            initial = model.add_constraints(
+                activate.isel({coord: 0}) - deactivate.isel({coord: 0}) == state.isel({coord: 0}) - previous_state,
+                name=f'{name}|initial',
+            )
+        else:
+            initial = None
 
-        # At most one switch per timestep
-        mutex = model.add_constraints(switch_on + switch_off <= 1, name=f'{name}|mutex')
+        # At most one transition per timestep (mutual exclusivity)
+        mutex = model.add_constraints(activate + deactivate <= 1, name=f'{name}|mutex')
 
         return transition, initial, mutex
 
@@ -617,63 +737,66 @@ class BoundingPatterns:
     def continuous_transition_bounds(
         model: Submodel,
         continuous_variable: linopy.Variable,
-        switch_on: linopy.Variable,
-        switch_off: linopy.Variable,
+        activate: linopy.Variable,
+        deactivate: linopy.Variable,
         name: str,
         max_change: float | xr.DataArray,
         previous_value: float | xr.DataArray = 0.0,
         coord: str = 'time',
     ) -> tuple[linopy.Constraint, linopy.Constraint, linopy.Constraint, linopy.Constraint]:
-        """
-        Constrains a continuous variable to only change when switch variables are active.
+        """Constrains a continuous variable to only change during state transitions.
+
+        Ensures a continuous variable remains constant unless a transition event occurs.
+        Uses Big-M formulation to enforce change bounds.
 
         Mathematical formulation:
-            -max_change * (switch_on[t] + switch_off[t]) <= continuous[t] - continuous[t-1] <= max_change * (switch_on[t] + switch_off[t])  ∀t > 0
-            -max_change * (switch_on[0] + switch_off[0]) <= continuous[0] - previous_value <= max_change * (switch_on[0] + switch_off[0])
-            switch_on[t], switch_off[t] ∈ {0, 1}
+            -max_change · (activate[t] + deactivate[t]) ≤ continuous[t] - continuous[t-1] ≤ max_change · (activate[t] + deactivate[t])  ∀t > 0
+            -max_change · (activate[0] + deactivate[0]) ≤ continuous[0] - previous_value ≤ max_change · (activate[0] + deactivate[0])
+            activate[t], deactivate[t] ∈ {0, 1}
 
-        This ensures the continuous variable can only change when switch_on or switch_off is 1.
-        When both switches are 0, the variable must stay exactly constant.
+        Behavior:
+            - When activate=0 and deactivate=0: variable must stay constant
+            - When activate=1 or deactivate=1: variable can change within ±max_change
 
         Args:
             model: The submodel to add constraints to
-            continuous_variable: The continuous variable to constrain
-            switch_on: Binary variable indicating when changes are allowed (typically transitions to active state)
-            switch_off: Binary variable indicating when changes are allowed (typically transitions to inactive state)
-            name: Base name for the constraints
-            max_change: Maximum possible change in the continuous variable (Big-M value)
-            previous_value: Initial value of the continuous variable before first period
-            coord: Coordinate name for time dimension
+            continuous_variable: Continuous variable to constrain
+            activate: Binary variable for transitions from inactive to active (0→1)
+            deactivate: Binary variable for transitions from active to inactive (1→0)
+            name: Base name for constraints
+            max_change: Maximum allowed change (Big-M value, should be ≥ actual max change)
+            previous_value: Initial value before first timestep (default 0.0)
+            coord: Time dimension name (default 'time')
 
         Returns:
-            Tuple of constraints: (transition_upper, transition_lower, initial_upper, initial_lower)
+            Tuple of (transition_upper, transition_lower, initial_upper, initial_lower) constraints
         """
         if not isinstance(model, Submodel):
             raise ValueError('ModelingPrimitives.continuous_transition_bounds() can only be used with a Submodel')
 
-        # Transition constraints for t > 0: continuous variable can only change when switches are active
+        # Transition constraints for t > 0: continuous variable can only change when transitions occur
         transition_upper = model.add_constraints(
             continuous_variable.isel({coord: slice(1, None)}) - continuous_variable.isel({coord: slice(None, -1)})
-            <= max_change * (switch_on.isel({coord: slice(1, None)}) + switch_off.isel({coord: slice(1, None)})),
+            <= max_change * (activate.isel({coord: slice(1, None)}) + deactivate.isel({coord: slice(1, None)})),
             name=f'{name}|transition_ub',
         )
 
         transition_lower = model.add_constraints(
             -(continuous_variable.isel({coord: slice(1, None)}) - continuous_variable.isel({coord: slice(None, -1)}))
-            <= max_change * (switch_on.isel({coord: slice(1, None)}) + switch_off.isel({coord: slice(1, None)})),
+            <= max_change * (activate.isel({coord: slice(1, None)}) + deactivate.isel({coord: slice(1, None)})),
             name=f'{name}|transition_lb',
         )
 
         # Initial constraints for t = 0
         initial_upper = model.add_constraints(
             continuous_variable.isel({coord: 0}) - previous_value
-            <= max_change * (switch_on.isel({coord: 0}) + switch_off.isel({coord: 0})),
+            <= max_change * (activate.isel({coord: 0}) + deactivate.isel({coord: 0})),
             name=f'{name}|initial_ub',
         )
 
         initial_lower = model.add_constraints(
             -continuous_variable.isel({coord: 0}) + previous_value
-            <= max_change * (switch_on.isel({coord: 0}) + switch_off.isel({coord: 0})),
+            <= max_change * (activate.isel({coord: 0}) + deactivate.isel({coord: 0})),
             name=f'{name}|initial_lb',
         )