Feature/add wind turbine (#28)

Fixes #27

Author: nhatcher-frequenz

RELEASE_NOTES.md

@@ -2,16 +2,4 @@
 
 ## Summary
 
-<!-- Here goes a general summary of what this release is about -->
-
-## Upgrading
-
-<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
-
-## New Features
-
-<!-- Here goes the main new features and examples or instructions on how to use them -->
-
-## Bug Fixes
-
-<!-- Here goes notable bug fixes that are worth a special mention or explanation -->
+- Added Wind Turbine formulas

src/component_category.rs

@@ -180,6 +180,10 @@ pub(crate) trait CategoryPredicates: Node {
     fn is_chp(&self) -> bool {
         self.category() == ComponentCategory::Chp
     }
+
+    fn is_wind_turbine(&self) -> bool {
+        self.category() == ComponentCategory::WindTurbine
+    }
 }
 
 /// Implement the `CategoryPredicates` trait for all types that implement the

src/graph/formulas.rs

@@ -64,6 +64,15 @@ where
         generators::pv::PVFormulaBuilder::try_new(self, pv_inverter_ids)?.build()
     }
 
+    /// Returns the wind_turbine formula for the graph.
+    pub fn wind_turbine_formula(
+        &self,
+        wind_turbine_ids: Option<BTreeSet<u64>>,
+    ) -> Result<AggregationFormula, Error> {
+        generators::wind_turbine::WindTurbineFormulaBuilder::try_new(self, wind_turbine_ids)?
+            .build()
+    }
+
     /// Returns the EV charger formula for the graph.
     pub fn ev_charger_formula(
         &self,

src/graph/formulas/fallback.rs

@@ -114,6 +114,7 @@ impl FallbackExpr {
     /// - Battery Inverter
     /// - PV Inverter
     /// - EV Charger
+    /// - Wind Turbine
     fn component_fallback<N: Node, E: Edge>(
         &self,
         graph: &ComponentGraph<N, E>,
@@ -125,6 +126,7 @@ impl FallbackExpr {
             && !component.is_chp()
             && !component.is_pv_inverter()
             && !component.is_ev_charger()
+            && !component.is_wind_turbine()
         {
             return Ok(None);
         }

src/graph/formulas/generators.rs

@@ -13,3 +13,4 @@ pub(super) mod grid_coalesce;
 pub(super) mod producer;
 pub(super) mod pv;
 pub(super) mod pv_ac_coalesce;
+pub(super) mod wind_turbine;

src/graph/formulas/generators/wind_turbine.rs

@@ -0,0 +1,196 @@
+// License: MIT
+// Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+//! This module contains the methods for generating producer formulas.
+
+use std::collections::BTreeSet;
+
+use crate::component_category::CategoryPredicates;
+use crate::graph::formulas::AggregationFormula;
+use crate::graph::formulas::expr::Expr;
+use crate::graph::formulas::fallback::FallbackExpr;
+use crate::{ComponentGraph, Edge, Error, Node};
+
+pub(crate) struct WindTurbineFormulaBuilder<'a, N, E>
+where
+    N: Node,
+    E: Edge,
+{
+    graph: &'a ComponentGraph<N, E>,
+    wind_turbine_ids: BTreeSet<u64>,
+}
+
+impl<'a, N, E> WindTurbineFormulaBuilder<'a, N, E>
+where
+    N: Node,
+    E: Edge,
+{
+    pub fn try_new(
+        graph: &'a ComponentGraph<N, E>,
+        wind_turbine_ids: Option<BTreeSet<u64>>,
+    ) -> Result<Self, Error> {
+        let wind_turbine_ids = if let Some(wind_turbine_ids) = wind_turbine_ids {
+            wind_turbine_ids
+        } else {
+            graph.find_all(
+                graph.root_id,
+                |node| node.is_wind_turbine(),
+                petgraph::Direction::Outgoing,
+                false,
+            )?
+        };
+        Ok(Self {
+            graph,
+            wind_turbine_ids,
+        })
+    }
+
+    /// Generates the wind_turbine formula.
+    ///
+    /// This is the sum of all wind_turbines in the graph. If the wind_turbine_ids are provided,
+    /// only the wind_turbines with the given ids are included in the formula.
+    pub fn build(self) -> Result<AggregationFormula, Error> {
+        if self.wind_turbine_ids.is_empty() {
+            return Ok(AggregationFormula::new(Expr::number(0.0)));
+        }
+
+        for id in &self.wind_turbine_ids {
+            if !self.graph.component(*id)?.is_wind_turbine() {
+                return Err(Error::invalid_component(format!(
+                    "Component with id {id} is not a wind turbine."
+                )));
+            }
+        }
+
+        FallbackExpr {
+            prefer_meters: false,
+            meter_fallback_for_meters: false,
+        }
+        .generate(self.graph, self.wind_turbine_ids.clone())
+        .map(AggregationFormula::new)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::collections::BTreeSet;
+
+    use crate::{Error, graph::test_utils::ComponentGraphBuilder};
+
+    #[test]
+    fn test_wind_turbine_formula() -> Result<(), Error> {
+        let mut builder = ComponentGraphBuilder::new();
+        let grid = builder.grid();
+
+        let grid_meter = builder.meter();
+        builder.connect(grid, grid_meter);
+
+        let graph = builder.build(None)?;
+        let formula = graph.wind_turbine_formula(None)?.to_string();
+        assert_eq!(formula, "0.0");
+
+        // Add a wind_turbine meter with one wind turbine.
+        let meter_wind_turbine_chain = builder.meter_wind_turbine_chain(1);
+        builder.connect(grid_meter, meter_wind_turbine_chain);
+
+        assert_eq!(grid_meter.component_id(), 1);
+        assert_eq!(meter_wind_turbine_chain.component_id(), 2);
+        let graph = builder.build(None)?;
+        let formula = graph.wind_turbine_formula(None)?.to_string();
+        assert_eq!(formula, "COALESCE(#3, #2, 0.0)");
+
+        // Add a battery meter with one battery inverter and two batteries.
+        let meter_bat_chain = builder.meter_bat_chain(1, 2);
+        builder.connect(grid_meter, meter_bat_chain);
+
+        assert_eq!(meter_bat_chain.component_id(), 4);
+
+        let graph = builder.build(None)?;
+        let formula = graph.wind_turbine_formula(None)?.to_string();
+        assert_eq!(formula, "COALESCE(#3, #2, 0.0)");
+
+        // Add a wind_turbine meter with two wind_turbine inverters.
+        let meter_wind_turbine_chain = builder.meter_wind_turbine_chain(2);
+        builder.connect(grid_meter, meter_wind_turbine_chain);
+
+        assert_eq!(meter_wind_turbine_chain.component_id(), 8);
+
+        let graph = builder.build(None)?;
+        let formula = graph.wind_turbine_formula(None)?.to_string();
+        assert_eq!(
+            formula,
+            concat!(
+                "COALESCE(#3, #2, 0.0) + ",
+                "COALESCE(#10 + #9, #8, COALESCE(#10, 0.0) + COALESCE(#9, 0.0))"
+            )
+        );
+
+        let formula = graph
+            .wind_turbine_formula(Some(BTreeSet::from([10, 3])))?
+            .to_string();
+        assert_eq!(formula, "COALESCE(#3, #2, 0.0) + COALESCE(#10, 0.0)");
+
+        // add a meter direct to the grid with three wind_turbine inverters
+        let meter_wind_turbine_chain = builder.meter_wind_turbine_chain(3);
+        builder.connect(grid, meter_wind_turbine_chain);
+
+        assert_eq!(meter_wind_turbine_chain.component_id(), 11);
+        let graph = builder.build(None)?;
+        let formula = graph.wind_turbine_formula(None)?.to_string();
+        assert_eq!(
+            formula,
+            concat!(
+                "COALESCE(#3, #2, 0.0) + ",
+                "COALESCE(#10 + #9, #8, COALESCE(#10, 0.0) + COALESCE(#9, 0.0)) + ",
+                "COALESCE(",
+                "#14 + #13 + #12, ",
+                "#11, ",
+                "COALESCE(#14, 0.0) + COALESCE(#13, 0.0) + COALESCE(#12, 0.0)",
+                ")"
+            ),
+        );
+
+        let formula = graph
+            .wind_turbine_formula(Some(BTreeSet::from([3, 9, 10, 12, 13])))?
+            .to_string();
+        assert_eq!(
+            formula,
+            concat!(
+                "COALESCE(#3, #2, 0.0) + ",
+                "COALESCE(#10 + #9, #8, COALESCE(#10, 0.0) + COALESCE(#9, 0.0)) + ",
+                "COALESCE(#12, 0.0) + ",
+                "COALESCE(#13, 0.0)"
+            )
+        );
+
+        let formula = graph
+            .wind_turbine_formula(Some(BTreeSet::from([3, 9, 10, 12, 13, 14])))?
+            .to_string();
+        assert_eq!(
+            formula,
+            concat!(
+                "COALESCE(#3, #2, 0.0) + ",
+                "COALESCE(#10 + #9, #8, COALESCE(#10, 0.0) + COALESCE(#9, 0.0)) + ",
+                "COALESCE(",
+                "#14 + #13 + #12, ",
+                "#11, ",
+                "COALESCE(#14, 0.0) + COALESCE(#13, 0.0) + COALESCE(#12, 0.0)",
+                ")"
+            )
+        );
+
+        let formula = graph
+            .wind_turbine_formula(Some(BTreeSet::from([10, 14])))?
+            .to_string();
+        assert_eq!(formula, "COALESCE(#10, 0.0) + COALESCE(#14, 0.0)");
+
+        // Failure cases:
+        let formula = graph.wind_turbine_formula(Some(BTreeSet::from([8])));
+        assert_eq!(
+            formula.unwrap_err().to_string(),
+            "InvalidComponent: Component with id 8 is not a wind turbine."
+        );
+
+        Ok(())
+    }
+}

src/graph/test_utils.rs

@@ -2,7 +2,7 @@
 // Copyright © 2024 Frequenz Energy-as-a-Service GmbH
 
 //! This module is only compiled when running unit tests and contains features
-//! that are shared by all tests of the `graph` modue.
+//! that are shared by all tests of the `graph` module.
 //!
 //! - the `TestComponent` and `TestConnection` types, which implement the `Node`
 //!   and `Edge` traits respectively.
@@ -150,6 +150,11 @@ impl ComponentGraphBuilder {
         self.add_component(ComponentCategory::Chp)
     }
 
+    /// Adds a wind_turbine to the graph and returns its handle.
+    pub(super) fn wind_turbine(&mut self) -> ComponentHandle {
+        self.add_component(ComponentCategory::WindTurbine)
+    }
+
     /// Connects two components in the graph.
     pub(super) fn connect(&mut self, from: ComponentHandle, to: ComponentHandle) -> &mut Self {
         self.connections
@@ -226,6 +231,17 @@ impl ComponentGraphBuilder {
         meter
     }
 
+    /// Adds a meter, followed by the given number of wind turbines, and
+    /// returns a handle to the meter.
+    pub(super) fn meter_wind_turbine_chain(&mut self, num_wind_turbines: usize) -> ComponentHandle {
+        let meter = self.meter();
+        for _ in 0..num_wind_turbines {
+            let wind_turbine = self.wind_turbine();
+            self.connect(meter, wind_turbine);
+        }
+        meter
+    }
+
     /// Builds and returns the component graph from the components and
     /// connections added to the builder.
     pub(super) fn build(