Combined Heat and Power (CHP)

documentation/features/scheduling.rst

@@ -5,8 +5,8 @@ Scheduling
 
 Scheduling is the main value-drive of FlexMeasures. We have two major types of schedulers built-in, for storage devices (usually batteries or hot water storage) and processes (usually in industry).
 
-FlexMeasures computes schedules for energy systems that consist of multiple devices that consume and/or produce electricity.
-We model a device as an asset with a power sensor, and compute schedules only for flexible devices, while taking into account inflexible devices.
+FlexMeasures computes schedules for energy systems that consist of multiple devices that consume and/or produce a commodity (e.g. electricity or gas).
+We model a device as an asset with a consumption/production sensor recording power values, and compute schedules only for flexible devices, while taking into account inflexible devices.
 
 .. contents::
     :local:
@@ -58,6 +58,9 @@ And if the asset belongs to a larger system (a hierarchy of assets), the schedul
    * - Field
      - Example value
      - Description
+   * - ``commodity``
+     - |COMMODITY_FLEX_CONTEXT.example|
+     - .. include:: ../_autodoc/COMMODITY_FLEX_CONTEXT.rst
    * - ``inflexible-device-sensors``
      - |INFLEXIBLE_DEVICE_SENSORS.example|
      - .. include:: ../_autodoc/INFLEXIBLE_DEVICE_SENSORS.rst
