---

---

Website | Getting started | Blog | Discord | Crates

Dynamic Causality for a Dynamic World

DeepCausality is the reference implementation of the Effect Propagation Process (EPP), a single axiomatic foundation for dynamic causality built on Whitehead's process metaphysics, which makes the framework general-relativistic-native and quantum-native. Classical computational causality frameworks (Pearl's SCM, Granger causality, DBNs) assume a fixed background spacetime and a static causal structure, so they cannot model causal structures that change. DeepCausality treats dynamic, adaptive, and emergent causality as first-class modalities and adds a programmable deontic layer for verifiable safety. DeepCausality is a sandbox project at the Linux Foundation for Data & AI.

Support

Dynamic causality can be daunting at first. For support on a larger or commercial project, contact the Center for Dynamic Causality, which backs the DeepCausality project.

Getting Started

For LLM-assisted project-building guidance, see SKILLS.md.

cargo add deep_causality_core

Counterfactual & Intervention Example

use deep_causality_core::{AlternatableValue, PropagatingEffect};

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

    // Intervention: replace the value MID-CHAIN with BloodLevel := 3.0
    let intervened = PropagatingEffect::pure(10.0_f64)
        .fmap(|dose| dose * 0.8)   // Absorption: 8.0
        .alternate_value(3.0)      // ← Force BloodLevel to 3.0; the log records the substitution
        .fmap(|level| level - 2.0) // Metabolism: 1.0
        .fmap(|level| if level > 5.0 { "Effective" } else { "Ineffective" });
    // Result: "Ineffective" — intervention changed the outcome

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

This walks Pearl's Ladder of Causation:

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

DeepCausality can express all major frameworks of classical computational causality.

---

Examples

# Regime change: causal structure evolves as the system crosses a physical threshold
cargo run -p physics_examples --example event_horizon_probe

# Compositional pipeline: Causaloid evaluations interleaved with CausalMonad bind
cargo run -p avionics_examples --example flight_envelope_monitor

See examples/README.md for the full catalogue of available examples.

---

What is Unique

One axiom, three primitives	Causaloid, Context, and Causal State Machine derived from a single functional-dependency axiom
Three causal modalities	Dynamic, adaptive, and emergent causality, going beyond the static-structure assumption
Effect Propagation Monads	PropagatingEffect and PropagatingProcess for composable causal pipelines
Effect Ethos	Defeasible deontic calculus (after Forbus) that verifies actions against an immutable ethos before execution
Uniform mathematics	Tensors, MultiVectors, Manifolds, and PropagatingEffect share one categorical interface (Functor / Monad / Comonad) via arity-5 HKT in stable Rust; multi-physics pipelines compose across domains in a single monadic flow
Geometric Algebra	Clifford algebras (Pauli, spacetime, conformal, projective, Dixon, Spin(10) GUA) with shared metric conventions
Differential Topology	Manifolds, simplicial complexes, lattice gauge theory verified against 24 reference results from Creutz
Float106 precision	106-bit float (~32 decimal digits) on stable Rust, several × faster than IEEE binary128
Causal Discovery	SURD and MRMR algorithms wrapped in a typestate DSL that closes the loop from data to model

---

Architecture

The EPP rests on a single axiom: m₂ = m₁ >>= f. Effect propagation is a monadic dependency that assumes no background spacetime. Three computable primitives implement the axiom; an optional fourth, the safety layer, governs emergent behaviour.

The Three Primitives

1. Causaloid and CausalMonad

The monadic axiom admits two isomorphic expressions of the same causal computation. Both are first-class causal entities; neither is more fundamental.

• Causaloid. A polymorphic container for the causal function f (after Hardy). It carries causal structure and is isomorphic across three forms (Singleton, Collection, Graph), so recursive causal structures compose without changes to the calling code.
• CausalMonad. The bind side of the axiom, carrying causal sequencing through Kleisli composition. bind short-circuits on error, accumulates the audit log, and supports counterfactual value substitution through alternate_value.

Both inhabit the same propagating-effect carrier:

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

Both consume and produce the same carrier, so they compose freely: a Causaloid evaluation can feed a .bind() step, a .bind() step can feed a Causaloid evaluation, and state and audit log accumulate across both. One pipeline can mix structural and sequential reasoning and pick the shape that fits each stage:

• Sequential transforms belong in a CausalMonad bind-chain.
• Parallel aggregation belongs in a Causaloid collection.
• Cross-influencing dependencies belong in a Causaloid graph.

The flight envelope monitor shows all three: a Causaloid collection over five sensor-health checks, a three-step CausalMonad bind-chain for state estimation, and a Causaloid hypergraph of six envelope protections, all running through one PropagatingProcess<T, FlightState, AircraftConfig> with state and audit log threaded across every stage.

2. Context

An explicit hypergraph carrying the operational environment: sensor data, temporal structures (linear and non-linear), spatial locations (Euclidean and non-Euclidean). The Context must be queryable and dynamic for causality to detach from a fixed background spacetime.

3. Causal State Machine (CSM)

The CSM connects causal inference to action. It separates state from action, so a proposed action can be verified before it executes.

The Safety Layer

Effect Ethos

An optional, programmable deontic layer that uses a defeasible deontic calculus to resolve normative conflicts and decide whether a CSM-proposed action is permissible under an immutable ethos. It is required wherever causality is emergent, because static verification is impossible there.

Uniform mathematics

Scientific-computing stacks often split tensors, geometric algebra and topology across separate libraries joined by glue code. DeepCausality lifts each mathematical layer into one categorical interface through the deep_causality_haft crate's arity-5 higher-kinded types:

