Formula generation support (#2)

This PR adds formula generators for various microgrid metrics that
traverse the graph to produce and return string formulas.

Author: shsms

.github/workflows/ci.yaml

@@ -16,13 +16,7 @@ jobs:
       - name: Fetch sources
         uses: actions/checkout@v4
         with:
-          submodules: true
-
-      - name: Check formatting
-        run: cargo fmt --check
-
-      - name: Run linter
-        run: cargo clippy -- -W clippy::unwrap_used -W clippy::expect_used -W clippy::panic
+          submodules: recursive
 
       - name: Run tests
-        run: cargo test
+        uses: frequenz-floss/gh-action-cargo-test@v1.0.0

README.md

@@ -4,9 +4,9 @@ This is a library for representing the components of a microgrid and the
 connections between them as a Directed Acyclic Graph (DAG).
 
 Current features:
-  - validating the graph
-  - traversing the graph
+  - Validating the graph
+  - Traversing the graph
+  - Formula generation
 
 Upcoming features:
-  - Formula generation
   - Python bindings

src/graph.rs

@@ -9,6 +9,7 @@ mod meter_roles;
 mod retrieval;
 mod validation;
 
+mod formulas;
 pub mod iterators;
 
 use crate::{Edge, Node};
@@ -42,53 +43,4 @@ where
 }
 
 #[cfg(test)]
-mod test_types {
-    //! This module contains the `TestComponent` and `TestConnection` types,
-    //! which implement the `Node` and `Edge` traits respectively.
-    //!
-    //! They are shared by all the test modules in the `graph` module.
-
-    use crate::{ComponentCategory, Edge, Node};
-
-    #[derive(Clone, Debug, PartialEq)]
-    pub(super) struct TestComponent(u64, ComponentCategory);
-
-    impl TestComponent {
-        pub(super) fn new(id: u64, category: ComponentCategory) -> Self {
-            TestComponent(id, category)
-        }
-    }
-
-    impl Node for TestComponent {
-        fn component_id(&self) -> u64 {
-            self.0
-        }
-
-        fn category(&self) -> ComponentCategory {
-            self.1.clone()
-        }
-
-        fn is_supported(&self) -> bool {
-            true
-        }
-    }
-
-    #[derive(Clone, Debug, PartialEq)]
-    pub(super) struct TestConnection(u64, u64);
-
-    impl TestConnection {
-        pub(super) fn new(source: u64, destination: u64) -> Self {
-            TestConnection(source, destination)
-        }
-    }
-
-    impl Edge for TestConnection {
-        fn source(&self) -> u64 {
-            self.0
-        }
-
-        fn destination(&self) -> u64 {
-            self.1
-        }
-    }
-}
+mod test_utils;

src/graph/creation.rs

@@ -118,7 +118,7 @@ where
 mod tests {
     use super::*;
     use crate::component_category::BatteryType;
-    use crate::graph::test_types::{TestComponent, TestConnection};
+    use crate::graph::test_utils::{TestComponent, TestConnection};
     use crate::ComponentCategory;
     use crate::InverterType;
 

src/graph/formulas.rs

@@ -0,0 +1,61 @@
+// License: MIT
+// Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+//! Methods for building formulas for various microgrid metrics.
+
+use std::collections::BTreeSet;
+
+use crate::ComponentGraph;
+use crate::Edge;
+use crate::Error;
+use crate::Node;
+
+mod expr;
+mod fallback;
+mod generators;
+mod traversal;
+
+/// 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<String, Error> {
+        generators::consumer::ConsumerFormulaBuilder::try_new(self)?.build()
+    }
+
+    /// Returns a string representing the grid formula for the graph.
+    pub fn grid_formula(&self) -> Result<String, Error> {
+        generators::grid::GridFormulaBuilder::try_new(self)?.build()
+    }
+
+    /// Returns a string representing the producer formula for the graph.
+    pub fn producer_formula(&self) -> Result<String, 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<String, 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<String, 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<String, Error> {
+        generators::pv::PVFormulaBuilder::try_new(self, pv_inverter_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<String, Error> {
+        generators::ev_charger::EVChargerFormulaBuilder::try_new(self, ev_charger_ids)?.build()
+    }
+}