Implement coalesce formula generators (#11)

These formulas can be used for voltage or frequency metrics.

Author: shsms

src/component_category.rs

@@ -96,10 +96,10 @@ impl Display for ComponentCategory {
             ComponentCategory::Unspecified => write!(f, "Unspecified"),
             ComponentCategory::Grid => write!(f, "Grid"),
             ComponentCategory::Meter => write!(f, "Meter"),
-            ComponentCategory::Battery(battery_type) => write!(f, "Battery({})", battery_type),
-            ComponentCategory::Inverter(inverter_type) => write!(f, "{}Inverter", inverter_type),
+            ComponentCategory::Battery(battery_type) => write!(f, "Battery({battery_type})"),
+            ComponentCategory::Inverter(inverter_type) => write!(f, "{inverter_type}Inverter"),
             ComponentCategory::EvCharger(ev_charger_type) => {
-                write!(f, "EVCharger({})", ev_charger_type)
+                write!(f, "EVCharger({ev_charger_type})")
             }
             ComponentCategory::Converter => write!(f, "Converter"),
             ComponentCategory::CryptoMiner => write!(f, "CryptoMiner"),

src/graph.rs

@@ -13,7 +13,7 @@ mod formulas;
 pub mod iterators;
 
 use crate::{ComponentGraphConfig, Edge, Node};
-pub use formulas::Formula;
+pub use formulas::{AggregationFormula, CoalesceFormula};
 use petgraph::graph::{DiGraph, NodeIndex};
 use std::collections::HashMap;
 

src/graph/formulas.rs

@@ -16,57 +16,117 @@ mod formula;
 mod generators;
 mod traversal;
 
-pub use formula::Formula;
+pub use formula::{AggregationFormula, CoalesceFormula};
 
 /// Formulas for various microgrid metrics.
 impl<N, E> ComponentGraph<N, E>
 where
     N: Node,
     E: Edge,
 {
-    /// Returns a string representing the consumer formula for the graph.
-    pub fn consumer_formula(&self) -> Result<Formula, Error> {
+    /// Returns the consumer formula for the graph.
+    pub fn consumer_formula(&self) -> Result<AggregationFormula, Error> {
         generators::consumer::ConsumerFormulaBuilder::try_new(self)?.build()
     }
 
-    /// Returns a string representing the grid formula for the graph.
-    pub fn grid_formula(&self) -> Result<Formula, Error> {
+    /// Returns the grid formula for the graph.
+    pub fn grid_formula(&self) -> Result<AggregationFormula, Error> {
         generators::grid::GridFormulaBuilder::try_new(self)?.build()
     }
 
-    /// Returns a string representing the producer formula for the graph.
-    pub fn producer_formula(&self) -> Result<Formula, Error> {
+    /// Returns the producer formula for the graph.
+    pub fn producer_formula(&self) -> Result<AggregationFormula, Error> {
         generators::producer::ProducerFormulaBuilder::try_new(self)?.build()
     }
 
-    /// Returns a string representing the battery formula for the graph.
-    pub fn battery_formula(&self, battery_ids: Option<BTreeSet<u64>>) -> Result<Formula, Error> {
+    /// Returns the battery formula with the given battery IDs.
+    ///
+    /// If `battery_ids` is `None`, the formula will contain all batteries in
+    /// the graph.
+    pub fn battery_formula(
+        &self,
+        battery_ids: Option<BTreeSet<u64>>,
+    ) -> Result<AggregationFormula, Error> {
         generators::battery::BatteryFormulaBuilder::try_new(self, battery_ids)?.build()
     }
 
-    /// Returns a string representing the CHP formula for the graph.
-    pub fn chp_formula(&self, chp_ids: Option<BTreeSet<u64>>) -> Result<Formula, Error> {
+    /// Returns the CHP formula for the graph.
+    pub fn chp_formula(&self, chp_ids: Option<BTreeSet<u64>>) -> Result<AggregationFormula, Error> {
         generators::chp::CHPFormulaBuilder::try_new(self, chp_ids)?.build()
     }
 
-    /// Returns a string representing the PV formula for the graph.
-    pub fn pv_formula(&self, pv_inverter_ids: Option<BTreeSet<u64>>) -> Result<Formula, Error> {
+    /// Returns the PV formula for the graph.
+    pub fn pv_formula(
+        &self,
+        pv_inverter_ids: Option<BTreeSet<u64>>,
+    ) -> Result<AggregationFormula, Error> {
         generators::pv::PVFormulaBuilder::try_new(self, pv_inverter_ids)?.build()
     }
 
-    /// Returns a string with the coalesce formula for the given component IDs.
+    /// Returns the coalesce formula for the given component IDs.
     ///
     /// This formula uses the `COALESCE` function to return the first non-null
     /// value from the components with the provided IDs.
-    pub fn coalesce(&self, component_ids: BTreeSet<u64>) -> Result<Formula, Error> {
+    pub fn coalesce(&self, component_ids: BTreeSet<u64>) -> Result<AggregationFormula, Error> {
         generators::generic::CoalesceFormulaBuilder::try_new(self, component_ids)?.build()
     }
 
     /// Returns a string representing the EV charger formula for the graph.
     pub fn ev_charger_formula(
         &self,
         ev_charger_ids: Option<BTreeSet<u64>>,
-    ) -> Result<Formula, Error> {
+    ) -> Result<AggregationFormula, Error> {
         generators::ev_charger::EVChargerFormulaBuilder::try_new(self, ev_charger_ids)?.build()
     }
+
+    /// Returns the grid coalesce formula for the graph.
+    ///
+    /// This formula is used for non-aggregating metrics like AC voltage or
+    /// frequency.
+    ///
+    /// The formula is a `COALESCE` expression that includes all meters,
+    /// PV inverters, and battery inverters that are directly connected to the
+    /// grid.
+    pub fn grid_coalesce_formula(&self) -> Result<CoalesceFormula, Error> {
+        generators::grid_coalesce::GridCoalesceFormulaBuilder::try_new(self)?.build()
+    }
+
+    /// Returns the battery AC coalesce formula for the given components.
+    ///
+    /// This formula is used for non-aggregating metrics like AC voltage or
+    /// frequency.
+    ///
+    /// The formula is a `COALESCE` expression that includes all the specified
+    /// battery meters and corresponding inverters.
+    ///
+    /// When the `battery_ids` parameter is `None`, it will include all the
+    /// battery meters and inverters in the graph.
+    pub fn battery_ac_coalesce_formula(
+        &self,
+        battery_ids: Option<BTreeSet<u64>>,
+    ) -> Result<CoalesceFormula, Error> {
+        generators::battery_ac_coalesce::BatteryAcCoalesceFormulaBuilder::try_new(
+            self,
+            battery_ids,
+        )?
+        .build()
+    }
+
+    /// Returns the PV AC coalesce formula for the given components.
+    ///
+    /// This formula is used for non-aggregating metrics like AC voltage or
+    /// frequency.
+    ///
+    /// The formula is a `COALESCE` expression that includes all the specified
+    /// PV meters and corresponding inverters.
+    ///
+    /// When the `pv_inverter_ids` parameter is `None`, it will include all the
+    /// PV meters and inverters in the graph.
+    pub fn pv_ac_coalesce_formula(
+        &self,
+        pv_inverter_ids: Option<BTreeSet<u64>>,
+    ) -> Result<CoalesceFormula, Error> {
+        generators::pv_ac_coalesce::PVAcCoalesceFormulaBuilder::try_new(self, pv_inverter_ids)?
+            .build()
+    }
 }

src/graph/formulas/expr.rs

@@ -3,7 +3,7 @@
 
 use crate::Node;
 
-#[derive(Debug, Clone)]
+#[derive(Debug, Clone, PartialEq)]
 pub(crate) enum Expr {
     /// A negation of an expression.
     Neg { param: Box<Expr> },
@@ -133,7 +133,11 @@ impl Expr {
     }
 
     pub(crate) fn coalesce(params: Vec<Expr>) -> Self {
-        Self::Coalesce { params }
+        if let [param] = params.as_slice() {
+            param.clone()
+        } else {
+            Self::Coalesce { params }
+        }
     }
 
     pub(crate) fn min(params: Vec<Expr>) -> Self {
@@ -178,13 +182,13 @@ impl Expr {
             Self::Number { value } => {
                 if value.fract() == 0.0 {
                     // For whole numbers, format with one decimal place.
-                    format!("{:.1}", value)
+                    format!("{value:.1}")
                 } else {
                     // else format normally.
-                    format!("{}", value)
+                    format!("{value}")
                 }
             }
-            Self::Component { component_id } => format!("#{}", component_id),
+            Self::Component { component_id } => format!("#{component_id}"),
             Self::Add { params } => {
                 Self::join_params(params, " + ", None, BracketComponents::None, bracket_whole)
             }
@@ -219,7 +223,7 @@ impl Expr {
         bracket_whole: bool,
     ) -> String {
         let (mut result, suffix) = match prefix {
-            Some(prefix) => (format!("{}(", prefix), String::from(")")),
+            Some(prefix) => (format!("{prefix}("), String::from(")")),
             None => (String::new(), String::new()),
         };
         let mut num_components = 0;

src/graph/formulas/formula.rs

@@ -8,47 +8,78 @@ use super::expr::Expr;
 // This struct represents the microgrid metric formulas that are generated by
 // traversing the component graph.
 //
-// `Formula` objects can be added or subtracted from each other, and they can
-// converted to a string representation, before they are passed to an evaluator.
-#[derive(Debug, Clone)]
-pub struct Formula {
+// They are used to represent quantities that are aggregated over multiple
+// components in the microgrid, such as power or current.
+//
+// `AggregationFormula` objects can be added or subtracted from each other, and
+// they can converted to a string representation, before they are passed to an
+// evaluator.
+#[derive(Debug, Clone, PartialEq)]
+pub struct AggregationFormula {
     expr: Expr,
 }
 
-impl Formula {
+impl AggregationFormula {
     pub(crate) fn new(expr: Expr) -> Self {
-        Formula { expr }
+        AggregationFormula { expr }
     }
 }
 
-impl std::ops::Add for Formula {
+impl std::ops::Add for AggregationFormula {
     type Output = Self;
 
     fn add(self, rhs: Self) -> Self::Output {
-        Formula {
+        AggregationFormula {
             expr: self.expr + rhs.expr,
         }
     }
 }
 
-impl std::ops::Sub for Formula {
+impl std::ops::Sub for AggregationFormula {
     type Output = Self;
 
     fn sub(self, rhs: Self) -> Self::Output {
-        Formula {
+        AggregationFormula {
             expr: self.expr - rhs.expr,
         }
     }
 }
 
-impl std::fmt::Display for Formula {
+impl std::fmt::Display for AggregationFormula {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        self.expr.fmt(f)
+    }
+}
+
+impl From<AggregationFormula> for String {
+    fn from(formula: AggregationFormula) -> Self {
+        formula.expr.to_string()
+    }
+}
+
+/// Represents a formula that coalesces metrics from multiple components.
+///
+/// This is typically used for non-aggregating metrics like AC voltage or
+/// frequency.
+#[derive(Debug, Clone, PartialEq)]
+pub struct CoalesceFormula {
+    expr: Expr,
+}
+
+impl CoalesceFormula {
+    pub(crate) fn new(expr: Expr) -> Self {
+        CoalesceFormula { expr }
+    }
+}
+
+impl std::fmt::Display for CoalesceFormula {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         self.expr.fmt(f)
     }
 }
 
-impl From<Formula> for String {
-    fn from(formula: Formula) -> Self {
+impl From<CoalesceFormula> for String {
+    fn from(formula: CoalesceFormula) -> Self {
         formula.expr.to_string()
     }
 }

src/graph/formulas/generators.rs

@@ -4,10 +4,13 @@
 //! Formula generators for standard metrics.
 
 pub(super) mod battery;
+pub(super) mod battery_ac_coalesce;
 pub(super) mod chp;
 pub(super) mod consumer;
 pub(super) mod ev_charger;
 pub(super) mod generic;
 pub(super) mod grid;
+pub(super) mod grid_coalesce;
 pub(super) mod producer;
 pub(super) mod pv;
+pub(super) mod pv_ac_coalesce;

src/graph/formulas/generators/battery.rs

@@ -7,7 +7,7 @@ use std::collections::BTreeSet;
 
 use crate::component_category::CategoryPredicates;
 use crate::graph::formulas::expr::Expr;
-use crate::graph::formulas::Formula;
+use crate::graph::formulas::AggregationFormula;
 use crate::{ComponentGraph, Edge, Error, Node};
 
 pub(crate) struct BatteryFormulaBuilder<'a, N, E>
@@ -49,26 +49,25 @@ where
     /// This is the sum of all battery_inverters in the graph. If the
     /// battery_ids are provided, only the batteries with the given ids are
     /// included in the formula.
-    pub fn build(self) -> Result<Formula, Error> {
+    pub fn build(self) -> Result<AggregationFormula, Error> {
         if self.inverter_ids.is_empty() {
-            return Ok(Formula::new(Expr::number(0.0)));
+            return Ok(AggregationFormula::new(Expr::number(0.0)));
         }
 
         self.graph
             .fallback_expr(self.inverter_ids, false)
-            .map(Formula::new)
+            .map(AggregationFormula::new)
     }
 
-    fn find_inverter_ids(
+    pub(super) fn find_inverter_ids(
         graph: &ComponentGraph<N, E>,
         battery_ids: &BTreeSet<u64>,
     ) -> Result<BTreeSet<u64>, Error> {
         let mut inverter_ids = BTreeSet::new();
         for battery_id in battery_ids {
             if !graph.component(*battery_id)?.is_battery() {
                 return Err(Error::invalid_component(format!(
-                    "Component with id {} is not a battery.",
-                    battery_id
+                    "Component with id {battery_id} is not a battery."
                 )));
             }
             for sibling in graph.siblings_from_predecessors(*battery_id)? {