Struct CausaloidGraph 

pub struct CausaloidGraph<T: Clone> { /* private fields */ }

A specialized graph structure for representing and reasoning about causal relationships.

CausaloidGraph is a wrapper around an ultragraph graph, tailored for holding nodes that implement the Causable trait. This structure allows for modeling complex, non-linear causal systems where the activation of one cause can influence others in a directed, potentially acyclic, manner.

The graph uses an adjacency matrix for its underlying storage, which provides fast edge lookups but can be memory-intensive if the graph is sparse and has a large capacity.

Type Parameters

• T: The type of the nodes in the graph. It must implement Causable to allow for causal reasoning, PartialEq for node comparison, Clone to manage graph data, and Display for explanations. A common T is the Causaloid struct.

Implementations

impl<T: Clone> CausaloidGraph<T>

pub fn new(id: IdentificationValue) -> Self

Creates a new CausaloidGraph with a default capacity.

This constructor initializes the graph with a default capacity of 500 nodes. It utilizes an adjacency matrix for storage, which is suitable for dense graphs or graphs where the maximum number of nodes is known and not excessively large.

Returns

pub fn new_with_capacity(id: IdentificationValue, capacity: usize) -> Self

Creates a new CausaloidGraph with a specified capacity.

This constructor allows you to pre-allocate space for a given number of nodes, which can be beneficial for performance if the approximate size of the graph is known beforehand. The underlying storage uses an adjacency matrix.

Arguments

• capacity - The maximum number of nodes the graph is expected to hold.

Trait Implementations

impl<I, O, PS, C> CausableGraph<Causaloid<I, O, PS, C>> for CausaloidGraph<Causaloid<I, O, PS, C>>

where I: Default + Send + Sync + 'static, O: Default + Debug + Send + Sync + 'static, PS: Default + Clone + Send + Sync + 'static, C: Clone + Send + Sync + 'static, Causaloid<I, O, PS, C>: MonadicCausable<I, O>,

fn is_frozen(&self) -> bool

fn freeze(&mut self)

Ensures the graph is in the immutable, performance-optimized Static state.

fn unfreeze(&mut self)

Ensures the graph is in the mutable, Dynamic state.

fn get_graph(&self) -> &UltraGraphWeighted<Causaloid<I, O, PS, C>, u64>

Returns a reference to the underlying CausalGraph.

fn add_root_causaloid( &mut self, value: Causaloid<I, O, PS, C>, ) -> Result<usize, CausalityGraphError>

Adds a special “root” causaloid to the graph.

fn contains_root_causaloid(&self) -> bool

Checks if a root causaloid has been set in the graph.

fn get_root_causaloid(&self) -> Option<&Causaloid<I, O, PS, C>>

Retrieves an immutable reference to the root causaloid, if it exists.

fn get_root_index(&self) -> Option<usize>

Retrieves the index of the root causaloid, if it exists.

fn get_last_index(&self) -> Result<usize, CausalityGraphError>

Gets the index of the last causaloid added to the graph.

fn add_causaloid( &mut self, value: Causaloid<I, O, PS, C>, ) -> Result<usize, CausalityGraphError>

Adds a new causaloid (node) to the graph.

fn contains_causaloid(&self, index: usize) -> bool

Checks if a causaloid exists at a specific index in the graph.

fn get_causaloid(&self, index: usize) -> Option<&Causaloid<I, O, PS, C>>

Retrieves an immutable reference to a causaloid at a given index.

fn remove_causaloid( &mut self, index: usize, ) -> Result<(), CausalGraphIndexError>

Removes a causaloid from the graph at the specified index.

fn add_edge(&mut self, a: usize, b: usize) -> Result<(), CausalGraphIndexError>

Adds a directed edge between two causaloids in the graph.

fn add_edg_with_weight( &mut self, a: usize, b: usize, weight: u64, ) -> Result<(), CausalGraphIndexError>

Adds a weighted directed edge between two causaloids.

fn contains_edge(&self, a: usize, b: usize) -> bool

Checks if a directed edge exists from causaloid a to causaloid b.

fn remove_edge( &mut self, a: usize, b: usize, ) -> Result<(), CausalGraphIndexError>

Removes a directed edge between two causaloids.

fn size(&self) -> usize

Returns the total number of causaloids (nodes) in the graph.

fn is_empty(&self) -> bool

Checks if the graph contains no causaloids.

fn clear(&mut self)

Removes all causaloids and edges from the graph.

fn number_edges(&self) -> usize

Returns the total number of edges in the graph.

fn number_nodes(&self) -> usize

Returns the total number of causaloids (nodes) in the graph.

fn freeze_dag(&mut self) -> Result<(), CausalityGraphError>

