Backport PR #1710: Fix/better documentation for price incompatibilities (#1710)

* docs: fix price units in examples

Signed-off-by: F.N. Claessen <felix@seita.nl>

* feat: improve error message in case of incompatible price units

Signed-off-by: F.N. Claessen <felix@seita.nl>

* docs: changelog entry

Signed-off-by: F.N. Claessen <felix@seita.nl>

* fix: update test case

Signed-off-by: F.N. Claessen <felix@seita.nl>

* fix: type annotation

Signed-off-by: F.N. Claessen <felix@seita.nl>

* feat: test VariableQuantityField._get_unit

Signed-off-by: F.N. Claessen <felix@seita.nl>

* fix: xfail test cases for serialized variable quantities

Signed-off-by: F.N. Claessen <felix@seita.nl>

* feat: _get_original_unit

Signed-off-by: F.N. Claessen <felix@seita.nl>

* fix: error message

Signed-off-by: F.N. Claessen <felix@seita.nl>

* refactor: a single _get_unit method returning either the original unit from the serialized variable quantity or the unit from the deserialized variable quantity

Signed-off-by: F.N. Claessen <felix@seita.nl>

* Revert "refactor: a single _get_unit method returning either the original unit from the serialized variable quantity or the unit from the deserialized variable quantity"

This reverts commit 66885ab.

* docs: keep clarifying inline comment

Signed-off-by: F.N. Claessen <felix@seita.nl>

---------

Signed-off-by: F.N. Claessen <felix@seita.nl>
(cherry picked from commit c614bdb)

Author: Flix6x

documentation/changelog.rst

@@ -10,7 +10,7 @@ v0.28.1 | September XX, 2025
 Bugfixes
 -----------
 * Fix schema validation in ``PATCH /assets/(id)`` [see `PR #1711 <https://www.github.com/FlexMeasures/flexmeasures/pull/1711>`_]
-
+* Fixed example values for peak pricing and improved error message for incompatible price units set in the ``flex-context`` [see `PR #1710 <https://github.com/FlexMeasures/flexmeasures/pull/1710>`_]
 
 v0.28.0 | September 10, 2025
 ============================

documentation/features/scheduling.rst

