Gate no-telemetry components out of formulas via operational mode#44
Merged
Conversation
A component whose operational mode provides no telemetry has no reading to emit, so drop it from every sum or difference of component readings in the fallback engine: it is instead measured through a telemetry-providing meter above it, which it still classifies (e.g. as a PV meter). A meter with a no-telemetry child stands alone on its own reading — no child sum is exact for its group — backed by the children's best-effort sum. Meters are gated the same way: a meter that provides no telemetry is not a usable measurement source, and drilling it never emits its own reading. It is measured by the best-effort sum of its children instead, so a reporting meter above it resolves through it to its reporting descendants. A silent meter whose children are fed around it, and one with nothing reporting below, are dropped whole; components under a silent meter are measured directly. A no-telemetry grid meter's term is null: its children never carry the site's unmodeled load, so a children sum would read as a false value. Existing all-telemetry behavior is unchanged. A child meter that feeds a sibling of the same parent normally has no term of its own, because the sibling's reading already carries its flow. When that sibling contributes nothing — it provides no telemetry and nothing below it reports — there is nothing to double count, so the child meter keeps its term: it is the only source for that line. Signed-off-by: Sahas Subramanian <sahas.subramanian@proton.me>
The grid, PV and battery AC coalesce formulas and both consumer formula variants enumerate component readings directly; skip any component that provides no telemetry, since it has no reading to include. A skipped component is still used to classify the meter that measures it, which remains in the formula. In the meterless consumer formula, discovery descends past a no-telemetry consumer meter, so its reporting descendant meters are summed in its place. A descendant meter that another collected meter already measures is left out: its line is already counted once, and what it gets through the silent feed alone has no reading that separates it. In the phantom-loads variant, a no-telemetry meter contributes no residual term (its residual is unknowable), a no-telemetry diamond sibling is left out of the diamond sum, and a no-telemetry non-meter successor is not subtracted, so its share counts as phantom load. Signed-off-by: Sahas Subramanian <sahas.subramanian@proton.me>
Signed-off-by: Sahas Subramanian <sahas.subramanian@proton.me>
component_formula and component_ac_coalesce_formula emit a single component's reading directly. When that component provides no telemetry it has no reading, so return 0.0 (None for the AC coalesce variant) instead. Looking the component up also validates that it exists in the graph. Signed-off-by: Sahas Subramanian <sahas.subramanian@proton.me>
The Node and Edge doc examples targeted microgrid API v0.17's common::v1::microgrid::components types. Retarget them to v0.18.1's common::v1alpha8::microgrid::electrical_components, whose ElectricalComponent and ElectricalComponentConnection are the current API surface; its category enum also maps 1:1 onto ComponentCategory now. Signed-off-by: Sahas Subramanian <sahas.subramanian@proton.me>
Introduce the OperationalMode enum, mirroring the microgrid API's ElectricalComponentOperationalMode, and expose it on the Node trait via a defaulted operational_mode() method. The default is Unspecified, treated as providing telemetry, so existing Node implementations keep their behavior. Signed-off-by: Sahas Subramanian <sahas.subramanian@proton.me>
Collaborator
Author
|
Based on #43 |
shsms
force-pushed
the
operational-mode
branch
4 times, most recently
from
July 16, 2026 14:47
7b488dd to
5f2f804
Compare
shsms
marked this pull request as ready for review
July 23, 2026 13:07
shsms
force-pushed
the
operational-mode
branch
2 times, most recently
from
July 24, 2026 11:01
a75aefa to
ca0e0cc
Compare
llucax
added
the
scope:breaking-change
llucax
reviewed
Jul 24, 2026
llucax
left a comment
llucax
left a comment
There was a problem hiding this comment.
🤖 rAIview (AI review here!)
The operational-mode behavior is broadly well documented and thoroughly tested, but two medium-severity issues should be addressed before merging: the updated public integration example does not compile, and consumer-formula de-duplication can perform quadratic numbers of whole-graph traversals.
llucax
approved these changes
Jul 24, 2026
This was referenced Jul 24, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Components can be active without providing telemetry (control-only or
inactive). Their readings never arrive, so formulas that include them
never resolve. This branch adds the microgrid API's operational mode to
the
Nodetrait and excludes no-telemetry components as measurementsources throughout the formula engine.
Changes
OperationalModeenum, exposed on theNodetrait via adefaulted
operational_mode()method. The default (Unspecified) istreated as providing telemetry, so existing implementations keep
their behavior.
difference of readings; they are measured through a reporting meter
above them, which they still classify. A no-telemetry meter is
measured through its reporting children; a no-telemetry grid meter's
term is null.
meterless consumer formula descends past a no-telemetry consumer
meter to its reporting descendant meters, without double counting a
line another collected meter already measures.
component_formula()returns a0.0formula andcomponent_ac_coalesce_formula()returnsNonefor a no-telemetrycomponent; both now return an error for an id not in the graph.
Breaking
component_formula()andcomponent_ac_coalesce_formula()nowreturn an error when the given component id is not in the graph;
before, they returned a formula for any id. See the
## Upgradingentry in the release notes.