---

---

Website | Getting started | Documentation | Blog | Discord | Crates

DeepCausality

A hypergeometric computational causality library for building systems that reason about cause and effect.

DeepCausality pioneers uniform reasoning across deterministic and probabilistic modalities, supporting both static and dynamic contextual causal models. The project is hosted as a sandbox project in the Linux Foundation for Data & AI.

✨ Key Features

Feature	Description
Effect Propagation Monads	PropagatingEffect and PropagatingProcess for composable causal computations
Geometric Algebra	Universal Clifford Algebra via CausalMultiVector for physics and quantum mechanics
Differential Topology	Manifold, SimplicialComplex, and discrete exterior calculus
Tensor Operations	CausalTensor with Einstein summation (ein_sum) and linear algebra
Causaloid Graphs	Recursive, composable causal structures with graph-based reasoning
Effect Ethos	Deontic guardrails using defeasible calculus for safe AI actions
Causal Discovery	SURD and MRMR algorithms for learning causal structure from data
Multi-Physics	Quantum mechanics, thermodynamics, electromagnetism, fluids, relativity

---

🏗️ Architecture

DeepCausality's architecture is built on a unified foundation: causality as monadic dependency (E₂ = f(E₁)). From this axiom, the framework derives its core abstractions.

The Causal Monad & PropagatingEffect

At the heart of DeepCausality is the Causal Monad pattern, implemented through two primary types:

Type	Purpose	State
PropagatingEffect<T>	Stateless effect propagation	Value + Error + Log
PropagatingProcess<T>	Stateful effect propagation	Value + State + Context + Error + Log

These monads enable composable causal computations where effects flow through a pipeline of transformations wth the following key properties:

• Error propagation: Errors short-circuit the chain automatically
• Logging: Each step can append to an audit trail
• Counterfactuals: bind supports hypothetical "what-if" reasoning

The Three Pillars

1. The Causaloid

A self-contained unit of causality that holds a causal function, receives an incoming effect, and emits a new outgoing effect. Causaloids compose into graphs for complex reasoning.

2. The Context

An explicit hypergraph data structure that holds all factual data about the operational environment: sensor readings, temporal structures, spatial locations, and more.

3. The Effect Ethos

A programmable deontic layer that verifies whether proposed actions align with safety and mission objectives before execution.

---

🚀 Getting Started

Add DeepCausality to your project:

cargo add deep_causality_core

Counterfactual & Intervention Example

use deep_causality_core::{Intervenable, PropagatingEffect};

fn main() {
    // Causal chain: Dose → Absorption → Metabolism → Response
    let observed = PropagatingEffect::pure(10.0_f64)
        .bind(|dose, _, _| PropagatingEffect::pure(dose * 0.8))   // Absorption: 8.0
        .bind(|level, _, _| PropagatingEffect::pure(level - 2.0)) // Metabolism: 6.0
        .bind(|level, _, _| {
            let response = if level > 5.0 { "Effective" } else { "Ineffective" };
            PropagatingEffect::pure(response)
        });
    // Result: "Effective"

    // Intervention: Replace value MID-CHAIN with do(BloodLevel := 3.0)
    let intervened = PropagatingEffect::pure(10.0_f64)
        .bind(|dose, _, _| PropagatingEffect::pure(dose * 0.8))   // Absorption: 8.0
        .intervene(3.0)  // ← Force BloodLevel to 3.0, preserving log
        .bind(|level, _, _| PropagatingEffect::pure(level - 2.0)) // Metabolism: 1.0
        .bind(|level, _, _| {
            let response = if level > 5.0 { "Effective" } else { "Ineffective" };
            PropagatingEffect::pure(response)
        });
    // Result: "Ineffective" — intervention changed the outcome

    println!("Observed:   {:?}", observed.value());   // "Effective"
    println!("Intervened: {:?}", intervened.value()); // "Ineffective"
}

This demonstrates Pearl's Ladder of Causation:

1. Association (Rung 1): Observing dose=10 correlates with "Effective"
2. Intervention (Rung 2): intervene(3.0) forces a value mid-chain
3. Counterfactual (Rung 3): Same chain, different outcome due to intervention

---

📂 Examples

Run examples with:

