Add consumer formula generator not accounting for phantom loads (#31)

Meters with successors can still have loads not represented in the
component graph.  These are called phantom loads.

Tracking phantom loads requires larger formulas and expects all meters
to be available.

This PR implements a consumer formula generator as it was
implemented in the SDK - exclude producer and battery powers from the
grid power, or when there is no grid meter, add all the non battery
and producer meters.

This PR also changes a number of default settings:
- Prefer consumer power without phantom loads, the original approach is
still available through a config flag.
- Prefer meters for all component category formulas

Author: shsms

RELEASE_NOTES.md

@@ -1,17 +1,17 @@
 # Frequenz Component Graph Release Notes
 
-## Summary
+## Upgrading
 
-<!-- Here goes a general summary of what this release is about -->
+- The PV, battery, CHP, EV and Wind Turbine formulas now prefer meters as the primary components and fallback to inverters or other corresponding components only when the meters are not available.
 
-## Upgrading
+  This makes a big difference in performance when there are multiple PV inverters behind a single meter, for example.
 
-<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
+  This behaviour can be changed with the newly introduced meter preference config flags.
 
-## New Features
+- Consumer formulas don't consider phantom loads by default anymore.  The original behaviour is still available through a config flag.
 
-<!-- Here goes the main new features and examples or instructions on how to use them -->
+## New Features
 
-## Bug Fixes
+- This introduces a new consumer formula generator that doesn't consider phantom loads.
 
-<!-- Here goes notable bug fixes that are worth a special mention or explanation -->
+  Meters with successors can still have loads not represented in the component graph.  These are called phantom loads.

src/config.rs

@@ -23,4 +23,42 @@ pub struct ComponentGraphConfig {
     /// Whether to disable fallback components in generated formulas.  When this
     /// is `true`, the formulas will not include fallback components.
     pub disable_fallback_components: bool,
+
+    /// Meters with successors can still have loads not represented in the
+    /// component graph.  These are called phantom loads.
+    ///
+    /// When this is `true`, phantom loads are included in formulas by excluding
+    /// the measurements of successor meters from the measurements of their
+    /// predecessor meters.
+    ///
+    /// When `false`, consumer formula is generated by excluding production
+    /// and battery components from the grid measurements.
+    pub include_phantom_loads_in_consumer_formula: bool,
+
+    /// Whether to prefer PV inverters when generating PV formulas.  When this
+    /// is `true`, PV inverters will be the primary source and PV meters will be
+    /// the fallback.  When `false`, PV meters will be the primary source.
+    pub prefer_inverters_in_pv_formula: bool,
+
+    /// Whether to prefer battery inverters when generating Battery formulas.
+    /// When this is `true`, battery inverters will be the primary source and
+    /// battery meters will be secondary.  When `false`, battery meters will be
+    /// the primary source.
+    pub prefer_inverters_in_battery_formula: bool,
+
+    /// Whether to prefer CHP when generating CHP formulas.  When this is
+    /// `true`, CHP units will be the primary source and CHP meters will be
+    /// secondary.  When `false`, CHP meters will be the primary source.
+    pub prefer_chp_in_chp_formula: bool,
+
+    /// Whether to prefer EV chargers when generating EV formulas.  When this
+    /// is `true`, EV chargers will be the primary source and EV meters will be
+    /// secondary.  When `false`, EV meters will be the primary source.
+    pub prefer_ev_chargers_in_ev_formula: bool,
+
+    /// Whether to prefer wind turbines when generating Wind formulas.  When
+    /// this is `true`, wind turbines will be the primary source and wind meters
+    /// will be secondary.  When `false`, wind meters will be the primary
+    /// source.
+    pub prefer_wind_turbines_in_wind_formula: bool,
 }

src/graph/formulas/fallback.rs

@@ -9,9 +9,26 @@ use std::collections::BTreeSet;
 
 use super::expr::Expr;
 
+#[derive(Default)]
 pub(crate) struct FallbackExpr {
-    pub(crate) prefer_meters: bool,
-    pub(crate) meter_fallback_for_meters: bool,
+    prefer_meters: bool,
+    meter_fallback_for_meters: bool,
+}
+
+impl FallbackExpr {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    pub fn prefer_meters(mut self, prefer: bool) -> Self {
+        self.prefer_meters = prefer;
+        self
+    }
+
+    pub fn meter_fallback_for_meters(mut self, enable: bool) -> Self {
+        self.meter_fallback_for_meters = enable;
+        self
+    }
 }
 
 impl FallbackExpr {
@@ -84,6 +101,21 @@ impl FallbackExpr {
             return Ok(Some(Expr::component(component_id)));
         }
 
+        // If a meter fallback for a meter exists, make sure it is not a component meter.
+        if self.meter_fallback_for_meters && has_successor_meters {
+            // we've already established that if there are successor meters,
+            // then there's only one successor.
+            let successor = graph
+                .successors(component_id)?
+                .find(|node| node.is_meter())
+                .ok_or(Error::internal(
+                    "Can't find successor meter of component with successor meters.",
+                ))?;
+            if graph.is_component_meter(successor.component_id())? {
+                return Ok(Some(Expr::component(component_id)));
+            }
+        }
+
         let mut coalesced = Expr::component(component_id);
 
         if !self.prefer_meters {
@@ -203,76 +235,56 @@ mod tests {
         assert_eq!(meter_bat_chain.component_id(), 2);
 
         let graph = builder.build(None)?;
-        let expr = FallbackExpr {
-            prefer_meters: true,
-            meter_fallback_for_meters: true,
-        }
-        .generate(&graph, BTreeSet::from([1]))?;
-        assert_eq!(expr.to_string(), "COALESCE(#1, #2)");
-
-        let expr = FallbackExpr {
-            prefer_meters: true,
-            meter_fallback_for_meters: true,
-        }
-        .generate(&graph, BTreeSet::from([1, 2]))?;
-        assert_eq!(expr.to_string(), "COALESCE(#1, #2) + COALESCE(#2, #3, 0.0)");
+        let expr = FallbackExpr::new()
+            .prefer_meters(true)
+            .meter_fallback_for_meters(true)
+            .generate(&graph, BTreeSet::from([1]))?;
+        assert_eq!(expr.to_string(), "#1");
+
+        let expr = FallbackExpr::new()
+            .prefer_meters(true)
+            .meter_fallback_for_meters(true)
+            .generate(&graph, BTreeSet::from([1, 2]))?;
+        assert_eq!(expr.to_string(), "#1 + COALESCE(#2, #3, 0.0)");
 
-        let expr = FallbackExpr {
-            prefer_meters: false,
-            meter_fallback_for_meters: false,
-        }
-        .generate(&graph, BTreeSet::from([1, 2]))?;
+        let expr = FallbackExpr::new().generate(&graph, BTreeSet::from([1, 2]))?;
         assert_eq!(expr.to_string(), "#1 + COALESCE(#3, #2, 0.0)");
 
-        let expr = FallbackExpr {
-            prefer_meters: true,
-            meter_fallback_for_meters: false,
-        }
-        .generate(&graph, BTreeSet::from([1, 2]))?;
+        let expr = FallbackExpr::new()
+            .prefer_meters(true)
+            .generate(&graph, BTreeSet::from([1, 2]))?;
         assert_eq!(expr.to_string(), "#1 + COALESCE(#2, #3, 0.0)");
 
-        let expr = FallbackExpr {
-            prefer_meters: true,
-            meter_fallback_for_meters: false,
-        }
-        .generate(&graph, BTreeSet::from([3]))?;
+        let expr = FallbackExpr::new()
+            .prefer_meters(true)
+            .generate(&graph, BTreeSet::from([3]))?;
         assert_eq!(expr.to_string(), "COALESCE(#2, #3, 0.0)");
-        let expr = FallbackExpr {
-            prefer_meters: true,
-            meter_fallback_for_meters: true,
-        }
-        .generate(&graph, BTreeSet::from([3]))?;
+        let expr = FallbackExpr::new()
+            .prefer_meters(true)
+            .meter_fallback_for_meters(true)
+            .generate(&graph, BTreeSet::from([3]))?;
         assert_eq!(expr.to_string(), "COALESCE(#2, #3, 0.0)");
-        let expr = FallbackExpr {
-            prefer_meters: true,
-            meter_fallback_for_meters: true,
-        }
-        .generate(&graph, BTreeSet::from([2]))?;
+        let expr = FallbackExpr::new()
+            .prefer_meters(true)
+            .meter_fallback_for_meters(true)
+            .generate(&graph, BTreeSet::from([2]))?;
         assert_eq!(expr.to_string(), "COALESCE(#2, #3, 0.0)");
 
         let graph = builder.build(Some(ComponentGraphConfig {
             disable_fallback_components: true,
             ..Default::default()
         }))?;
-        let expr = FallbackExpr {
-            prefer_meters: false,
-            meter_fallback_for_meters: false,
-        }
-        .generate(&graph, BTreeSet::from([1, 2]))?;
+        let expr = FallbackExpr::new().generate(&graph, BTreeSet::from([1, 2]))?;
         assert_eq!(expr.to_string(), "#1 + #2");
 
-        let expr = FallbackExpr {
-            prefer_meters: true,
-            meter_fallback_for_meters: false,
-        }
-        .generate(&graph, BTreeSet::from([1, 2]))?;
+        let expr = FallbackExpr::new()
+            .prefer_meters(true)
+            .generate(&graph, BTreeSet::from([1, 2]))?;
         assert_eq!(expr.to_string(), "#1 + #2");
 
-        let expr = FallbackExpr {
-            prefer_meters: true,
-            meter_fallback_for_meters: false,
-        }
-        .generate(&graph, BTreeSet::from([3]))?;
+        let expr = FallbackExpr::new()
+            .prefer_meters(true)
+            .generate(&graph, BTreeSet::from([3]))?;
         assert_eq!(expr.to_string(), "#3");
 
         // Add a battery meter with three inverter and three batteries
@@ -282,11 +294,7 @@ mod tests {
         assert_eq!(meter_bat_chain.component_id(), 5);
 
         let graph = builder.build(None)?;
-        let expr = FallbackExpr {
-            prefer_meters: false,
-            meter_fallback_for_meters: false,
-        }
-        .generate(&graph, BTreeSet::from([3, 5]))?;
+        let expr = FallbackExpr::new().generate(&graph, BTreeSet::from([3, 5]))?;
         assert_eq!(
             expr.to_string(),
             concat!(
@@ -299,11 +307,9 @@ mod tests {
             )
         );
 
-        let expr = FallbackExpr {
-            prefer_meters: true,
-            meter_fallback_for_meters: false,
-        }
-        .generate(&graph, BTreeSet::from([2, 5]))?;
+        let expr = FallbackExpr::new()
+            .prefer_meters(true)
+            .generate(&graph, BTreeSet::from([2, 5]))?;
         assert_eq!(
             expr.to_string(),
             concat!(
@@ -312,11 +318,9 @@ mod tests {
             )
         );
 
-        let expr = FallbackExpr {
-            prefer_meters: true,
-            meter_fallback_for_meters: false,
-        }
-        .generate(&graph, BTreeSet::from([2, 6, 7, 8]))?;
+        let expr = FallbackExpr::new()
+            .prefer_meters(true)
+            .generate(&graph, BTreeSet::from([2, 6, 7, 8]))?;
         assert_eq!(
             expr.to_string(),
             concat!(
@@ -325,11 +329,9 @@ mod tests {
             )
         );
 
-        let expr = FallbackExpr {
-            prefer_meters: true,
-            meter_fallback_for_meters: false,
-        }
-        .generate(&graph, BTreeSet::from([2, 7, 8]))?;
+        let expr = FallbackExpr::new()
+            .prefer_meters(true)
+            .generate(&graph, BTreeSet::from([2, 7, 8]))?;
         assert_eq!(
             expr.to_string(),
             "COALESCE(#2, #3, 0.0) + COALESCE(#7, 0.0) + COALESCE(#8, 0.0)"
@@ -339,32 +341,22 @@ mod tests {
             disable_fallback_components: true,
             ..Default::default()
         }))?;
-        let expr = FallbackExpr {
-            prefer_meters: false,
-            meter_fallback_for_meters: false,
-        }
-        .generate(&graph, BTreeSet::from([3, 5]))?;
+        let expr = FallbackExpr::new().generate(&graph, BTreeSet::from([3, 5]))?;
         assert_eq!(expr.to_string(), "#3 + #5");
 
-        let expr = FallbackExpr {
-            prefer_meters: true,
-            meter_fallback_for_meters: false,
-        }
-        .generate(&graph, BTreeSet::from([2, 5]))?;
+        let expr = FallbackExpr::new()
+            .prefer_meters(true)
+            .generate(&graph, BTreeSet::from([2, 5]))?;
         assert_eq!(expr.to_string(), "#2 + #5");
 
-        let expr = FallbackExpr {
-            prefer_meters: true,
-            meter_fallback_for_meters: false,
-        }
-        .generate(&graph, BTreeSet::from([2, 6, 7, 8]))?;
+        let expr = FallbackExpr::new()
+            .prefer_meters(true)
+            .generate(&graph, BTreeSet::from([2, 6, 7, 8]))?;
         assert_eq!(expr.to_string(), "#2 + #6 + #7 + #8");
 
-        let expr = FallbackExpr {
-            prefer_meters: true,
-            meter_fallback_for_meters: false,
-        }
-        .generate(&graph, BTreeSet::from([2, 7, 8]))?;
+        let expr = FallbackExpr::new()
+            .prefer_meters(true)
+            .generate(&graph, BTreeSet::from([2, 7, 8]))?;
         assert_eq!(expr.to_string(), "#2 + #7 + #8");
 
         let meter = builder.meter();
@@ -379,11 +371,9 @@ mod tests {
         assert_eq!(pv_inverter.component_id(), 14);
 
         let graph = builder.build(None)?;
-        let expr = FallbackExpr {
-            prefer_meters: true,
-            meter_fallback_for_meters: false,
-        }
-        .generate(&graph, BTreeSet::from([5, 12]))?;
+        let expr = FallbackExpr::new()
+            .prefer_meters(true)
+            .generate(&graph, BTreeSet::from([5, 12]))?;
         assert_eq!(
             expr.to_string(),
             concat!(
@@ -392,11 +382,7 @@ mod tests {
             )
         );
 
-        let expr = FallbackExpr {
-            prefer_meters: false,
-            meter_fallback_for_meters: false,
-        }
-        .generate(&graph, BTreeSet::from([7, 14]))?;
+        let expr = FallbackExpr::new().generate(&graph, BTreeSet::from([7, 14]))?;
         assert_eq!(expr.to_string(), "COALESCE(#7, 0.0) + COALESCE(#14, 0.0)");
 
         Ok(())
@@ -423,4 +409,30 @@ mod tests {
         let expr = graph.pv_formula(None).unwrap().to_string();
         assert_eq!(expr, "COALESCE(#1, 0.0) + COALESCE(#2, 0.0)");
     }
+
+    /// Test meters with meter fallback
+    #[test]
+    fn test_meters_with_meter_fallback() -> Result<(), Error> {
+        let mut builder = ComponentGraphBuilder::new();
+        let grid = builder.grid();
+
+        let meter1 = builder.meter();
+        let meter2 = builder.meter();
+        let bat_chain = builder.meter_bat_chain(1, 1);
+        let pv_chain = builder.meter_pv_chain(1);
+
+        builder.connect(grid, meter1);
+        builder.connect(meter1, meter2);
+        builder.connect(meter2, bat_chain);
+        builder.connect(meter2, pv_chain);
+
+        let graph = builder.build(None)?;
+        let expr = FallbackExpr::new()
+            .prefer_meters(true)
+            .meter_fallback_for_meters(true)
+            .generate(&graph, BTreeSet::from([meter1.component_id()]))?;
+        assert_eq!(expr.to_string(), "COALESCE(#1, #2)");
+
+        Ok(())
+    }
 }

src/graph/formulas/formula.rs

@@ -43,7 +43,7 @@ where
 // evaluator.
 #[derive(Debug, Clone, PartialEq)]
 pub struct AggregationFormula {
-    expr: Expr,
+    pub(crate) expr: Expr,
 }
 
 impl From<Expr> for AggregationFormula {