Struct CausalGraph 

pub struct CausalGraph { /* private fields */ }

A concurrent directed acyclic graph for causal reasoning.

Internally backed by DashMap for lock-free concurrent reads and fine-grained write locking. Edge lists are stored in both forward (outgoing) and reverse (incoming) adjacency maps for efficient bidirectional traversal.

Implementations

impl CausalGraph

pub fn new() -> Self

Create an empty causal graph.

pub fn add_node(&self, label: String, metadata: Value) -> NodeId

Add a node with an auto-assigned ID.

pub fn get_node(&self, id: NodeId) -> Option<CausalNode>

Retrieve a clone of the node with the given ID.

pub fn remove_node(&self, id: NodeId) -> Option<CausalNode>

Remove a node and all edges incident to it.

Returns the removed node, or None if the ID was not found.

pub fn link( &self, source: NodeId, target: NodeId, edge_type: CausalEdgeType, weight: f32, timestamp: u64, chain_seq: u64, ) -> bool

Create an edge from source to target.

Returns false if either endpoint does not exist.

pub fn unlink(&self, source: NodeId, target: NodeId) -> usize

Remove all edges between source and target (in that direction).

Returns the number of edges removed.

pub fn get_forward_edges(&self, id: NodeId) -> Vec<CausalEdge>

Return all edges originating from id.

pub fn get_reverse_edges(&self, id: NodeId) -> Vec<CausalEdge>

Return all edges targeting id.

pub fn get_edges_by_type( &self, id: NodeId, edge_type: &CausalEdgeType, ) -> Vec<CausalEdge>

Return forward edges from id that match edge_type.

pub fn node_count(&self) -> u64

Number of nodes currently in the graph.

pub fn edge_count(&self) -> u64

Number of edges currently in the graph.

pub fn clear(&self)

Remove all nodes and edges (used during calibration cleanup).

pub fn traverse_forward(&self, start: NodeId, depth: usize) -> Vec<NodeId>

BFS traversal forward from start up to depth hops.

Returns all discovered node IDs (excluding start).

pub fn traverse_reverse(&self, start: NodeId, depth: usize) -> Vec<NodeId>

BFS traversal backward (following reverse edges) from start up to depth hops.

Returns all discovered node IDs (excluding start).

pub fn find_path( &self, from: NodeId, to: NodeId, max_depth: usize, ) -> Option<Vec<NodeId>>

Find the shortest path from from to to using BFS, limited to max_depth hops.

Returns the node sequence including both endpoints, or None if no path exists within the depth limit.

pub fn node_ids(&self) -> Vec<NodeId>

List all node IDs currently in the graph.

pub fn degree(&self, id: NodeId) -> usize

Degree of a node (in + out edges, treating graph as undirected).

pub fn in_degree(&self, id: NodeId) -> usize

In-degree (number of incoming edges).

pub fn out_degree(&self, id: NodeId) -> usize

Out-degree (number of outgoing edges).

pub fn connected_components(&self) -> Vec<Vec<NodeId>>

Find connected components treating the graph as undirected.

Returns a vec of components, each component being a vec of node IDs. Components are sorted largest-first.

pub fn detect_communities(&self, max_iterations: usize) -> Vec<Vec<NodeId>>

Detect communities using label propagation on the undirected graph.

Each node starts with its own label. In each iteration, every node adopts the most frequent label among its neighbors (weighted by edge weight). Converges when no labels change, or after max_iterations.

Returns a map from community label (a NodeId) to the set of node IDs in that community.

pub fn spectral_analysis(&self, max_iterations: usize) -> SpectralResult

Compute the algebraic connectivity (lambda_2) of the graph.

Lambda_2 is the second-smallest eigenvalue of the graph Laplacian.

• lambda_2 = 0 means the graph is disconnected.
• Higher values indicate stronger connectivity.

Uses sparse Lanczos iteration at O(km) where m = number of edges and k = max_iterations. For typical ECC graphs with average degree ~10, this is ~200x faster than the dense O(kn^2) approach.

Returns (lambda_2, fiedler_vector) where the Fiedler vector can be used for spectral partitioning (sign of each component indicates which partition the node belongs to).

pub fn spectral_partition(&self) -> (Vec<NodeId>, Vec<NodeId>)

Partition the graph into two halves using the Fiedler vector.

Nodes with positive Fiedler vector components go to partition A, negative to partition B. This is spectral bisection — the minimum-cut balanced partition.

pub fn compute_coupling( &self, change_events: &[ChangeEvent], ) -> Vec<CouplingPair>

Compute co-modification coupling between nodes based on temporal co-occurrence patterns.

Given a list of “change events” (each event is a set of node IDs that changed together, plus a timestamp), computes a coupling score for every pair of nodes that have been modified together.

The coupling score for nodes (A, B) is: coupling = co_changes(A,B) / max(changes(A), changes(B))

Returns pairs sorted by coupling score descending.

pub fn predict_changes( &self, change_events: &[ChangeEvent], window_size: usize, baseline_factor: f64, ) -> Vec<ChangePrediction>

Detect burst patterns in change events and predict which nodes are likely to change next.

A “burst” is a period where a node has significantly more changes than its baseline rate. Nodes currently in a burst, or recently co-modified with nodes in a burst, are predicted to change next.

window_size is the number of recent events to consider for the burst window. baseline_factor is the multiplier above which a node’s activity is considered a burst (e.g., 2.0 = 2x baseline).

Returns nodes sorted by prediction confidence (descending).

impl CausalGraph

pub fn save_to_writer<W: Write>(&self, writer: W) -> Result<(), Error>

Serialize the entire graph to a JSON writer.

pub fn load_from_reader<R: Read>(reader: R) -> Result<Self, Error>

Deserialize a graph from a JSON reader.

pub fn save_to_file(&self, path: &Path) -> Result<(), Error>

Save the graph to a file path.

pub fn load_from_file(path: &Path) -> Result<Self, Error>

Load a graph from a file path.

Trait Implementations

impl Default for CausalGraph

fn default() -> Self

Returns the “default value” for a type.