eneros-topology

eneros-topology treats grid topology as a first-class citizen data structure of the operating system kernel, providing directed graph modeling and single-traversal topology analysis algorithms based on petgraph. All upper-layer components (Agent, Load Flow, Constraint, Twin) share the same topology view, avoiding the problem in traditional power software where topology is repeatedly modeled across multiple applications with inconsistent states.

Responsibilities

eneros-topology handles the following core responsibilities:

• Graph Structure Modeling: Graph structure representation of buses, branches, and electrical islands, supporting multiple branch types including lines, transformers, and switches
• Single-Traversal Analysis: A single DFS/BFS completes electrical island detection, connectivity checks, and shortest path search, avoiding multiple scans
• Topology Change Broadcast: Topology changes such as switch operations and branch switching are broadcast through the event bus, automatically invalidating Load Flow caches and triggering constraint recalculation
• Incremental Updates: Switch operations have O(log n) complexity, supporting high-frequency topology change scenarios
• Persistence: Supports multiple formats including JSON / CIM / CDF for import and export
• Index Acceleration: Bidirectional index based on HashMap<BusId, NodeIndex> for O(1) node lookup

Key Types and Interfaces

NetworkGraph

use petgraph::stable_graph::StableDiGraph;
use petgraph::graph::NodeIndex;
use std::collections::HashMap;
use eneros_core::{BusId, BranchId, ElementId, Voltage, BusType};

pub struct NetworkGraph {
    graph: StableDiGraph<Bus, Branch>,
    bus_index: HashMap<BusId, NodeIndex>,
    metadata: NetworkMetadata,
}

#[derive(Debug, Clone)]
pub struct NetworkMetadata {
    pub id: String,
    pub name: String,
    pub base_mva: f64,
    pub created_at: chrono::DateTime<chrono::Utc>,
}

impl NetworkGraph {
    pub fn new() -> Self {
        Self {
            graph: StableDiGraph::new(),
            bus_index: HashMap::new(),
            metadata: NetworkMetadata {
                id: uuid::Uuid::new_v4().to_string(),
                name: "unnamed".into(),
                base_mva: 100.0,
                created_at: chrono::Utc::now(),
            },
        }
    }

    pub fn add_bus(&mut self, bus: Bus) -> bool {
        if self.bus_index.contains_key(&bus.id) {
            return false;
        }
        let idx = self.graph.add_node(bus.clone());
        self.bus_index.insert(bus.id.clone(), idx);
        true
    }

    pub fn add_branch(&mut self, branch: Branch) -> bool {
        let from = match self.bus_index.get(&branch.from) {
            Some(&i) => i,
            None => return false,
        };
        let to = match self.bus_index.get(&branch.to) {
            Some(&i) => i,
            None => return false,
        };
        self.graph.add_edge(from, to, branch);
        true
    }

    pub fn remove_bus(&mut self, id: &BusId) -> Option<Bus> {
        let idx = self.bus_index.remove(id)?;
        self.graph.remove_node(idx)
    }

    pub fn bus_count(&self) -> usize {
        self.graph.node_count()
    }

    pub fn branch_count(&self) -> usize {
        self.graph.edge_count()
    }

    pub fn topology(&self) -> TopologyEngine<'_> {
        TopologyEngine { graph: self }
    }
}

Bus / Branch

#[derive(Debug, Clone)]
pub struct Bus {
    pub id: BusId,
    pub bus_type: BusType,
    pub voltage: Voltage,
    pub nominal_kv: f64,
    pub area: Option<String>,
    pub zone: Option<String>,
}

impl Bus {
    pub fn new(id: impl Into<String>, bus_type: BusType, voltage: Voltage) -> Self {
        Self {
            id: ElementId::new(id),
            bus_type,
            voltage,
            nominal_kv: 110.0,
            area: None,
            zone: None,
        }
    }
}

#[derive(Debug, Clone)]
pub struct Branch {
    pub from: BusId,
    pub to: BusId,
    pub params: BranchParams,
    pub status: BranchStatus,
    pub kind: BranchKind,
}

impl Branch {
    pub fn new(
        from: impl Into<String>,
        to: impl Into<String>,
        params: BranchParams,
    ) -> Self {
        Self {
            from: ElementId::new(from),
            to: ElementId::new(to),
            params,
            status: BranchStatus::Closed,
            kind: BranchKind::Line,
        }
    }
}

