Add a steam boiler pool by shsms · Pull Request #1429 · frequenz-floss/frequenz-sdk-python

shsms · 2026-06-08T15:49:43Z

Steam boilers are controllable electrical loads the SDK could not monitor or
manage. This adds a steam boiler pool with power readings and power control,
following the structure of the EV charger and PV pools.

Changes

New public API: microgrid.new_steam_boiler_pool() returning a
SteamBoilerPool with power, power_status, and a consumption-only
propose_power (negative power is rejected).
SteamBoilerData component data type and data sourcing support.
Power manager wiring using the plain matryoshka algorithm, with
DefaultPower.ZERO when no actor is proposing.
SteamBoilerManager splits the target power equally across the working
boilers, keeping every allocation inside the boiler's inclusion bounds: a
share below a boiler's minimum operating power is raised to the minimum, or
the boiler is kept off. Like the PV manager, it subtracts the measured draw
of unreachable boilers from the target.
SteamBoilerStatusTracker for per-boiler health, mirroring the PV tracker.

Worth a look

The single-pass allocation reports power as excess when a high-minimum
boiler can't be afforded instead of topping up earlier boilers
(test_unaffordable_minimum_strands_excess pins this).
With no usable boilers a request is dropped with only an error log — the
same behavior as the PV and EV managers; a follow-up could make all three
send an Error result the way the battery manager does.

cwasicki

Any advice what to review here? On a first glimpse this looks like a lot of boiler-plate code.

cwasicki · 2026-08-27T08:09:10Z

    Metric.AC_REACTIVE_POWER_PHASE_3: lambda msg: msg.reactive_power_per_phase[2],
 }

+_STEAM_BOILER_DATA_METHODS: dict[


Why do we need to repeat these for every device?

"historical reasons". This comes from the old days where the API have one message per component for the data. Now it just needs modernization. Hopefully soon™️.

It would be a lot of work to do it differently, which is not worth it, because this stuff will all be rewritten in rust in the next several months.

shsms · 2026-08-28T11:01:51Z

Any advice what to review here? On a first glimpse this looks like a lot of boiler-plate code.

The big things to check are:

the power distribution algorithm, which allocates equally, starting from the smallest component, here: https://github.com/frequenz-floss/frequenz-sdk-python/pull/1429/changes#diff-acd36e353c52229236c9db5604976d972cb6e7cef600da43ef0d385af0f47b41R103
the default power and power manager algorithm here: https://github.com/frequenz-floss/frequenz-sdk-python/pull/1429/changes#diff-9f32f637c4ac702aa43914f3ab2949c4b6adef41b482c1d300a4262c06b1f995R146-R147

I'll need to do some testing as well.

cwasicki

LGTM, the PR description mentions a wrong default though.

llucax

LGTM. AI review with a few findings coming up.

BTW, sorry for the delay, I started the review but never submitted it and forgot about it.

llucax · 2026-08-27T09:36:05Z

Oh, damn. I sill need to remove all this cr*p... 🤦 ☹️

Maybe you can forget about this for now. There's a big cleanup coming soon anyway, with the moving of the algorithmic parts to be behind the microgrid API.

llucax · 2026-08-27T12:43:33Z

    Metric.AC_REACTIVE_POWER_PHASE_3: lambda msg: msg.reactive_power_per_phase[2],
 }

