frequenz-microgrid-component-graph 0.5.0

A library for representing the components of a microgrid and the connections between them as a Directed Acyclic Graph (DAG).
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

// License: MIT
// Copyright © 2024 Frequenz Energy-as-a-Service GmbH

//! Helper methods for checking invariants of a [`ComponentGraph`].

use crate::{Edge, Error, Node};

use super::ComponentGraphValidator;

impl<N, E> ComponentGraphValidator<'_, N, E>
where
    N: Node,
    E: Edge,
{
    /// Checks that the given node is a leaf node.
    pub(super) fn ensure_leaf(&self, node: &N) -> Result<(), Error> {
        if let Some(successor) = self.cg.successors(node.component_id())?.next() {
            return Err(Error::invalid_graph(format!(
                "{}:{} can't have any successors. Found {}:{}.",
                node.category(),
                node.component_id(),
                successor.category(),
                successor.component_id()
            )));
        }
        Ok(())
    }

    /// Checks that the given node is *not* a leaf node.
    pub(super) fn ensure_not_leaf(&self, node: &N) -> Result<(), Error> {
        if self.cg.successors(node.component_id())?.next().is_none() {
            return Err(Error::invalid_graph(format!(
                "{}:{} must have at least one successor.",
                node.category(),
                node.component_id()
            )));
        }
        Ok(())
    }

    /// Checks that the given node is a root node.
    pub(super) fn ensure_root(&self, node: &N) -> Result<(), Error> {
        if let Some(predecessor) = self.cg.predecessors(node.component_id())?.next() {
            return Err(Error::invalid_graph(format!(
                "{}:{} can't have any predecessors. Found {}:{}.",
                node.category(),
                node.component_id(),
                predecessor.category(),
                predecessor.component_id()
            )));
        }
        Ok(())
    }

    /// Checks that the given predicate holds for all predecessors of the given node.
    pub(super) fn ensure_on_predecessors(
        &self,
        node: &N,
        predicate: impl Fn(&N) -> bool,
        failure_message: &str,
    ) -> Result<(), Error> {
        for predecessor in self.cg.predecessors(node.component_id())? {
            if !predicate(predecessor) {
                return Err(Error::invalid_graph(format!(
                    "{}:{} can only have predecessors that are {}. Found {}:{}.",
                    node.category(),
                    node.component_id(),
                    failure_message,
                    predecessor.category(),
                    predecessor.component_id()
                )));
            }
        }
        Ok(())
    }

    /// Checks that the given predicate holds for all successors of the given node.
    pub(super) fn ensure_on_successors(
        &self,
        node: &N,
        predicate: impl Fn(&N) -> bool,
        failure_message: &str,
    ) -> Result<(), Error> {
        for successor in self.cg.successors(node.component_id())? {
            if !predicate(successor) {
                return Err(Error::invalid_graph(format!(
                    "{}:{} can only have successors that are {}. Found {}:{}.",
                    node.category(),
                    node.component_id(),
                    failure_message,
                    successor.category(),
                    successor.component_id()
                )));
            }
        }
        Ok(())
    }

    /// Checks that the given node's successors are exclusive to it.
    ///
    /// A node's successors are exclusive to the node if they don't have any
    /// other predecessors.
    pub(super) fn ensure_exclusive_successors(&self, node: &N) -> Result<(), Error> {
        for successor in self.cg.successors(node.component_id())? {
            if self.cg.predecessors(successor.component_id())?.count() > 1 {
                return Err(Error::invalid_graph(format!(
                    "{}:{} can't have successors with multiple predecessors. Found {}:{}.",
                    node.category(),
                    node.component_id(),
                    successor.category(),
                    successor.component_id()
                )));
            }
        }
        Ok(())
    }
}