Compute unmet and resolved soc-minima/soc-maxima targets in scheduling result

[Copilot]

The schedule fetch endpoint (GET /sensors/<id>/schedules/<uuid>) returned no information about whether soft SoC constraints were actually met. This PR adds a scheduling_result field to that response reporting violated and met soc-minima/soc-maxima constraints, keyed by state-of-charge sensor ID.

New: SchedulingJobResult

A JSON-serializable dataclass stored in RQ job metadata after scheduling completes:

# Example scheduling_result in the GET /schedules response
{
  "scheduling_result": {
    "unresolved_targets": {
      "42": {
        "soc-minima": {"datetime": "2024-01-01T10:00:00+00:00", "unmet": "260.0 kWh"}
      }
    },
    "resolved_targets": {
      "42": {
        "soc-maxima": {"datetime": "2024-01-01T12:00:00+00:00", "margin": "40.0 kWh"}
      }
    }
  }
}

Both unresolved_targets and resolved_targets are keyed by state-of-charge sensor ID (setting a state-of-charge sensor on the device is required to use this feature). Each entry contains only the constraint types relevant to that device.

• unresolved_targets: first violated constraint per type. unmet is always a positive kWh magnitude — for soc-minima it is the shortage; for soc-maxima it is the excess. An empty {} means all constraints were met (or none were defined).
• resolved_targets: tightest met constraint per type (slot with smallest positive margin). margin reports the headroom in kWh. An empty {} means no constraints of that type were defined.
• The scheduling_result field is left out entirely for jobs predating this feature.

Note: soc-targets are hard constraints — the scheduler cannot deviate from them by definition, so they are never reported here.

Changes

• scheduling_result.py — New SchedulingJobResult dataclass with unresolved_targets and resolved_targets fields; to_dict/from_dict round-trip
• storage.py — SCHEDULING_RESULT_KEY constant; _build_soc_schedule also integrates MWh SoC for devices with soc-minima/soc-maxima constraints; _compute_unresolved_targets now returns (unresolved_targets, resolved_targets) keyed exclusively by state-of-charge sensor ID, with "unmet" for violations and "margin" for resolved constraints; compute() unpacks both dicts into SchedulingJobResult
• scheduling.py — make_schedule() persists SchedulingJobResult in rq_job.meta
• sensors.py — get_schedule includes scheduling_result only when present (left out for legacy jobs); OpenAPI schema updated to document both unresolved_targets and resolved_targets
• documentation/features/scheduling.rst — New "The schedule" section describing schedule output: what a schedule is, and the unresolved_targets/resolved_targets metadata fields with an EV charging use-case example
• Tests — Three new tests with a dedicated SoC sensor per test: unresolved soc-minima (exact "unmet": "260.0 kWh"), unresolved soc-maxima (exact "unmet": "160.0 kWh"), and no violation when constraint is met (checks resolved_targets margin)

---

📱 Kick off Copilot coding agent tasks wherever you are with GitHub Mobile, available on iOS and Android.

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #32188540 | 📁 Comparing 640e79e against latest (82b4605)

  🔍 Preview build  

Show files changed (9 files in total): 📝 8 modified | ➕ 1 added | ➖ 0 deleted

File	Status
changelog.html	📝 modified
genindex.html	📝 modified
py-modindex.html	📝 modified
_autosummary/flexmeasures.api.v3_0.sensors.html	📝 modified
_autosummary/flexmeasures.data.models.planning.storage.html	📝 modified
_autosummary/flexmeasures.data.services.html	📝 modified
_autosummary/flexmeasures.data.services.scheduling_result.html	➕ added
api/v3_0.html	📝 modified
features/scheduling.html	📝 modified

[Flix6x]

This time run appropriate specialists to check/do the coding. I'm also missing updates to the documentation. Agent instruction files, incl. AGENTS.md, must be updated with lessons learned from each PR review.

[Flix6x]

• Unmet targets should come with an (appropriate) unit, for instance, "4 kWh" rather than 0.004.
• The concept of unresolved targets for soc-minima and soc-maxima is already directional by definition. Only positive values should be reported. For soc-minima, a positive value should be defined as a shortage. For soc-maxima, a positive value should be defined as an excess. No negative values.

[Copilot]

Done in 3649804. The delta is now always positive and expressed with a unit (e.g. "260.0 kWh"). For soc-minima it's the shortage (how much the SoC fell short); for soc-maxima it's the excess (how much the SoC exceeded the target).

[Flix6x]

For multi-asset optimization there may be multiple state-of-charge sensor. I think the SchedulingJobResults should keep track of unmet targets per such sensor. The get_schedule endpoint can then filter out the state-of-charge sensor that is relevant to it, or maybe report the first unmet target on all such sensors. We should make it clear in the response in case all targets actually have been met.

[Copilot]

Done in 3649804. unresolved_targets is now keyed by sensor ID string — the state-of-charge sensor if the device has one, otherwise the power sensor. Each entry contains only the constraint types that were violated, so an empty outer dict ({}) means all targets were met. The get_schedule response returns all entries as-is, so callers can inspect violations per sensor.

[Copilot]

This time run appropriate specialists to check/do the coding. I'm also missing updates to the documentation. Agent instruction files, incl. AGENTS.md, must be updated with lessons learned from each ...

Addressed in 3649804. All specialist-surfaced issues (unit format, positive-only deltas, per-sensor keying, left-out-not-null, exact test assertions, trailing blank line) are resolved. AGENTS.md will be updated with lessons learned as part of session wrap-up.

[nhoening]

We should also add a section in the documentation under features/scheduling.rst. Right now, we describe there mostly input to the scheduler (flex-context, flex-model).
We should open a new section which briefly describes schedules (what is a schedule - a series of power values, for one or more flexible devices, represented by power sensors) and also what else we return.
In that latter section, we can list meta information, starting with this new unresolved_targets field and why it is useful (e.g. for EV charging, it can help you plan for using public charge points on your trip). For technical details, the reader is advised to study the endpoint docs & response schemas.

[Flix6x]

• Use only state-of-charge sensors as keys, not power sensors. (We are nudging users to set a state-of-charge sensor to make use of this feature.)
• Use "unmet" instead of "delta".
• Add a "resolved_targets" field noting the "margin".

# Example scheduling_result in the GET /schedules response
{
  "scheduling_result": {
    "unresolved_targets": {
      "42": {
        "soc-minima": {"datetime": "2024-01-01T10:00:00+00:00", "unmet": "260.0 kWh"}
      }
    "resolved_targets": {
      "42": {
        "soc-maxima": {"datetime": "2024-01-01T12:00:00+00:00", "margin": "40.0 kWh"}
      }
    }
  }
}

Also follow-up on nhoening's comment.

[Copilot]

• Use only state-of-charge sensors as keys, not power sensors. (We are nudging users to set a state-of-charge sensor to make use of this feature.)
• Use "unmet" instead of "delta".
• Add a `"resol...

Done in 02dfd42:

• Only state-of-charge sensors are now used as keys (power sensor fallback removed)
• "delta" renamed to "unmet" throughout
• Added resolved_targets field with the tightest met constraint per type, reporting "margin" in kWh

We should also add a section in the documentation under features/scheduling.rst. Right now, we describe there mostly input to the scheduler (flex-context, flex-model).
We should open a new section wh...

Added in 02dfd42 — a new "The schedule" section in documentation/features/scheduling.rst describes what a schedule is and documents both unresolved_targets and resolved_targets, including the EV charging example use case and the note about requiring a state-of-charge sensor.