Frequenz Microgrid Component Graph

A Rust library for modelling a microgrid as a Directed Acyclic Graph (DAG) of electrical components, validating the topology, and generating string formulas for aggregated metrics.

Usage

The central type is ComponentGraph, generic over user-supplied node and edge types. Build one by passing iterators of components and connections to ComponentGraph::try_new, optionally with a ComponentGraphConfig constructed via ComponentGraphConfig::builder().

The Node and Edge traits

Because this crate is independent of any specific microgrid representation, it doesn't know about the component and connection types and instead uses traits to interact with them.

To be usable with ComponentGraph, the component and connection types must therefore implement the Node and Edge traits, respectively. Check the rustdoc for these traits for sample implementations.

Validation

try_new returns an Error unless the input graph has exactly one root (a GridConnectionPoint), is fully connected, acyclic, and obeys the per-category neighbor rules (e.g. a battery has a battery inverter predecessor and no successors). Selected checks downgrade to a tracing::warn! when the corresponding allow_* flag is set on the config.

Pass-through components

Several categories (transformers, breakers, converters, electrolyzers, HVAC, capacitor banks, and similar non-metering interconnect components) are treated as pass-through: validators and formula generators see the graph as if those nodes weren't there, and the public predecessors / successors iterators walk past them transparently. The raw graph view, including pass-through nodes, is available via raw_predecessors / raw_successors. ComponentGraph::try_new emits a tracing::warn! for each pass-through node so operators know what is being elided.

Warning: Pass-through behavior exists for forward compatibility — when new component categories are introduced, the library treats it as transparent rather than failing validation of the whole graph.

The trade-off is that a real misclassification can slip through unnoticed if the tracing::warn! output isn't being read; operators integrating this library should make sure those warnings are surfaced.

Formulas

Once constructed, the graph emits string formulas (e.g. #1 + COALESCE(#2, #3, 0.0)) that downstream code can hand to a metric evaluator:

• Aggregate: grid_formula, consumer_formula, producer_formula.
• Per category: battery_formula, pv_formula, chp_formula, wind_turbine_formula, ev_charger_formula, steam_boiler_formula.
• Single component: component_formula.
• Non-aggregating metrics (voltage, frequency): grid_coalesce_formula, battery_ac_coalesce_formula, pv_ac_coalesce_formula, component_ac_coalesce_formula.

For the per-category formulas, whether the meter or the device measurement is the primary source is controlled by prefer_meters_in_component_formulas on the config, with per-formula overrides available through FormulaOverrides.