@@ -183,6 +186,9 @@ For more details on the possible formats for field values, see :ref:`variable_qu
    * - Field
      - Example value
      - Description
+   * - ``commodity``
+     - |COMMODITY_FLEX_MODEL.example|
+     - .. include:: ../_autodoc/COMMODITY_FLEX_MODEL.rst
    * - ``consumption``
      - |CONSUMPTION.example|
      - .. include:: ../_autodoc/CONSUMPTION.rst

flexmeasures/data/models/planning/__init__.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from collections import defaultdict
 from collections.abc import Iterable
 from dataclasses import dataclass, field
 from datetime import datetime, timedelta
@@ -53,6 +54,7 @@ class Scheduler:
 
     flex_model: list[dict] | dict | None = None
     flex_context: dict | None = None
+    stock_groups: dict | None = None
 
     fallback_scheduler_class: "Type[Scheduler] | None" = None
     info: dict | None = None
@@ -65,6 +67,103 @@ class Scheduler:
 
     return_multiple: bool = False
 
+    @staticmethod
+    def _build_stock_groups(flex_model: list[dict]) -> dict:
+        """
+        Build stock groups where devices sharing the same state-of-charge sensor are grouped together.
+        """
+        groups = defaultdict(list)
+        soc_usage = defaultdict(list)
+
+        for d, fm in enumerate(flex_model):
+            soc = fm.get("state_of_charge")
+            if soc is not None:
+                if hasattr(soc, "id"):
+                    soc_id = soc.id
+                elif isinstance(soc, dict) and "sensor" in soc:
+                    sensor = soc["sensor"]
+                    soc_id = sensor.id if hasattr(sensor, "id") else sensor
+                else:
+                    soc_id = soc
+
+                soc_usage[soc_id].append(d)
+
+        for soc_id, device_list in soc_usage.items():
+            groups[soc_id] = device_list
+
+        already_grouped = {dev for group in groups.values() for dev in group}
+        missing_soc_sensor_i = -len(flex_model)
+        for d in range(len(flex_model)):
+            if d not in already_grouped:
+                groups[missing_soc_sensor_i].append(d)
+                missing_soc_sensor_i += 1
+
+        return dict(groups)
+
+    @staticmethod
+    def _build_coupling_groups(
+        flex_model: list[dict],
+    ) -> dict[str, list[tuple[int, float]]]:
+        """Build coupling groups from the 'coupling' and 'coupling_coefficient' fields
+        of each device model.
+
+        Devices sharing the same coupling name form a coupling group.
+        The optimization model introduces a decision variable ``alpha`` per group per time
+        step, and constrains every device by ``P[d] == coeff_d * alpha``.
+
+        Coupling coefficients in flex-models are user-facing positive magnitudes.
+        The internal sign is inferred from directional capacities:
+
+        - ``consumption_capacity == 0`` -> output device -> internally negative coefficient
+        - ``production_capacity == 0`` -> input device -> internally positive coefficient
+
+        If neither direction is explicitly blocked, the coefficient stays positive.
+
+        Example — a CHP with 50% heat efficiency and 30% power efficiency:
+
+            [
+                {"coupling": "chp", "coupling_coefficient": 1.0},  # gas input (alpha = P_gas)
+                {"coupling": "chp", "coupling_coefficient": 0.5},  # heat output (50% of gas)
+                {"coupling": "chp", "coupling_coefficient": 0.3},  # power output (30% of gas)
+            ]
+
+        :param flex_model: List of deserialized device flex-model dicts.
+        :returns: Mapping from coupling-group name to a list of
+                  ``(device_index, internal_signed_coefficient)`` tuples suitable for
+                  passing to ``device_scheduler(coupling_groups=...)``. Returns an empty dict
+                  when no device defines a ``coupling`` field.
+        """
+
+        def _is_zero_capacity(value: Any) -> bool:
+            """Return True if the capacity value is numerically zero."""
+
+            if value is None:
+                return False
+
+            # Pint quantities expose ``magnitude``.
+            magnitude = getattr(value, "magnitude", value)
+            try:
+                return bool(np.isclose(float(magnitude), 0.0))
+            except (TypeError, ValueError):
+                return False
+
+        groups: dict[str, list[tuple[int, float]]] = defaultdict(list)
+        for d, fm in enumerate(flex_model):
+            coupling_name = fm.get("coupling")
+            if coupling_name is None:
+                continue
+            coefficient = abs(float(fm.get("coupling_coefficient", 1.0)))
+
+            is_output = _is_zero_capacity(fm.get("consumption_capacity"))
+            is_input = _is_zero_capacity(fm.get("production_capacity"))
+
+            if is_output and not is_input:
+                coefficient = -coefficient
+
+            groups[coupling_name].append((d, coefficient))
+
+        return dict(groups)
+
     def __init__(
         self,
         sensor: Sensor | None = None,  # deprecated
@@ -203,12 +302,19 @@ def collect_flex_config(self):
             # Listify the flex-model for the next code block, which actually does the merging with the db_flex_model
             flex_model = [flex_model]
 
+        # Find which asset is relevant for a given device model in the flex-model from the trigger message
         for flex_model_d in flex_model:
             asset_id = flex_model_d.get("asset")
             if asset_id is None:
-                sensor_id = flex_model_d["sensor"]
-                sensor = db.session.get(Sensor, sensor_id)
-                asset_id = sensor.asset_id
+                sensor_id = flex_model_d.get("sensor")
+                if sensor_id is not None:
+                    sensor = db.session.get(Sensor, sensor_id)
+                    asset_id = sensor.asset_id
+                else:
+                    soc_sensor_ref = flex_model_d.get("state-of-charge")
+                    if soc_sensor_ref is not None:
+                        soc_sensor = db.session.get(Sensor, soc_sensor_ref["sensor"])
+                        asset_id = soc_sensor.asset_id
             if asset_id in db_flex_model:
                 flex_model_d = {**db_flex_model[asset_id], **flex_model_d}
             amended_flex_model.append(flex_model_d)
@@ -289,14 +395,27 @@ class Commitment:
     quantity: pd.Series = 0
     upwards_deviation_price: pd.Series = 0
     downwards_deviation_price: pd.Series = 0
+    commodity: str | pd.Series | None = None
 
     def __post_init__(self):
         # device_group is a device→label lookup table, not a time series;
         # exclude it from automatic time-series index coercion.
+        if (
+            isinstance(self, FlowCommitment)
+            and isinstance(self.commodity, pd.Series)
+            and self.device is not None
+        ):
+            devices = extract_devices(self.device)
+            missing = set(devices) - set(self.commodity.index)
+            if missing:
+                raise ValueError(f"commodity mapping missing for devices: {missing}")
+
         series_attributes = [
             attr
             for attr, _type in self.__annotations__.items()
-            if _type == "pd.Series" and hasattr(self, attr) and attr != "device_group"
+            if _type == "pd.Series"
+            and hasattr(self, attr)
+            and attr not in ("device_group", "commodity")
         ]
         for series_attr in series_attributes:
             val = getattr(self, series_attr)
@@ -389,6 +508,10 @@ def _init_device_group(self):
                 range(len(devices)), index=devices, name="device_group"
             )
         else:
+            if not isinstance(self.device_group, pd.Series):
+                self.device_group = pd.Series(
+                    self.device_group, index=devices, name="device_group"
+                )
             # Validate custom grouping
             missing = set(devices) - set(self.device_group.index)
             if missing:
@@ -450,6 +573,19 @@ def to_frame(self) -> pd.DataFrame:
                 np.nan
             )  # EMS-level: handled by ems_flow_commitment_equalities
 
+        # commodity
+        if getattr(self, "commodity", None) is None:
+            df["commodity"] = None
+        elif isinstance(self.commodity, pd.Series):
+            # commodity is a device→commodity mapping, like device_group
+            if self.device is None:
+                df["commodity"] = None
+            else:
+                df["commodity"] = map_device_to_group(self.device, self.commodity)
+        else:
+            # scalar commodity
+            df["commodity"] = self.commodity
+
         return df