Freezes the graph for reasoning only if it is acyclic (a directed acyclic graph).

fn freeze_verified( &mut self, state_writers: &[usize], ) -> Result<(), CausalityGraphError>

where Self: Sized,

Freezes the graph with the full Stage-4 precondition checks: acyclicity (freeze_dag) plus the single-writer invariant at reconvergent joins — the structural preconditions the schedule-invariance theorem (core.causaloid.graph_fold_order_invariant) assumes.

fn freeze_verified_with_check<F>( &mut self, state_writers: &[usize], level_check: F, ) -> Result<(), CausalityGraphError>

where F: Fn(&Self) -> Result<(), CausalityGraphError>, Self: Sized,

freeze_verified with a level-specific hook — the extension point for stack-level structural checks (e.g. the quantum layer’s commuting-factorization check; the QCM-on-EPP freeze model). The hook runs after the built-in checks pass, on the frozen graph; a hook error rolls the graph back to the dynamic state.

fn check_single_writer( &self, state_writers: &[usize], ) -> Result<(), CausalityGraphError>

The single-writer check on the frozen graph (see freeze_verified). Split out so hooks and tests can run it directly.

fn get_shortest_path( &self, start_index: usize, stop_index: usize, ) -> Result<Vec<usize>, CausalityGraphError>

Default implementation for shortest path algorithm.

impl<T: Clone + Clone> Clone for CausaloidGraph<T>

fn clone(&self) -> CausaloidGraph<T>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for CausaloidGraph<CausaloidId>

fn default() -> Self

Returns the “default value” for a type.

impl Identifiable for CausaloidGraph<CausaloidId>

fn id(&self) -> u64

impl<V, PS, C> MonadicCausableGraphReasoning<V, PS, C> for CausaloidGraph<Causaloid<V, V, PS, C>>

where V: Verdict + Default + Clone + Send + Sync + 'static + Debug, PS: Default + Clone + Send + Sync + 'static, C: Clone + Send + Sync + 'static, Causaloid<V, V, PS, C>: MonadicCausable<V, V>,

fn evaluate_single_cause( &self, index: usize, effect: &PropagatingEffect<V>, ) -> PropagatingEffect<V>

Evaluates a single, specific causaloid within the graph by its index using a monadic approach.

fn evaluate_subgraph_from_cause( &self, start_index: usize, initial_effect: &PropagatingEffect<V>, ) -> PropagatingEffect<V>

Reasons over the acyclic sub-DAG reachable from a start index using a monadic approach.

fn evaluate_subgraph_from_cause_with_lambda_edges( &self, start_index: usize, initial_effect: &PropagatingEffect<V>, lambda_edges: &LambdaEdges<V>, ) -> PropagatingEffect<V>

evaluate_subgraph_from_cause with per-edge Λ decoration slots: the value flowing along a decorated edge is transformed by that edge’s Λ (keyed by intrinsic (source, target) identity, never by order; absent slot = identity) before any join, so a reconvergent join computes ∇(Λ₁(a), Λ₂(b)) — Hardy’s connection data on the edges, the commutative fuse at the node (core.causaloid.inversion, core.causaloid.graph_fold_order_invariant).

fn evaluate_shortest_path_between_causes( &self, start_index: usize, stop_index: usize, initial_effect: &PropagatingEffect<V>, ) -> PropagatingEffect<V>

Reasons over the shortest path between a start and stop cause using a monadic approach.

impl<V, S, C> StatefulMonadicCausableGraphReasoning<V, S, C> for CausaloidGraph<Causaloid<V, V, S, C>>

where V: Default + Clone + Send + Sync + 'static + Debug, S: Default + Clone + Send + Sync + 'static + Debug, C: Clone + Send + Sync + 'static, Causaloid<V, V, S, C>: MonadicCausable<V, V> + StatefulMonadicCausable<V, V, S, C>,

fn evaluate_single_cause_stateful( &self, index: usize, effect: &PropagatingProcess<V, S, C>, ) -> PropagatingProcess<V, S, C>

Stateful counterpart to crate::MonadicCausableGraphReasoning::evaluate_single_cause.

fn evaluate_subgraph_from_cause_stateful( &self, start_index: usize, initial_effect: &PropagatingProcess<V, S, C>, ) -> PropagatingProcess<V, S, C>

Stateful counterpart to crate::MonadicCausableGraphReasoning::evaluate_subgraph_from_cause.

fn evaluate_shortest_path_between_causes_stateful( &self, start_index: usize, stop_index: usize, initial_effect: &PropagatingProcess<V, S, C>, ) -> PropagatingProcess<V, S, C>

Stateful counterpart to crate::MonadicCausableGraphReasoning::evaluate_shortest_path_between_causes.