feat: support a default fallback on sensor references

documentation/api/change_log.rst

@@ -10,6 +10,7 @@ v3.0-32 | July XX, 2026
 - API endpoints are now rate-limited. A request which exceeds a limit is answered with a ``429 (Too Many Requests)`` status code and a ``Retry-After`` header stating how many seconds to wait. Responses also carry ``X-RateLimit-*`` headers, describing the limit that applied, how much of it is left, and when it resets. A stricter limit applies to ``POST /assets/<id>/schedules/trigger``, ``POST /sensors/<id>/schedules/trigger`` and ``POST /sensors/<id>/forecasts/trigger`` than to other endpoints; the health endpoints are exempt. Per-account overrides are set by assigning the account a plan (a ``Plan`` database row), rather than through an account attribute.
 - Introduced the ``inflexible-consumption`` and ``inflexible-production`` flex-context fields, which make explicit how the sign of each inflexible device's power data should be read: positive values denote consumption resp. production. Each entry is a sensor reference (``{"sensor": <id>}``), optionally with source filters (``source-types``, ``exclude-source-types``, ``sources``, ``source-account``). Deprecated the ``inflexible-device-sensors`` field (a list of bare sensor IDs, whose sign convention is read from each sensor's ``consumption_is_positive`` attribute); it remains supported, but cannot be combined with the new fields in one flex-context.
 - Added a ``role`` query parameter to ``GET /api/v3_0/accounts`` for filtering accessible organisations by account role.
+- Sensor references on variable-quantity flex-model and flex-context fields (such as ``soc-minima``, ``soc-maxima``, the capacity fields and the price fields) may now include a ``default`` fallback quantity, e.g. ``{"sensor": 50, "default": "0 kWh"}``. It fills the time slots for which the referenced sensor holds no value. Note that this fills *every* such slot, so a sensor recording only occasional setpoints becomes densely constrained. The field is not (yet) applied to sensor references on ``inflexible-consumption``/``inflexible-production`` or to forecaster regressors. Take particular care with a fallback of ``0`` on a ``consumption-capacity`` or ``production-capacity``: if the sensor holds no value for the whole scheduling window, the resulting all-zero capacity is read as a physical statement about the device and enforced strictly (see :ref:`the flex-model capacity fields <flex_models_and_schedulers>`), rather than as a limit that may be breached at a price.
 - Extended ``GET /api/v3_0/jobs/<uuid>`` with a ``result`` field containing ``unresolved`` and ``resolved`` arrays, each keyed by asset ID. For scheduling jobs, this surfaces soft state-of-charge constraint analysis: ``soc-minima`` and ``soc-maxima`` violations (with a ``violation`` magnitude) or satisfied constraints (with a ``margin`` headroom). Both arrays are empty when no SoC constraints were defined.
 - **Field canonicalization** for background job tracking:
   * The ``job`` field is now the canonical way to identify background jobs returned by `/sensors/<id>/schedules/trigger`, `/assets/<id>/schedules/trigger`, and `/sensors/<id>/forecasts/trigger` endpoints. If applicable, the triggered response now also returns a ``results-url`` pointing to the sensor-specific results endpoint, alongside the generic ``job-url``.

documentation/changelog.rst

@@ -58,6 +58,7 @@ New features
 * Commodity contexts that omit grid-connection fields (prices and site capacities) now get smart defaults instead of failing or silently leaving the grid unconstrained — for instance, a bare ``{"commodity": "gas"}`` is treated as having no grid connection; see :ref:`commodity_context_defaults` for the full rules [see `PR #2272 <https://www.github.com/FlexMeasures/flexmeasures/pull/2272>`_]
 * CLI support for adding/editing account attributes [see `PR #2242 <https://www.github.com/FlexMeasures/flexmeasures/pull/2242>`_]
 * Improve chart axis domain for event values not around zero, with a per-sub-chart ``y-axis`` option in ``sensors_to_show`` (default ``zero``, which pads the axis out to include zero) that can be set to ``data`` to fit a sub-chart's y-axis to the values shown, to an explicit ``[min, max]`` domain that the axis will cover at least (expanding to fit data beyond it), or to a strict ``{"min": min, "max": max}`` domain that the axis will never exceed (clamping data beyond it, with a warning when that happens), editable from the graph editor [see `PR #2244 <https://www.github.com/FlexMeasures/flexmeasures/pull/2244>`_]