+_STEAM_BOILER_DATA_METHODS: dict[


"historical reasons". This comes from the old days where the API have one message per component for the data. Now it just needs modernization. Hopefully soon™️.

llucax

🤖 rAIview (AI review here!)

The overall structure is consistent with the existing component pools. I found three concrete control-path issues around failure feedback, stale bounds when all boilers become unavailable, and reversed reactive-power documentation. I also left two questions about whether the deliberately simple allocation and exclusion-bound behavior should be accepted and documented for this initial version.

llucax · 2026-09-08T12:02:58Z

+    reactive_power: float = 0.0
+    """The total reactive 3-phase AC power, in Volt-Ampere Reactive (VAr).
+
+    * Positive power means capacitive (current leading w.r.t. voltage).
+    * Negative power means inductive (current lagging w.r.t. voltage).
+    """
+
+    reactive_power_per_phase: PhaseTuple = (0.0, 0.0, 0.0)
+    """The per-phase AC reactive power, in Volt-Ampere Reactive (VAr).
+
+    The provided values are for phase 1, 2, and 3 respectively.
+
+    * Positive power means capacitive (current leading w.r.t. voltage).
+    * Negative power means inductive (current lagging w.r.t. voltage).


🟡⬇️ Correct the reactive-power sign convention

These descriptions reverse the Microgrid API convention. The API defines negative reactive power as capacitive, with current leading voltage, and positive reactive power as inductive, with current lagging voltage. Both the total and per-phase docstrings currently say the opposite.

API reference: microgrid.proto:183-187.

Impact

Users can interpret measured reactive power with the wrong physical direction and build control or reporting logic around the reversed convention.

Suggested fix (⬇️ effort)

Change both docstrings to say that negative is capacitive and positive is inductive.

🟡 Medium Severity: Probably best to fix before merging because this documents a public data type with the opposite convention from the API.
⬇️ Low Effort: This requires changing four documentation lines.

I guess we're contradicting the proto everywhere. in the old_component_data.py file, not just here.

Besides, both the proto and the SDK docs are completely wrong about the meaning of reactive power signs. So both need to be fixed, but separate project I guess.

Are there issues for this? I seems nasty to document stuff that is not true.

Steam boilers are controllable electrical loads. Their active power and its inclusion/exclusion bounds, together with the per-phase power, current, voltage and frequency, are reported through the corresponding AC_* metrics. SteamBoilerData derives directly from ComponentData and declares its own fields and from_samples/to_samples handling, rather than reusing another category's type, so steam boilers are not coupled to the CHP data model. Signed-off-by: Sahas Subramanian <sahas.subramanian@proton.me>

Adds the timeseries.steam_boiler_pool package: the SteamBoilerPool, its reference store and report types, and a SteamBoilerSystemBoundsTracker that aggregates the active-power bounds of the working boilers, mirroring the PV pool. Signed-off-by: Sahas Subramanian <sahas.subramanian@proton.me>

The data sourcing actor handles the steam boiler component category so the power formula can resample per-boiler power. Signed-off-by: Sahas Subramanian <sahas.subramanian@proton.me>

The SteamBoilerStatusTracker reports per-boiler health so that broken boilers can be excluded from power distribution, mirroring the PV inverter status tracker. Signed-off-by: Sahas Subramanian <sahas.subramanian@proton.me>

The SteamBoilerManager splits the target power equally across the working boilers. Each allocation stays inside the boiler's inclusion bounds: a share below a boiler's minimum operating power is raised to the minimum when the remaining budget covers it, and the boiler is kept off otherwise. Like the PV manager, the measured draw of unreachable boilers is subtracted from the target, so the working boilers don't make the site overshoot it. Signed-off-by: Sahas Subramanian <sahas.subramanian@proton.me>

Wires the steam boiler pool into the data pipeline factory, using the plain matryoshka power-manager algorithm with DefaultPower.ZERO, so that unmanaged boilers are switched off and fall back to gas heating, and documents the new pool in the microgrid module docs. Signed-off-by: Sahas Subramanian <sahas.subramanian@proton.me>

Adds SteamBoilerDataWrapper, steam boiler streaming in the mock microgrid, resampling in the mock resampler, and graph-generator support. Signed-off-by: Sahas Subramanian <sahas.subramanian@proton.me>

Tests for the steam boiler pool power formula (including its meter fallback) and the power control methods. Signed-off-by: Sahas Subramanian <sahas.subramanian@proton.me>

Tests for the SteamBoilerManager's distribution (minimum-power and unreachable-power handling, formula delegation, shutdown) and the status tracker. Signed-off-by: Sahas Subramanian <sahas.subramanian@proton.me>

Signed-off-by: Sahas Subramanian <sahas.subramanian@proton.me>

llucax

OK, approving, assuming there were no code changes except for resolving any conflicts or adapting the necessary bits to the fixes for exhaustive match.

shsms · 2026-09-10T08:49:53Z

Yes, it was only a rebase.

github-project-automation Bot added this to Python SDK Roadmap Jun 8, 2026

github-project-automation Bot moved this to To do in Python SDK Roadmap Jun 8, 2026

shsms changed the title ~~Add SteamBoilerPool for monitoring and controlling steam boilers~~ Add a steam boiler pool Aug 26, 2026

shsms force-pushed the steam-boiler-pool branch from 8cda58a to ba9e618 Compare August 26, 2026 14:27

shsms marked this pull request as ready for review August 26, 2026 14:29

shsms requested a review from a team as a code owner August 26, 2026 14:29

shsms requested review from llucax and removed request for a team August 26, 2026 14:29

cwasicki reviewed Aug 27, 2026

View reviewed changes

llucax mentioned this pull request Aug 27, 2026

Add steam boiler pool #1399

Closed

cwasicki approved these changes Aug 28, 2026

View reviewed changes

github-project-automation Bot moved this from To do to Review approved in Python SDK Roadmap Aug 28, 2026

shsms added this pull request to the merge queue Sep 7, 2026

github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Sep 7, 2026

llucax reviewed Sep 8, 2026

View reviewed changes

shsms added 8 commits September 8, 2026 16:51

Add steam boiler support to the data sourcing actor

e9b81d2

The data sourcing actor handles the steam boiler component category so the power formula can resample per-boiler power. Signed-off-by: Sahas Subramanian <sahas.subramanian@proton.me>

Add a status tracker for steam boilers

31d7ade

The SteamBoilerStatusTracker reports per-boiler health so that broken boilers can be excluded from power distribution, mirroring the PV inverter status tracker. Signed-off-by: Sahas Subramanian <sahas.subramanian@proton.me>

Add steam boiler support to the test utilities

f30a2b3

Adds SteamBoilerDataWrapper, steam boiler streaming in the mock microgrid, resampling in the mock resampler, and graph-generator support. Signed-off-by: Sahas Subramanian <sahas.subramanian@proton.me>

Add steam boiler pool tests

77072f3

Tests for the steam boiler pool power formula (including its meter fallback) and the power control methods. Signed-off-by: Sahas Subramanian <sahas.subramanian@proton.me>

shsms added 2 commits September 8, 2026 16:51

Add steam boiler power distribution and status tests

59037fc

Tests for the SteamBoilerManager's distribution (minimum-power and unreachable-power handling, formula delegation, shutdown) and the status tracker. Signed-off-by: Sahas Subramanian <sahas.subramanian@proton.me>

Add release note for the steam boiler pool

b7d7402

Signed-off-by: Sahas Subramanian <sahas.subramanian@proton.me>

shsms force-pushed the steam-boiler-pool branch from ba9e618 to b7d7402 Compare September 8, 2026 15:04

shsms requested a review from llucax September 9, 2026 15:02

llucax approved these changes Sep 10, 2026

View reviewed changes

shsms added this pull request to the merge queue Sep 10, 2026

Merged via the queue into frequenz-floss:v1.x.x with commit cd5282e Sep 10, 2026
9 checks passed

shsms deleted the steam-boiler-pool branch September 10, 2026 08:54

github-project-automation Bot moved this from Review approved to Done in Python SDK Roadmap Sep 10, 2026

llucax added this to the v1.0.0-rc2212 milestone Sep 15, 2026

Uh oh!

Conversation

shsms commented Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Worth a look

Uh oh!

cwasicki left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shsms commented Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cwasicki left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

llucax left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

llucax left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Impact

Suggested fix (⬇️ effort)

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

llucax left a comment

Choose a reason for hiding this comment

Uh oh!

shsms commented Sep 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

shsms commented Jun 8, 2026 •

edited

Loading

shsms commented Aug 28, 2026 •

edited

Loading

llucax left a comment •

edited

Loading