#[derive(Debug, Clone)]
pub struct BranchParams {
    pub r_pu: f64,
    pub x_pu: f64,
    pub b_pu: f64,
    pub rate_mva: f64,
}

impl BranchParams {
    pub fn line(r_pu: f64, x_pu: f64, b_pu: f64) -> Self {
        Self {
            r_pu,
            x_pu,
            b_pu,
            rate_mva: 100.0,
        }
    }

    pub fn transformer(r_pu: f64, x_pu: f64, ratio: f64) -> Self {
        Self {
            r_pu,
            x_pu,
            b_pu: 0.0,
            rate_mva: 100.0,
        }
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum BranchStatus {
    Closed,
    Open,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum BranchKind {
    Line,
    Transformer,
    Switch,
    Breaker,
}

TopologyEngine

use std::collections::HashSet;

pub struct TopologyEngine<'a> {
    graph: &'a NetworkGraph,
}

#[derive(Debug, Clone)]
pub struct Island {
    pub buses: Vec<BusId>,
    pub has_slack: bool,
}

impl<'a> TopologyEngine<'a> {
    pub fn find_islands(&self) -> Vec<Island> {
        let mut visited: HashSet<NodeIndex> = HashSet::new();
        let mut islands = Vec::new();

        for node in self.graph.graph.node_indices() {
            if visited.contains(&node) {
                continue;
            }
            let mut component: Vec<BusId> = Vec::new();
            let mut stack = vec![node];
            let mut has_slack = false;

            while let Some(n) = stack.pop() {
                if !visited.insert(n) {
                    continue;
                }
                let bus = &self.graph.graph[n];
                component.push(bus.id.clone());
                if bus.bus_type.is_slack() {
                    has_slack = true;
                }
                for edge in self.graph.graph.edges(n) {
                    let target = edge.target();
                    if !visited.contains(&target) {
                        stack.push(target);
                    }
                }
            }

            islands.push(Island { buses: component, has_slack });
        }
        islands
    }

    pub fn is_connected(&self, a: &BusId, b: &BusId) -> bool {
        let start = match self.graph.bus_index.get(a) {
            Some(&i) => i,
            None => return false,
        };
        let target = match self.graph.bus_index.get(b) {
            Some(&i) => i,
            None => return false,
        };
        let mut visited: HashSet<NodeIndex> = HashSet::new();
        let mut stack = vec![start];
        while let Some(n) = stack.pop() {
            if n == target {
                return true;
            }
            if !visited.insert(n) {
                continue;
            }
            for edge in self.graph.graph.edges(n) {
                if !visited.contains(&edge.target()) {
                    stack.push(edge.target());
                }
            }
        }
        false
    }

    pub fn shortest_path(&self, a: &BusId, b: &BusId) -> Option<Vec<BusId>> {
        let start = self.graph.bus_index.get(a)?;
        let target = self.graph.bus_index.get(b)?;
        let mut parent: HashMap<NodeIndex, NodeIndex> = HashMap::new();
        let mut queue = std::collections::VecDeque::new();
        queue.push_back(*start);
        let mut visited: HashSet<NodeIndex> = HashSet::new();
        visited.insert(*start);

        while let Some(node) = queue.pop_front() {
            if node == *target {
                let mut path = Vec::new();
                let mut cur = *target;
                path.push(self.graph.graph[cur].id.clone());
                while let Some(&p) = parent.get(&cur) {
                    path.push(self.graph.graph[p].id.clone());
                    cur = p;
                }
                path.reverse();
                return Some(path);
            }
            for edge in self.graph.graph.edges(node) {
                let t = edge.target();
                if visited.insert(t) {
                    parent.insert(t, node);
                    queue.push_back(t);
                }
            }
        }
        None
    }

    pub fn neighbors(&self, bus: &BusId) -> Vec<BusId> {
        let idx = match self.graph.bus_index.get(bus) {
            Some(&i) => i,
            None => return Vec::new(),
        };
        self.graph
            .graph
            .edges(idx)
            .map(|e| self.graph.graph[e.target()].id.clone())
            .collect()
    }
}

Core API

Usage Examples

Building a Simple Network

use eneros_topology::{NetworkGraph, Bus, Branch, BranchParams, BusType};
use eneros_core::Voltage;

let mut net = NetworkGraph::new();
net.add_bus(Bus::new("1", BusType::Slack, Voltage::new(1.05, 0.0)));
net.add_bus(Bus::new("2", BusType::PQ,   Voltage::new(1.00, 0.0)));
net.add_bus(Bus::new("3", BusType::PQ,   Voltage::new(1.00, 0.0)));

net.add_branch(Branch::new("1", "2", BranchParams::line(0.1, 0.2, 0.02)));
net.add_branch(Branch::new("2", "3", BranchParams::line(0.05, 0.1, 0.01)));
net.add_branch(Branch::new("1", "3", BranchParams::line(0.08, 0.15, 0.015)));

println!("Bus count: {} Branch count: {}", net.bus_count(), net.branch_count());

Electrical Island Detection

let topo = net.topology();
let islands = topo.find_islands();
println!("Number of electrical islands: {}", islands.len());
for (i, island) in islands.iter().enumerate() {
    println!(
        "Island {}: bus_count={} has_slack={}",
        i,
        island.buses.len(),
        island.has_slack
    );
}

Connectivity and Shortest Path

let topo = net.topology();
assert!(topo.is_connected(&"1".into(), &"3".into()));

if let Some(path) = topo.shortest_path(&"1".into(), &"3".into()) {
    println!("Shortest path: {:?}", path);
}

let neighbors = topo.neighbors(&"2".into());
println!("Adjacent buses of bus 2: {:?}", neighbors);

Topology Change: Switch Operation

use eneros_topology::{BranchStatus, BranchKind};

let mut net = NetworkGraph::new();
net.add_bus(Bus::new("A", BusType::Slack, Voltage::new(1.0, 0.0)));
net.add_bus(Bus::new("B", BusType::PQ,   Voltage::new(1.0, 0.0)));

let mut sw = Branch::new("A", "B", BranchParams::line(0.0, 0.0, 0.0));
sw.kind = BranchKind::Switch;
sw.status = BranchStatus::Closed;
net.add_branch(sw);

assert!(net.topology().is_connected(&"A".into(), &"B".into()));

// Switch open: electrical island splits
let topo = net.topology();
let islands_before = topo.find_islands().len();
println!("Number of islands before opening: {}", islands_before);

Persistence (JSON)

use eneros_topology::NetworkGraph;

let mut net = NetworkGraph::new();
net.add_bus(Bus::new("1", BusType::Slack, Voltage::new(1.05, 0.0)));
net.add_bus(Bus::new("2", BusType::PQ,   Voltage::new(1.00, 0.0)));
net.add_branch(Branch::new("1", "2", BranchParams::line(0.1, 0.2, 0.02)));

let json = serde_json::to_string_pretty(&net)?;
std::fs::write("network.json", json)?;

let restored: NetworkGraph = serde_json::from_str(&std::fs::read_to_string("network.json")?)?;
assert_eq!(restored.bus_count(), 2);

Performance Metrics

Test environment: 4 cores / 8GB / Ubuntu 22.04 / Rust 1.78 release build.

Dependencies

Own Dependencies

[dependencies]
eneros-core = { path = "../core", version = "0.47.0" }
eneros-linalg = { path = "../linalg", version = "0.47.0" }
petgraph = "0.6"
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
chrono = { version = "0.4", features = ["serde"] }
uuid = { version = "1", features = ["v4", "serde"] }
tracing = "0.1"

Depended On By

eneros-topology is the core of the power kernel, directly depended on by the following crates:

• eneros-powerflow — Builds YBus matrix based on topology
• eneros-constraint — Validates voltage and branch constraints based on topology
• eneros-analysis — State estimation and OPF
• eneros-twin — Digital Twin shares topology view
• eneros-agent — Agents perceive grid location through topology
• eneros-network — Topology-Power Flow unified pipeline

Version and Compatibility

Related Documentation

• Grid Topology First-Class Citizen — Design philosophy
• eneros-powerflow — Topology-driven Load Flow
• eneros-core — Foundational type system
• Crate Index — Complete list