Struct Causaloid 

pub struct Causaloid<I, O, STATE, CTX>
where
    I: Default,
    O: Default + Debug,
    STATE: Default + Clone,
    CTX: Clone,
{ /* private fields */ }

Causaloid is the fundamental building block for causal models in DeepCausality.

It represents a self-contained unit of causality, capable of encapsulating various forms of causal logic:

• A single, stateless causal function (CausaloidType::Singleton).
• A single, context-aware causal function (CausaloidType::Singleton with context).
• A collection of other Causaloids (CausaloidType::Collection).
• A directed acyclic graph (DAG) of other Causaloids (CausaloidType::Graph).

Causaloids are generic over their input (I), output (O), state (STATE), and context (CTX).

Type Parameters

• I: The type of the input effect value.
• O: The type of the output effect value.
• STATE: The type for state management (e.g., internal state or aggregation state).
• CTX: The type for context, providing access to external data or environment.

Implementations

impl<I, O, PS, C> Causaloid<I, O, PS, C>

where I: Default, O: Default + Debug, PS: Default + Clone, C: Clone,

pub fn id(&self) -> IdentificationValue

pub fn causal_type(&self) -> &CausaloidType

pub fn causal_fn(&self) -> Option<&CausalFn<I, O>>

pub fn context_causal_fn(&self) -> Option<&ContextualCausalFn<I, O, PS, C>>

pub fn context(&self) -> Option<&C>

pub fn causal_collection(&self) -> Option<&Arc<Vec<Causaloid<I, O, PS, C>>>>

pub fn causal_graph( &self, ) -> Option<&Arc<CausaloidGraph<Causaloid<I, O, PS, C>>>>

pub fn description(&self) -> &str

pub fn coll_aggregate_logic(&self) -> Option<&AggregateLogic>

pub fn coll_threshold_value(&self) -> Option<&NumericalValue>

impl<I, O, STATE, CTX> Causaloid<I, O, STATE, CTX>

where I: Default, O: Default + Debug, STATE: Default + Clone, CTX: Clone,

pub fn new( id: IdentificationValue, causal_fn: CausalFn<I, O>, description: &str, ) -> Self

Creates a new singleton Causaloid with a stateless causal function.

This constructor is used for Causaloids that represent a single, atomic causal relationship defined by a pure function, without requiring any external context.

Arguments

• id - A unique identifier for the causaloid.
• causal_fn - The stateless function that defines the causaloid’s reasoning logic.
• description - A human-readable description of the causaloid.

Returns

A new Causaloid instance of CausaloidType::Singleton.

pub fn new_with_context( id: IdentificationValue, context_causal_fn: ContextualCausalFn<I, O, STATE, CTX>, context: CTX, description: &str, ) -> Self

Creates a new singleton Causaloid with a context-aware causal function.

This constructor is used for Causaloids that represent a single, atomic causal relationship whose logic depends on an external, shared Context.

Arguments

• id - A unique identifier for the causaloid.
• context_causal_fn - The context-aware stateless function for reasoning.
• context - A shared context object accessible by the function.
• description - A human-readable description of the causaloid.

Returns

A new Causaloid instance of CausaloidType::Singleton with an associated context.

impl<I, O, STATE, CTX> Causaloid<I, O, STATE, CTX>

where I: Default, O: Default + Debug, STATE: Default + Clone, CTX: Clone,

pub fn from_causal_collection( id: IdentificationValue, causal_coll: Arc<Vec<Causaloid<I, O, STATE, CTX>>>, description: &str, aggregate_logic: AggregateLogic, threshold_value: NumericalValue, ) -> Self

where I: Send + Sync + 'static, O: Send + Sync + 'static, STATE: Send + Sync + 'static, CTX: Send + Sync + 'static, Causaloid<I, O, STATE, CTX>: MonadicCausable<I, O>,

Creates a new Causaloid that encapsulates a linear collection of other Causaloids.

This allows treating a sequence of causal relationships as a single, composite causal unit. The collection can be evaluated individually, as part of another causal collection, or embedded into a causal graph.

Arguments

• id - A unique identifier for the causaloid.
• causal_coll - An Arc to a vector of child Causaloids forming the collection.
• description - A human-readable description of the causaloid.
• aggregate_logic - The logic used to aggregate the results of the child causaloids.
• threshold_value - A numerical threshold relevant to the aggregation logic.

Type Bounds

The child Causaloids within the collection must implement Send, Sync, and 'static to ensure thread safety and static lifetime requirements for shared ownership. They must also implement MonadicCausable<CausalMonad> for evaluation.

Returns

A new Causaloid instance of CausaloidType::Collection.

pub fn from_causal_collection_with_context( id: IdentificationValue, causal_coll: Arc<Vec<Causaloid<I, O, STATE, CTX>>>, context: CTX, description: &str, aggregate_logic: AggregateLogic, threshold_value: NumericalValue, ) -> Self

where I: Send + Sync + 'static, O: Send + Sync + 'static, STATE: Send + Sync + 'static, CTX: Send + Sync + 'static, Causaloid<I, O, STATE, CTX>: MonadicCausable<I, O>,

