Feat/offtick soc projection

[BelhsanHmida]

Description

• Project off-tick storage SoC constraints onto the scheduling ticks using charge/discharge capacity, instead of blindly flooring timed soc-targets, soc-minima, and soc-maxima.
• Preserve original SoC event times during storage flex-model schema deserialization so scheduler logic can interpret the user’s intent.
• Automatically enable relax-soc-constraints when off-tick SoC constraints are submitted, so generated/adjusted constraints can be softened safely.
• Added tests for off-tick SoC target projection and automatic SoC constraint relaxation.
• add changelog entry.

How to test

pytest flexmeasures/api/v3_0/tests/test_sensor_schedules.py flexmeasures/data/schemas/tests/test_scheduling.py flexmeasures/data/models/planning/tests/test_storage.py -q

Manual test:

• Trigger a storage schedule with a 15-minute resolution and an off-tick soc-target, e.g. 17:12.
• Use 0.04 MW charging capacity and target 1 MWh.
• Verify the scheduler does not floor the target to 17:00, but projects it onto the scheduling ticks as an adjusted previous-tick bound and a next-tick target.
• Verify off-tick SoC constraints enable relax-soc-constraints.

Projection policy

The scheduler can enforce SoC constraints only on its scheduling ticks. For point-like off-tick SoC events:

• soc-targets are projected to an exact target on the next scheduling tick, with capacity-adjusted lower and upper bounds on the previous tick.
• soc-minima are projected as lower bounds on the surrounding ticks, adjusted by reachable charge/discharge capacity.
• soc-maxima are projected as upper bounds on the surrounding ticks, adjusted by reachable charge/discharge capacity.
• If multiple projected lower bounds land on the same tick, the stricter lower bound is kept.
• If multiple projected upper bounds land on the same tick, the stricter upper bound is kept.

Related Items

Follow-up to PR #2146 review discussion around off-tick storage SoC constraints.

Sign-off

• I agree to license my contributions under the project’s license.
• I signed off my commits.

[Flix6x]

Thanks @BelhsanHmida — the projection policy is sound and well-tested, and the target projection faithfully generalizes the original recipe in #10 (comment). I reviewed the branch in depth and, rather than a long list of change requests, pushed fixes for what I found directly onto your branch (17 commits, d255bd3c5..03fd551b0, plus a merge of main to pick up the OpenAPI hook fix). Summary of what was addressed:

Correctness issues found in review

1. Projection ran only in the hard-constraint path — but with breach prices set (which the auto-enabled relaxation guarantees), soc-minima/soc-maxima were converted to soft StockCommitments (and nulled) before the projection ran. So off-tick minima/maxima reached the commitment builder unprojected, while target-derived bounds were applied as hard constraints despite relaxation. Fixed by projecting right after device capacities are known, before the soft/hard split (8ba7a524c).
2. Off-tick targets near the schedule end were silently dropped: possibly_extend_end extended self.end to the raw off-tick time, so the projected next-tick target fell beyond the schedule end and was disregarded. The extension is now ceiled to the scheduling resolution (54c576bc4).
3. An explicit relax-soc-constraints: False was silently overridden; it is now respected, with a logged warning (d2360b515).
4. Projected bounds were silently dropped when the counterpart field is a sensor/series/quantity; now logged (dc57d1563). Same for off-tick events that match no tick when projection is opted out via floor_datetimes_to_resolution=False (3576a1ff3).
5. The flooring machinery in StorageFlexModelSchema was inert: marshmallow resolves fields from class-level declared fields, so the instance-level soc field re-creations (carrying flooring_resolution and the timezone override) never took effect. Removed, with the intended timezone/soc-unit overrides realized via setattr on the bound fields (2e49f87eb).

Refinements

• Projection logic moved to a dedicated module planning/soc_projection.py, with docstrings, and the rule-table indirection replaced by explicit projections (d255bd3c5, 289a5ccf2, ca83e9f82).
• Reachable energy is now efficiency-aware: charging moves the stock at P × charging_efficiency (which can exceed 1, e.g. a heat pump's COP), discharging at P / discharging_efficiency (cd0b69ffb).
• Off-tick detection moved from the schema's pre_load (guessed resolution, mutable schema state) into the scheduler, using its actual resolution (eafa169cf).
• Auto-relaxation is now scoped to the devices that actually use off-tick constraints (tracked by power sensor) when the user's flex-context didn't already soften SoC constraints — other devices keep their hard constraints (f0a5cc203). Follow-up to key this on stock groups instead is parked on Share storage-efficiency per stock group and index solver stock by group #2325.
• Off-tick soc-at-start support (per the issue API usage with datetimes that aren't at midnight or a multiple of the sensor resolution afterwards #10 recipe): when the starting SoC resolves from the state-of-charge field and the measurement time falls off-tick within the first scheduling interval, the next tick receives capacity/efficiency-adjusted bounds (db98b260d).
• Tests for all of the above, including the multi-device flex-model path (d13e37b26, f5967625f, 03fd551b0). The pre-existing hard-path tests now pin relax-constraints/relax-soc-constraints: False, since projected bounds are softened by default after fix 1.

One policy note for future discussion (not changed on the branch): the capacity-loosened bounds for user-given soc-minima/soc-maxima preserve reachability but don't enforce the bound at the off-tick moment itself — since intra-tick SoC is linear, duplicating the bound unadjusted onto both surrounding ticks would guarantee it exactly, with the auto-enabled relaxation absorbing any infeasibility. Similarly, targets are guaranteed at the next tick (slightly late), which matches the original issue-10 recipe; exact attainment at the off-tick time would need an interpolated constraint in device_scheduler. Both could be follow-ups.
Personally, duplicating the bound unadjusted does not appeal to me, and I favour the approach we now implemented. For me, the follow-up should be adding interpolated constraints in device_scheduler, but I feel this might need an update to how we formulate a schedule in the API response, too, in which time slots would no longer share the same resolution. Definitively out of scope, and not even on our roadmap.

Please review the pushed commits — happy to adjust anything you disagree with.

[Flix6x]

Pushed 1a0b144 implementing the stock-key rekey requested on #2325:

• off_tick_soc_sensor_ids → off_tick_stock_keys: entries are tracked by the stock key resolved from their serialized state-of-charge field (via _resolve_stock_key from Track devices via a typed device inventory in the StorageScheduler #2321), so relaxation scoping covers all devices sharing a stock — including the case where the SoC parameters live on a stock-only entry or on a member that isn't the group's first device. Entries without a resolvable stock key (no state-of-charge, or a time series) fall back to a namespaced ("sensor", power_sensor.id) key, preserving the previous per-device behavior for standalone devices.
• soc_at_start_datetimes is now keyed by stock key, threaded through the soc-at-start resolution chain: exact stock key in multi-device mode (passed down from the stock-group loop in _prepare), the SoC sensor's id when resolving from a sensor, and a None key for the single-sensor time-series case (with a matching fallback at the projection site).
• New regression test test_off_tick_soc_relaxation_covers_all_devices_of_a_shared_stock: off-tick soc-minima on a stock-only entry soften the shared group's constraints while an unrelated device keeps its hard on-tick minima.

Full planning suite passes on this branch (210 passed). Note: no dependency on #2325 — the rekey only uses #2321-level APIs, so the branches merge in either order (trivial textual overlap in _prepare's new device_stock_key lookup). Heads-up: your local fm-wt-pr2194 checkout is now one commit behind origin.