# Classical Causality (CATE, DBN, Granger, SCM)
cargo run -p classical_causality_examples --example scm_example

# Medicine & Life Sciences
cargo run -p medicine_examples --example protein_folding
cargo run -p medicine_examples --example mri_tissue_classification

# Physics (Quantum, Electromagnetism, Relativity)
cargo run -p physics_examples --example maxwell_example
cargo run -p physics_examples --example geometric_tilt_example
cargo run -p physics_examples --example quantum_counterfactual
cargo run -p physics_examples --example gravitational_wave

# Causal State Machine
cargo run -p csm_examples --example csm_effect_ethos_example

For more examples, See examples/README.md

---

📦 Crate Ecosystem

Core Framework

Crate	Description
deep_causality	Main library with Causaloid, Context, CSM, and Model types
deep_causality_core	PropagatingEffect, PropagatingProcess, and CausalEffectSystem
deep_causality_ethos	Deontic reasoning with EffectEthos and Teloid

Mathematics & Physics

Crate	Description
deep_causality_multivector	Clifford Algebra with CausalMultiVector and HilbertState
deep_causality_tensor	N-dimensional tensors with Einstein summation
deep_causality_topology	Manifold, SimplicialComplex, Graph, Hypergraph, PointCloud
deep_causality_physics	Quantum, thermodynamics, electromagnetism, fluids, relativity kernels
deep_causality_sparse	Compressed sparse row matrices
deep_causality_num	Complex numbers, division algebras, numeric traits

Data & Algorithms

Crate	Description
deep_causality_discovery	Causal Discovery Language (CDL) with SURD and MRMR
deep_causality_algorithms	Feature selection and causal discovery algorithms
deep_causality_data_structures	Specialized data structures
ultragraph	High-performance hypergraph backend

Utilities

Crate	Description
deep_causality_haft	Higher-kinded types and abstract functional types
deep_causality_uncertain	Uncertain<T> and MaybeUncertain<T> for uncertainty propagation
deep_causality_rand	Random number generation and statistical distributions
deep_causality_macros	Procedural macros
deep_causality_ast	Generic abstract syntax tree

---

🛠️ Build & Test

# Optimized build with SIMD
RUSTFLAGS='-C target-cpu=native' cargo build --release

# Run all tests
cargo test --all

# Run benchmarks
cargo bench

Using Make

make install   # Install dependencies
make build     # Build incrementally
make test      # Run all tests
make example   # Run examples
make check     # Security audit

Using Bazel

The repository also supports Bazel builds. Install bazelisk and run:

bazel build //...
bazel test //...

---

📚 Documentation

Resource	Link
API Reference	docs.rs/deep_causality
Core	docs/CORE.md
HAFT	docs/HAFT.md
Ethos	docs/ETHOS.md
Discovery	docs/DISCOVERY.md
Tensor	docs/TENSOR.md
Topology	docs/TOPOLOGY.md
Physics	docs/PHYSICS.md
Unified Math	docs/UNIFIED_MATH.md
Introduction	docs/INTRO.md
Deep Dive	docs/DEEP_DIVE.md
Architecture	deepcausality.com/docs/architecture
Concepts	deepcausality.com/docs/concepts
Changelog	CHANGELOG.md

---

👨‍💻 Contributing

Contributions are welcome! Please read:

• Contributing Guide
• Code of Conduct
• Project Charter

# Before submitting a PR
make test
make check

---

🙏 Credits

Inspired by research from:

• Judea Pearl - Causal inference
• Lucien Hardy - Causaloid framework
• Elias Bareinboim - Causal AI
• Microsoft Research - Causality and ML

Implements research from:

• "An Algebraic Roadmap of Particle Theories"
• "A Defeasible Deontic Calculus for Resolving Norm Conflicts"
• "NWHy: A Framework for Hypergraph Analytics"
• "Observational causality by states and interaction type for scientific discovery"
• "Probability Theories with Dynamic Causal Structure"
• "Uncertain T: A First-Order Type for Uncertain Data"

---

🌐 Community

• Discord
• GitHub Discussions
• LF Email Lists

---

📜 License

This project is licensed under the MIT license.

👮 Security

See SECURITY.md for security policies.

---

🎁 Sponsors

JetBrains provides the project with an all-product license.