Domain	Type	Categorical role
Mechanics	CausalTensor<T>	Functor (map over field data)
Algebra	CausalMultiVector<T>	Monad (chain operations)
Topology	Manifold<T>	Comonad (neighborhood analysis)
Causality	PropagatingEffect<T>	Monad (sequencing + logs)

A single bind-chain can therefore step from a Tensor (general relativity), through a MultiVector (geometric algebra), onto a Manifold (topology), and finish in a PropagatingEffect (causal logic) without serialisation or adapter code. The GRMHD example does this for relativistic magnetohydrodynamics: Einstein tensor curvature feeds metric selection, which feeds a multivector Lorentz force, which feeds causal stability analysis, all in one monadic chain. The Maxwell example derives E and B as bivector grades of a single electromagnetic field F = ∇A, which cuts the scalar count from six to four (~50% compute reduction) and applies to 5G/6G phased-array antenna design.

---

Crate Ecosystem

Causal Discovery

Crate	Description
deep_causality_discovery	Causal Discovery Language (typestate DSL: load → clean → select → discover → analyse)
deep_causality_algorithms	SURD, MRMR, and feature-selection primitives

Causal Framework

Crate	Description
deep_causality	Causaloid (Singleton/Collection/Graph), CausaloidGraph reasoning, CSM
deep_causality_context	Context hypergraph: contextoids and data, space, time and spacetime nodes
deep_causality_context_store	Persistence contract for Context: the records it projects onto and the ContextStorage trait a backend implements
deep_causality_core	PropagatingEffect, PropagatingProcess, CausalMonad, CausalArrow, CausalFlow
deep_causality_ethos	EffectEthos and Teloid for defeasible deontic reasoning
deep_causality_uncertain	Uncertain<T> and MaybeUncertain<T> (after Bornholt et al.)

Physics

Crate	Description
deep_causality_physics	Astrophysics, condensed matter, EM, fluids, MHD, nuclear, photonics, QM, relativity, thermo, waves; generic over float type
deep_causality_cfd	Counterfactual fluid dynamics: DEC and tensor-train solvers behind the CfdFlow DSL, coupling flow, chemistry, navigation and control in one run. Site: cfd.deepcausality.com

Mathematics

Crate	Description
deep_causality_tensor	N-dim tensors, broadcasting, Einstein summation, Functor/Applicative/Monad/Comonad
deep_causality_multivector	Clifford algebras: Pauli, STA, CGA, PGA(3), Dixon, Spin(10) GUA
deep_causality_topology	Graphs, hypergraphs, simplicial complexes, manifolds, point clouds, exterior calculus, U(1)/SU(2)/SU(3)/Lorentz lattice gauge fields
deep_causality_linear	Sparse (CSR), dense and bit-packed 𝔽₂ matrices, vectors, elimination, decompositions, conjugate gradient, exact integer path

Foundation

Crate	Description
deep_causality_num	Numerical traits (casts, identity, float, integer) and Float106
deep_causality_haft	Arity-5 higher-kinded types via witness pattern; Effect / Functor / Applicative / Monad / CoMonad
deep_causality_metric	Single source of truth for metric signatures (East Coast, West Coast, Cl(p,q,r))
ultragraph	Two-phase hypergraph backend for CausaloidGraph and Context

Utilities

Crate	Description
deep_causality_data_structures	Sliding-window, grid-array, and other specialised structures
deep_causality_rand	RNGs, uniform range sampling, Sobol sequences
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 builds with Bazel. Install bazelisk and run:

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

Every example is a Bazel binary except example_ml_rca in causal_discovery_examples, which is Cargo-only: CARGO_ONLY in scripts/check_examples.sh lists it, so the example-coverage check expects no Bazel target for it. The two commands in the Examples section run under Bazel as:

bazel run //examples/physics_examples:event_horizon_probe
bazel run //examples/avionics_examples:flight_envelope_monitor

Examples that read bundled data or record an output table resolve those paths against the workspace root, so they read and write the same files under either build system. make check_examples verifies that no Cargo example is missing its Bazel target.

---

Contributing

Contributions are welcome. Please read:

• AI Coding Assistants
• Contributing Guide
• Code of Conduct

# Before submitting a PR
make test
make check

---

Acknowledgement

Inspired by research from:

• Judea Pearl: Structural Causal Models
• Lucien Hardy: Causaloid framework
• Elias Bareinboim: Transportability and data fusion

Implemented research:

deep_causality

• "Probability Theories with Dynamic Causal Structure", Hardy

deep_causality_algorithms

• "Root Cause Analysis of Failures in Microservices via Bayesian Root Cause Discovery"
• Maximum Relevance and Minimum Redundancy Feature Selection
• "Observational causality by states and interaction type for scientific discovery"

deep_causality_ethos

• "A Defeasible Deontic Calculus for Resolving Norm Conflicts", Olson & Forbus

deep_causality_multivector

• "An Algebraic Roadmap of Particle Theories"

deep_causality_uncertain

• "Uncertain⟨T⟩: A First-Order Type for Uncertain Data", Bornholt et al.

Ultragraph

• "NWHy: A Framework for Hypergraph Analytics"

---

Community

• Discord
• GitHub Discussions
• LF Email Lists

---

👮 Security

The DeepCausality project follows the Linux Foundation CRA stewardship framework to comply with the EU Cyber Resilience Act (CRA).

See SECURITY.md for security policies and details.

---

Sponsors

JetBrains provides project core maintainers with an all-product license.

The Center for Dynamic Causality contributes ongoing research and resources to the DeepCausality project.

---

License

This project is licensed under the MIT license.