Creates a new Causaloid that encapsulates a linear collection of other Causaloids with an associated shared context.

This allows treating a sequence of causal relationships as a single, composite causal unit, where the evaluation of the collection can depend on an external, shared Context.

Arguments

• id - A unique identifier for the causaloid.
• causal_coll - An Arc to a vector of child Causaloids forming the collection.
• context - A shared context object accessible by the collection’s logic.
• description - A human-readable description of the causaloid.
• aggregate_logic - The logic used to aggregate the results of the child causaloids.
• threshold_value - A numerical threshold relevant to the aggregation logic.

Type Bounds

The child Causaloids within the collection must implement Send, Sync, and 'static to ensure thread safety and static lifetime requirements for shared ownership. They must also implement MonadicCausable<CausalMonad> for evaluation.

Returns

A new Causaloid instance of CausaloidType::Collection with an associated context.

pub fn from_causal_graph( id: IdentificationValue, description: &str, causal_graph: Arc<CausaloidGraph<Self>>, ) -> Self

Creates a new Causaloid that encapsulates a causal graph of other Causaloids.

This allows treating a complex, interconnected network of causal relationships as a single, composite causal unit. The graph can be evaluated independently, or embedded into a larger causal structure.

Arguments

• id - A unique identifier for the causaloid.
• description - A human-readable description of the causaloid.
• causal_graph - An Arc to a CausaloidGraph containing the interconnected child Causaloids.

Returns

A new Causaloid instance of CausaloidType::Graph.

pub fn from_causal_graph_with_context( id: IdentificationValue, description: &str, causal_graph: Arc<CausaloidGraph<Self>>, context: CTX, ) -> Self

Creates a new Causaloid that encapsulates a causal graph of other Causaloids with an associated shared context.

This allows treating a complex, interconnected network of causal relationships as a single, composite causal unit, where the evaluation of the graph can depend on an external, shared Context.

Arguments

• id - A unique identifier for the causaloid.
• description - A human-readable description of the causaloid.
• causal_graph - An Arc to a CausaloidGraph containing the interconnected child Causaloids.
• context - A shared context object accessible by the graph’s logic.

Returns

A new Causaloid instance of CausaloidType::Graph with an associated context.

Trait Implementations

impl<I, O, PS, C> Causable for Causaloid<I, O, PS, C>

where I: Default, O: Default + Debug, PS: Default + Clone, C: Clone,

Implements the Causable trait for Causaloid.

This trait provides fundamental properties and methods for any entity that can participate in a causal relationship. For Causaloid, it primarily defines how to determine if a causaloid represents a single, atomic causal unit.

fn is_singleton(&self) -> bool

Checks if the Causaloid is of type Singleton.

A singleton causaloid represents an atomic causal relationship that can be evaluated independently.

Returns

true if the CausaloidType is Singleton, false otherwise.

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 get_shortest_path( &self, start_index: usize, stop_index: usize, ) -> Result<Vec<usize>, CausalityGraphError>

Default implementation for shortest path algorithm.

impl<I, O, STATE, CTX> Clone for Causaloid<I, O, STATE, CTX>

where I: Default, O: Default + Debug, STATE: Default + Clone, CTX: Clone,

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<I, O, PS, C> Debug for Causaloid<I, O, PS, C>

where I: Default, O: Default + Debug, PS: Default + Clone, C: Clone,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<I, O, PS, C> Display for Causaloid<I, O, PS, C>

where I: Default, O: Default + Debug, PS: Default + Clone, C: Clone,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<I, O, PS, C> Identifiable for Causaloid<I, O, PS, C>

where I: Default, O: Default + Debug, PS: Default + Clone, C: Clone,

fn id(&self) -> u64

impl<I, O, PS, C> MonadicCausable<I, O> for Causaloid<I, O, PS, C>

where I: Default + Clone + Send + Sync + 'static + Debug, O: Default + Debug + Clone + Send + Sync + 'static, PS: Default + Clone + Send + Sync + 'static, C: Clone + Send + Sync + 'static,

Implements the MonadicCausable trait for Causaloid.

This implementation provides the core evaluation logic for Causaloids, leveraging monadic principles to handle the flow of effects, errors, and logs.

Note: This base implementation only supports CausaloidType::Singleton. For Collection and Graph evaluation with aggregation support, use the specialized constructors that ensure proper trait bounds are met.

fn evaluate( &self, incoming_effect: &PropagatingEffect<I>, ) -> PropagatingEffect<O>

Evaluates the causal effect of this Causaloid given an incoming_effect.

The evaluation process is monadic, ensuring that errors are propagated and a comprehensive log of operations is maintained.

Important: This base implementation only supports Singleton causaloids. For Collection and Graph types, specialized evaluation methods with proper trait bounds should be used.

Arguments

• incoming_effect - The PropagatingEffect representing the input to this causaloid.

Returns

A PropagatingEffect containing the result of the causal evaluation, any errors encountered, and a complete log of the operations performed.

impl<I, O, PS, C> PartialEq for Causaloid<I, O, PS, C>

where I: Default, O: Default + Debug, PS: Default + Clone, C: Clone,

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.