@@ -111,14 +111,14 @@ And if the asset belongs to a larger system (a hierarchy of assets), the schedul
      - The price of breaching the ``site-production-capacity``, useful to treat ``site-production-capacity`` as a soft constraint but still make the scheduler attempt to respect it.
        Can be (a sensor recording) contractual penalties, but also a theoretical penalty just to allow the scheduler to breach the production capacity, while influencing how badly breaches should be avoided. [#penalty_field]_ [#breach_field]_
    * - ``site-peak-consumption-price``
-     - ``"260 EUR/MWh"``
+     - ``"260 EUR/MW"``
      - Consumption peaks above the ``site-peak-consumption`` are penalized against this per-kW price. [#penalty_field]_
    * - ``site-peak-production``
      - ``{"sensor": 8}``
      - Current peak production.
        Costs from peaks below it are considered sunk costs. Default to 0 kW.
    * - ``site-peak-production-price``
-     - ``"260 EUR/MWh"``
+     - ``"260 EUR/MW"``
      - Production peaks above the ``site-peak-production`` are penalized against this per-kW price. [#penalty_field]_
    * - ``soc-minima-breach-price``
      - ``"120 EUR/kWh"``

flexmeasures/data/schemas/scheduling/__init__.py

@@ -169,8 +169,8 @@ def set_default_breach_prices(
             )
         return data
 
-    @validates_schema
-    def check_prices(self, data: dict, **kwargs):
+    @validates_schema(pass_original=True)
+    def check_prices(self, data: dict, original_data: dict, **kwargs):
         """Check assumptions about prices.
 
         1. The flex-context must contain at most 1 consumption price and at most 1 production price field.
@@ -221,7 +221,7 @@ def check_prices(self, data: dict, **kwargs):
         # make sure that the prices fields are valid price units
 
         # All prices must share the same unit
-        data = self._try_to_convert_price_units(data)
+        data = self._try_to_convert_price_units(data, original_data)
         shared_currency = ur.Quantity(data["shared_currency_unit"])
 
         # Fill in default soc breach prices when asked to relax SoC constraints, unless already set explicitly.
@@ -265,7 +265,7 @@ def check_prices(self, data: dict, **kwargs):
 
         return data
 
-    def _try_to_convert_price_units(self, data):
+    def _try_to_convert_price_units(self, data: dict, original_data: dict):
         """Convert price units to the same unit and scale if they can (incl. same currency)."""
 
         shared_currency_unit = None
@@ -287,10 +287,13 @@ def _try_to_convert_price_units(self, data):
                     previous_field_name = price_field.data_key
                 if not units_are_convertible(currency_unit, shared_currency_unit):
                     field_name = price_field.data_key
-                    raise ValidationError(
-                        f"Prices must share the same monetary unit. '{field_name}' uses '{currency_unit}', but '{previous_field_name}' used '{shared_currency_unit}'.",
-                        field_name=field_name,
+                    original_price_unit = price_field._get_original_unit(
+                        original_data[field_name], data[field]
                     )
+                    error_message = f"Invalid unit. A valid unit would be, for example, '{shared_currency_unit + price_field.to_unit}' (this example uses '{shared_currency_unit}', because '{previous_field_name}' used that currency). However, you passed an incompatible price ('{original_price_unit}') for the '{field_name}' field."
+                    if shared_currency_unit not in price_unit:
+                        error_message += f" Also note that all prices in the flex-context must share the same currency unit (in this case: '{shared_currency_unit}')."
+                    raise ValidationError(error_message, field_name=field_name)
         if shared_currency_unit is not None:
             data["shared_currency_unit"] = shared_currency_unit
         elif sensor := data.get("consumption_price_sensor"):

flexmeasures/data/schemas/sensors.py

@@ -411,8 +411,27 @@ def convert(self, value, param, ctx, **kwargs):
 
         return super().convert(_value, param, ctx, **kwargs)
 
-    def _get_unit(self, variable_quantity: ur.Quantity | list[dict | Sensor]) -> str:
-        """Obtain the unit from the variable quantity."""
+    def _get_original_unit(
+        self,
+        serialized_variable_quantity: str | list[dict] | dict,
+        deserialized_variable_quantity: ur.Quantity | list[dict] | Sensor,
+    ) -> str:
+        """Obtain the original unit from the still serialized variable quantity."""
+        if isinstance(serialized_variable_quantity, str):
+            unit = str(ur.Quantity(serialized_variable_quantity).units)
+        elif isinstance(serialized_variable_quantity, list):
+            unit = str(ur.Quantity(serialized_variable_quantity[0]["value"]).units)
+        elif isinstance(serialized_variable_quantity, dict):
+            # use deserialized quantity to avoid another Sensor query; the serialized quantity only has the sensor ID
+            unit = deserialized_variable_quantity.unit
+        else:
+            raise NotImplementedError(
+                f"Unexpected type '{type(serialized_variable_quantity)}' for serialized_variable_quantity describing '{self.data_key}': {serialized_variable_quantity}."
+            )
+        return unit
+
+    def _get_unit(self, variable_quantity: ur.Quantity | list[dict] | Sensor) -> str:
+        """Obtain the unit from the (deserialized) variable quantity."""
         if isinstance(variable_quantity, ur.Quantity):
             unit = str(variable_quantity.units)
         elif isinstance(variable_quantity, list):

flexmeasures/data/schemas/tests/test_scheduling.py

@@ -13,7 +13,7 @@
 from flexmeasures.data.schemas.scheduling.storage import (
     StorageFlexModelSchema,
 )
-from flexmeasures.data.schemas.sensors import TimedEventSchema
+from flexmeasures.data.schemas.sensors import TimedEventSchema, VariableQuantityField
 
 
 @pytest.mark.parametrize(
@@ -242,7 +242,9 @@ def load_schema():
                 "consumption-price": "1 KRW/MWh",
                 "site-peak-production-price": "1 EUR/MW",
             },
-            {"site-peak-production-price": "Prices must share the same monetary unit."},
+            {
+                "site-peak-production-price": "all prices in the flex-context must share the same currency unit"
+            },
         ),
         (
             {
@@ -501,3 +503,34 @@ def test_db_flex_context_schema(
             )
     else:
         schema.load(flex_context)
+
+
+@pytest.mark.parametrize(
+    ["variable_quantity", "expected_unit"],
+    [
+        ("1 kWh", "kWh"),
+        (
+            [{"start": "2025-09-17T00:00+02", "duration": "PT3H", "value": "1 kWh"}],
+            "kWh",
+        ),
+        ({"sensor": "epex_da"}, "EUR/MWh"),
+    ],
+)
+@pytest.mark.parametrize("deserialized", [True, False])
+def test_get_variable_quantity_unit(
+    setup_markets, variable_quantity, expected_unit: str, deserialized: bool
+):
+    # Use sensor name to look up sensor ID from fixture
+    if isinstance(variable_quantity, dict):
+        variable_quantity = variable_quantity.copy()
+        variable_quantity["sensor"] = setup_markets[variable_quantity["sensor"]].id
+
+    field = VariableQuantityField("/1")  # we use to_unit="/1" here to allow any unit
+    deserialized_variable_quantity = field.deserialize(variable_quantity)
+    if deserialized:
+        assert field._get_unit(deserialized_variable_quantity) == expected_unit
+    else:
+        assert (
+            field._get_original_unit(variable_quantity, deserialized_variable_quantity)
+            == expected_unit
+        )