[StorageScheduler] Support aggregate-power schedule output at multiple topology levels

[saerts-gp]

Context & Problem Statement

In a typical behind-the-meter energy site, the electrical topology has multiple hierarchical levels where aggregate power is meaningful:

Grid Connection
  └── Point of Common Coupling (PCC)
        └── Distribution Board (DB)
              ├── Battery
              ├── PV Array(s)
              ├── EV Charger(s)
              └── Untracked Load

Currently, the FlexMeasures StorageScheduler writes the aggregate scheduled power to a single sensor, referenced via the aggregate-power key in the site's flex-context. This sensor is typically attached to the distribution board level.

We attempted to add a second aggregate-power schedule sensor at the PCC level (one topology level above the distribution board), so that the total scheduled power is visible at both the DB and PCC levels. However, the current architecture only supports a single sensor reference in the flex-context:

flex_context = {
    "aggregate-power": {"sensor": 16},  # only one sensor ID
    ...
}

When multiple assets have an aggregate-power schedule sensor, only the first one found during setup receives data. All other sensors are provisioned but remain permanently empty — the scheduler never writes to them.

Proposed Solution / Approach

Support writing aggregate schedule data to multiple sensors across different topology levels. Two possible approaches:

Option A: Multi-sensor aggregate-power in flex-context

Allow aggregate-power to reference a list of sensors instead of a single one:

flex_context = {
    "aggregate-power": {"sensors": [16, 42]},  # DB sensor + PCC sensor
    ...
}

The scheduler would write the same aggregate schedule to all referenced sensors after each scheduling cycle.

Option B: Derived/cascading schedule sensors

Keep the single aggregate-power reference but allow other schedule sensors to be defined as "mirrors" or "derived" sensors that automatically copy data from the primary aggregate sensor. This would be handled at the data layer rather than the scheduler.

Option C: Post-schedule hook

Add a post-scheduling hook that propagates the aggregate schedule data up the topology tree, writing to parent-level sensors automatically based on the asset hierarchy.

Action Items (Task List)

• Evaluate which approach (A, B, or C) best fits the FlexMeasures architecture
• If Option A: update flex-context schema to accept a list of sensor references for aggregate-power
• If Option A: update StorageScheduler to iterate and store results to all referenced sensors
• If Option B: implement a sensor "mirroring" or "derived schedule" mechanism
• If Option C: implement post-schedule propagation using asset parent relationships
• Update documentation for multi-level aggregate power configuration
• Add integration tests covering multi-level topology scenarios

Acceptance Criteria

• A site with both a Distribution Board and a PCC can have aggregate-power schedule sensors at both levels
• After a successful scheduling cycle, both sensors contain identical aggregate schedule data
• Existing single-sensor configurations continue to work without changes (backward compatible)
• The UI (if applicable) shows the aggregate schedule at whichever topology level is being viewed

Technical Notes / Resources

Current behavior observed:

• Setup iterates assets and takes the first power_balance schedule sensor found
• The "first wins" logic means the sensor at the lower topology level (DB) always gets the data
• The PCC-level sensor is correctly provisioned but has zero measurements after scheduling

Relevant scheduler flow:

1. reload_global_flex_context() discovers aggregate-power sensors on distribution-board-type assets
2. Sets flex_context["aggregate-power"]["sensor"] to the first sensor found
3. StorageScheduler reads this single sensor ID and stores the aggregate schedule only there

Site topology that triggered this:

Grid (utility connection, price sensors)
  └── PCC (import/export limits, power balance computed sensors)
        └── Distribution Board (power balance schedule sensor ← only this gets data)
              ├── Battery (schedule sensor, SoC)
              ├── PV Array SE (forecast + schedule sensors)
              ├── PV Array NW (forecast + schedule sensors)
              └── EV Charger (measured power)

Open Questions

• Should the aggregate at the PCC level be identical to the DB level, or should it account for additional topology-specific factors (e.g., grid losses, transformer constraints)?
• Is there a use case for having different aggregate calculations at different levels, or is a simple copy/mirror sufficient?
• How should this interact with multi-DB sites (sites with more than one distribution board under a single PCC)?

[Flix6x]

(I moved this from the Q&A to the Ideas category, as otherwise GitHub suggested my comment would turn op as a straight answer to a question. I think this will be more of a discussion topic for a new idea.)

I tend to think about this from the perspective of having multiple distribution boards under a grid connection. For that case, a higher-level aggregate power sensor should record the sum over lower-level aggregate power sensors. This touches on our work on device groups and intermediate power constraints. The direction we are taking is to let you extend the flex-model (now a list of device descriptions) with group descriptions. If the group description contains a power sensor we would use that as the aggregate-power sensor for that group. This direction is effectively making the topology part of the flex-model.

For asset trees defined in the db, we might derive this topology automatically, or require it to be defined explicitly in the flex-model of each asset. I'll add some examples here later.

Are you really only interested short-term in having a straight-up copy of the aggregate power data on a second sensor, or would you agree to discuss this in the context of multiple distribution boards?

[saerts-gp]

Thanks Felix, the group-based flex-model direction is exactly what we'd love to see!

We're very much interested in discussing this in the multi-DB context, not just a simple copy. Our real-world topology looks like:

Grid
└── PCC
├── Distribution Board A
│ ├── Battery
│ ├── PV Array(s)
│ └── EV Charger
└── Distribution Board B
├── Battery
└── PV Array(s)
In this case, the PCC-level aggregate should be the sum of all child DB aggregates, not a copy. Each DB has its own set of flexible/inflexible devices, and the PCC aggregate represents the net scheduled power at the grid connection point.

What's the rough timeline you're thinking for the group descriptions work? We'll implement a short-term workaround on our side (some sensor that sums child DB aggregates) in the meantime.

[nhoening]

It's something we would like to have, for sure, but not on top of our priority list (in terms of project deadlines).

How about we spec what should be done, let Copilot create a first version, and you can test that, @saerts-gp ?

[saerts-gp]

Good suggestion, I will volunteer to test that :)