Value the state of charge at the end of the scheduling horizon

[Flix6x]

Summary

Adds a per-device soc-value-at-end flex-model field for storage devices: a marginal value (fixed quantity or sensor reference, e.g. "60 EUR/MWh" or {"sensor": 123}) assigned to energy left in storage at the end of the scheduling horizon.

Without it, the scheduler sees no benefit in ending the horizon with a non-zero state of charge, which leads to myopic behaviour: batteries and thermal buffers tend towards their minimum SoC at the end of the planning window.

Implementation

• Modern port of the device_future_reward tech spike on the feature/planning/relaxed-scheduler branch (commit "feature: final SoC has tiny value"), now expressed as a StockCommitment priced only in the final time slot (negative up/down deviation prices around a zero-SoC baseline give a linear reward on the final SoC).
• Field lives in the flex-model (per device) rather than the flex-context, because the appropriate value differs per device — e.g. a battery's charging efficiency (~1) vs. a heat pump's COP means the same stored MWh has different replacement value. A sensor reference lets an external system (e.g. a CEM or simulation runner) set the value dynamically.
• Added to both StorageFlexModelSchema and DBStorageFlexModelSchema, plus metadata/OpenAPI docs and the scheduling docs table.

Tests

New parametrized solver test on the day-2 price profile (expensive/cheap/expensive): with no or tiny soc-value-at-end the battery still sells out at the end; with a value above the highest price it ends the horizon full.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LQFkeGxDwErydUV5ZmHmki

[nhoening]

a battery's charging efficiency (~1) vs. a heat pump's COP means the same stored MWh has different replacement value.

but this is all information we know from the flex-model, so we can imagine pricing electricity per site - which would be easier.

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #33612127 | 📁 Comparing 95a01fb against latest (8d775f6)

  🔍 Preview build  

13 files changed · + 2 added · ± 11 modified

+ Added

• _autodoc/SOC_VALUE_AT_END.html
• _autosummary/flexmeasures.data.models.planning.devices.html

± Modified

• changelog.html
• genindex.html
• py-modindex.html
• _autosummary/flexmeasures.data.models.planning.html
• _autosummary/flexmeasures.data.models.planning.storage.html
• _autosummary/flexmeasures.data.schemas.generic_assets.html
• _autosummary/flexmeasures.data.schemas.scheduling.html
• _autosummary/flexmeasures.data.schemas.sensors.html
• api/v3_0.html
• dev/release_process.html
• and 1 more...

[Flix6x]

Added cross-validation of price units between flex-model and flex-context (815c7de):

• New PriceField subclass of VariableQuantityField marks monetary fields.
• FlexContextSchema's currency check now selects fields by isinstance(field, PriceField) instead of the *price name-suffix convention (same ten fields as before).
• On deserialize_flex_config, the storage scheduler validates each flex-model PriceField (currently soc-value-at-end, incl. sensor references via their unit) against the flex-context's shared_currency_unit, raising a marshmallow ValidationError with the usual example-unit hint — so a wrong currency or a mis-referenced sensor fails at trigger time rather than inside the queued job.
• Test: soc-value-at-end in USD against an EUR flex-context is rejected with the field name in the error.

[Flix6x]

a battery's charging efficiency (~1) vs. a heat pump's COP means the same stored MWh has different replacement value.

but this is all information we know from the flex-model, so we can imagine pricing electricity per site - which would be easier.

You are correct. But it is less flexible and I need to experiment with this for a project first. Not meant for merging soon. But I will definitely take your comment into account. I am also taking into account the option of moving this valuation entirely into FlexMeasures, to by default not entirely discount the future.

Regardless, I think having some prices in flex-models may be inescapable, so I factored out the refactoring that enables flex-model price fields in #2311 (and adds validation and test coverage for prices in custom commitments).