+* Sensor references on variable-quantity flex-model and flex-context fields now accept a ``default`` fallback quantity, e.g. ``{"sensor": 50, "default": "0 kWh"}``, filling the time slots for which the referenced sensor holds no value; also settable from the flex-model UI. Note that a fallback of ``0`` on a directional capacity makes that capacity a hard bound wherever the sensor is silent for the whole scheduling window [see `PR #2405 <https://www.github.com/FlexMeasures/flexmeasures/pull/2405>`_]
 * Breaking behaviour change: the built-in storage fallback scheduler has been retired, so an infeasible storage problem now fails with its failure reason instead of silently saving a fallback schedule; ``FLEXMEASURES_FALLBACK_REDIRECT`` is now only relevant for custom schedulers that define a fallback scheduler [see `PR #2252 <https://www.github.com/FlexMeasures/flexmeasures/pull/2252>`_]
 * Breaking behaviour change: the specific ``relax-soc-constraints`` and ``relax-site-capacity-constraints`` flags now follow the umbrella ``relax-constraints`` flag (which now defaults to true, see above) unless they are set explicitly, in which case they take precedence for their respective constraints, in either direction (previously, these flags were independent opt-ins defaulting to false); also fixed: explicitly set breach prices (including zero prices) are no longer overwritten with default breach prices when relaxation is enabled, and when only one breach price of the ``soc-minima``/``soc-maxima`` (or site capacity) pair is set explicitly, the other one still gets its default [see `PR #2252 <https://www.github.com/FlexMeasures/flexmeasures/pull/2252>`_]
 * Extended ``GET /api/v3_0/jobs/<uuid>`` with a ``result`` field containing ``unresolved`` and ``resolved`` soft state-of-charge constraint analysis (``soc-minima``/``soc-maxima`` violations or satisfied constraints, keyed by asset ID) for scheduling jobs; both arrays are empty when no SoC constraints were defined [see `PR #2072 <https://www.github.com/FlexMeasures/flexmeasures/pull/2072>`_]

flexmeasures/data/models/planning/tests/test_utils_fresh_db.py

@@ -10,6 +10,7 @@
 from flexmeasures.data.schemas.sensors import SensorReference
 from flexmeasures.data.models.planning.storage import StorageScheduler
 from flexmeasures.data.models.planning.utils import get_series_from_quantity_or_sensor
+from flexmeasures.utils.unit_utils import ur
 
 
 def test_get_series_from_sensor_reference_source_filter_integration(fresh_db):
@@ -88,6 +89,48 @@ def test_get_series_from_sensor_reference_source_filter_integration(fresh_db):
     assert result_forecaster.iloc[0] == pytest.approx(200.0)
 
 
+def test_get_series_from_sensor_reference_default_fills_missing_values(fresh_db):
+    """A SensorReference default fills query slots with no matching sensor belief."""
+    query_window = (
+        pd.Timestamp("2025-06-01 08:00:00+02:00"),
+        pd.Timestamp("2025-06-01 08:30:00+02:00"),
+    )
+    source = DataSource(name="test-default-source", type="scheduler")
+    fresh_db.session.add(source)
+    asset_type = GenericAssetType(name="test-asset-type-default")
+    fresh_db.session.add(asset_type)
+    asset = GenericAsset(name="test-asset-default", generic_asset_type=asset_type)
+    fresh_db.session.add(asset)
+    sensor = Sensor(
+        name="test-sensor-default",
+        generic_asset=asset,
+        event_resolution=timedelta(minutes=15),
+        unit="MW",
+    )
+    fresh_db.session.add(sensor)
+    fresh_db.session.flush()
+    fresh_db.session.add(
+        TimedBelief(
+            event_start=query_window[0],
+            belief_horizon=timedelta(0),
+            event_value=0.1,
+            source=source,
+            sensor=sensor,
+        )
+    )
+    fresh_db.session.commit()
+
+    result = get_series_from_quantity_or_sensor(
+        variable_quantity=SensorReference(sensor=sensor, default=ur.Quantity("1 MW")),
+        query_window=query_window,
+        resolution=sensor.event_resolution,
+        unit="kW",
+        as_instantaneous_events=False,
+    )
+
+    assert list(result) == pytest.approx([100.0, 1000.0])
+
+
 def test_get_series_from_sensor_reference_sources_filter_integration(fresh_db):
     """A :class:`SensorReference` with ``sources`` returns only beliefs from the specified source.
 

flexmeasures/data/models/planning/utils.py

@@ -326,6 +326,14 @@ def get_series_from_quantity_or_sensor(
         time_series = convert_units(
             time_series, variable_quantity.unit, unit, resolution
         )
+        if variable_quantity.default is not None:
+            default_value = convert_units(
+                variable_quantity.default.magnitude,
+                str(variable_quantity.default.units),
+                unit,
+                resolution,
+            )
+            time_series = time_series.fillna(default_value)
     elif isinstance(variable_quantity, Sensor):
         bdf: tb.BeliefsDataFrame = TimedBelief.search(
             variable_quantity,