feat: support a default fallback on sensor references

[BelhsanHmida]

Description

Split out of #2267 on @Flix6x's suggestion, so the uncontroversial half can land while the SoC constraint hardness question is settled across the whole flex-model (see #2395).

• A sensor reference on a variable-quantity flex-model or flex-context field (soc-minima, soc-maxima, the capacity fields, the price fields) may now carry a default fallback quantity, e.g. {"sensor": 50, "default": "0 kWh"}.
• Settable from the flex-model UI.
• Documented that a default fills every empty slot, so a sensor recording only occasional setpoints becomes densely constrained.
• Omit default from serialized sensor references when unset, instead of emitting default: null (which is not valid input on the way back in, and broke the forecaster config round-trips).
• Changelog + API changelog + OpenAPI specs updated.

Not included, and still parked on feat/dynamic-soc-bounds-defaults (#2267) pending #2395: the soc-min → soc_minima folding, the scalar softening (_relax_scalar_soc_minimum / _relax_scalar_soc_maximum), the soc-minima / soc-maxima deprecation labelling, and the soc_min / soc_max field-type change.

Look & Feel

The flex-model sensor picker gains an optional "Default fallback" input.

How to test

pytest flexmeasures/data/schemas/tests/test_sensor.py \
  flexmeasures/data/schemas/tests/test_scheduling.py \
  flexmeasures/data/schemas/tests/test_forecasting.py \
  flexmeasures/data/tests/test_forecasting_pipeline.py \
  flexmeasures/data/models/planning/tests/test_utils_fresh_db.py

Also ran the full CI-equivalent suite (--doctest-modules, same ignores as the workflow): 1923 passed, with only failures that reproduce identically on main (test_closest_sensor[1]/[3], and test_numerical_errors[cbc] where the CBC solver binary is absent locally).

Manual check — a sensor reference with a fallback in a storage flex-model:

{
  "flex-model": {
    "soc-at-start": "12 kWh",
    "soc-minima": {"sensor": 300, "default": "10 kWh"},
    "power-capacity": "5 kW"
  }
}

Slots where sensor 300 has no value are filled with 10 kWh.

Related Items

• Answers most of Make soc-minima and soc-maxima the default, simplifying usage #2251
• Split out of Feat: make soc-min and soc-max canonical with sensor defaults parked pending (#2395) #2267 (which stays open for the parked SoC work)
• Context: production-capacity: 0 means two different things, and the rule that separates them is unwritten #2395

Sign-off

• I confirm that my contribution follows the contribution guidelines.
• I certify that I wrote the contribution or otherwise have the right to submit it under the project license.

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #33965229 | 📁 Comparing ec5fe72 against latest (f3319e0)

  🔍 Preview build  

31 files changed · + 1 added · ± 30 modified

+ Added

• _autosummary/flexmeasures.utils.sentry_utils.html

± Modified

• changelog.html
• configuration.html
• genindex.html
• index.html
• py-modindex.html
• _autodoc/CONSUMPTION_CAPACITY.html
• _autodoc/PRODUCTION_CAPACITY.html
• _autodoc/RELAX_CAPACITY_CONSTRAINTS.html
• _autodoc/RELAX_CONSTRAINTS.html
• _autodoc/RELAX_SITE_CAPACITY_CONSTRAINTS.html
• and 20 more...

[BelhsanHmida]

Manual end-to-end check. I drove the real StorageScheduler with a soc-minima sensor holding a value for exactly one slot of the horizon (40 kWh at 6am), with prices set expensive for the first 4 hours and cheap afterwards — so the scheduler has every incentive to stay empty early, and any early charging must come from a constraint rather than arbitrage.

flex-model	SoC over the first 2 hours
"soc-minima": {"sensor": X}	0.0 MWh throughout
"soc-minima": {"sensor": X, "default": "20 kWh"}	0.02 MWh throughout

So the fallback fills the slots the sensor leaves silent, and the solver honours it as a floor, paying the high price to hold it. Also verified that a reference without a default no longer serializes default: null (the bug that was failing the forecaster config round-trips).

Known gap — follow-up needed

default is declared on the shared SensorReferenceSchema, so the API accepts it on every sensor reference, but it is only applied in get_series_from_quantity_or_sensor. Two other consumers unpack a SensorReference, read its source filters, and ignore default entirely:

• get_power_values (flexmeasures/data/models/planning/utils.py) — inflexible devices
• _regressor_sensor_and_source_filters (flexmeasures/data/models/forecasting/pipelines/base.py) — forecaster regressors

This is visible in the generated spec: the InflexibleDevice component now advertises default, where setting it does nothing and raises no error.

@Flix6x I've scoped the changelog and the field description to say where the field actually takes effect, rather than implement the missing paths in this PR. Opening a follow-up issue to apply default in those two paths happy to take it, or to fold it in here if you'd rather it land together.

[BelhsanHmida]

@Flix6x i rebased the pr to main

[Flix6x]

Reviewed and approved — thanks for splitting this out, it lands cleanly. I pushed one commit rather than leaving review notes, since both parts are small and mechanical.

1. Restored the specs version to 1.0.0. The previous revision had "version": "0.33.2" in openapi-specs.json. That is not something you chose: generate_open_api_specs reads it from the installed FlexMeasures and truncates to major.minor.patch (flexmeasures/api/v3_0/__init__.py), so it records whatever version the generating environment had installed — a stale editable install in this case. Regenerating from an up-to-date environment puts it back. Worth a uv sync before regenerating the specs in future, or the version will keep drifting back.

2. Documented one interaction with #2345, which landed after this branch was opened.

Since #2345, a consumption-capacity or production-capacity that is zero throughout the scheduling window is read as a statement about what the device physically cannot do, and is enforced strictly — it is no longer breachable at a price. A default fills every slot the referenced sensor leaves empty, as you already document. Put together:

"production-capacity": {"sensor": 42, "default": "0 kW"}

against a sensor that is silent for the whole window yields an all-zero capacity, which becomes a hard bound. That is a reasonable thing for someone to write meaning "assume no export capability when I have no data", and they would not expect it to become uncrossable. So the caveat is now in three places: the default field description (and therefore OpenAPI), the API changelog entry, and the changelog entry.

Nothing to change in your implementation — this is a documentation consequence of two features meeting, and the note belongs with default because that is where a user meets it.

For context on the wider question of why a directional capacity carries two meanings at all, and what would let us stop inferring physics from the value 0, see #2395. Your parked work on #2267 is waiting on the same decision.