Feat: make soc-min and soc-max canonical with sensor defaults parked pending (#2395)

[BelhsanHmida]

Description

• Make soc-min and soc-max the canonical fields for fixed and dynamic storage SoC boundaries.
• Allow dynamic soc-min / soc-max values through sensor references and time-series specifications.
• Add a generic default field to sensor references for filling missing sensor values.
• Keep soc-minima and soc-maxima supported as deprecated legacy aliases.
• Reject ambiguous combinations of canonical and legacy dynamic fields.
• Preserve backwards compatibility for fixed SoC bounds and fixed-plus-legacy configurations.
• Make scalar soc-min / soc-max follow the default SoC relaxation behavior.
• Reject default: null.
• Update the API, UI, scheduling documentation, changelog, and OpenAPI specifications.
• Allow configuring sensor-reference fallbacks through the flex-model UI
• Add changelog entry

Look & Feel

N/A

Example API flex-model shape:

{
  "soc-at-start": "12 kWh",
  "soc-min": {
    "sensor": 300,
    "default": "10 kWh"
  },
  "soc-max": {
    "sensor": 301,
    "default": "25 kWh"
  },
  "power-capacity": "5 kW"
}

How to test

• pytest:

uv run pytest \
  flexmeasures/data/schemas/tests/test_sensor.py \
  flexmeasures/data/schemas/tests/test_scheduling.py \
  flexmeasures/data/models/planning/tests/test_storage.py \
  flexmeasures/data/models/planning/tests/test_utils_fresh_db.py \
  tests/documentation/test_openapi_spec.py

• Manual API-style check:
  Use a storage flex-model where soc-min and soc-max are dynamic sensor references with defaults:

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

Expected behavior: soc-min and soc-max are treated as dynamic SoC boundaries, missing sensor values are filled with the provided default values, default: null is rejected, and scalar soc-min / soc-max are soft by default when SoC relaxation is active.

Further Improvements

• Handle recurring SoC limits separately in Recurring SoC limits #2255.

Related Items

• Closes Make soc-minima and soc-maxima the default, simplifying usage #2251
• Related to Feat/retire fallback scheduler #2252
• Related follow-up: Recurring SoC limits #2255

---

Sign-off

• I agree to contribute to the project under Apache 2 License.
• To the best of my knowledge, the proposed patch is not based on code under GPL or other license that is incompatible with FlexMeasures

[nhoening]

We should mark the (user-facing) deprecation more explicitly (e.g. in the first words of this explanation).

Also, maybe even remove the user-facing documentation of it (e.g. on the feastures/scheduling) page. I would favor that last part because the list of documented fields is becoming long.

[BelhsanHmida]

Parking this for now the soc-minima/soc-maxima deprecation is one of the pieces held back pending #2395 (see split suggestion), so I'd rather not word the deprecation notice before we know whether the deprecation stands. Noted for when this comes back including your point about trimming the field list on the scheduling page, which I think is right regardless.

[Flix6x]

Flagging #2395 here, because it has a bearing on the part of this PR that changes SoC constraint hardness.

The short version: stocks are the half of the flex-model that already separates physics from preference cleanly, and it is worth preserving that. soc-min / soc-max act as a hard envelope that both fills gaps and clips the dynamic bounds into itself (in add_storage_constraints), while soc-minima / soc-maxima become StockCommitments with the hard constraint dropped. Flows lack that separation, which is what #2395 is about.

So my suggestion is to split this PR:

Land now — the default field on sensor references, and the docs / OpenAPI / UI work. These are uncontroversial and answer most of #2251.

Hold — the soc-min → soc_minima folding, the scalar softening (_relax_scalar_soc_minimum / _relax_scalar_soc_maximum), and the deprecation labelling of soc-minima / soc-maxima. Together these collapse two tiers into one, and I would rather settle the hardness question across the whole flex-model first.

One point that is worth making regardless of how the hardness question lands, because it is a silent behaviour change:

default is not soc-min. A default fills the slots where the sensor is silent — the fillna. soc-min additionally clips, including the slots where the sensor did speak. So a sensor reporting a bad value (a unit slip, a negative SoC) is clamped today and would not be after the fold. That loss is independent of the hard-versus-soft question and would need addressing either way.

Apologies for the moving target here — this is a design question that took a few rounds to pin down, and none of it reflects on the implementation work, which is solid.