Overview of DeepCausality

Built on a Single Axiomatic Foundation

DeepCausality is an open-source project hosted at the Linux Foundation for Data & AI, and it is the reference implementation of the EPP. The EPP rests on a single axiom: every effect is derived from a prior effect by a causal function embedded into a monadic composition, written m₂ = m₁ >>= f. This generalizes causality so that the classical definition becomes a special case of it. The framework can therefore express five established methods of classical causality, as demonstrated in the classical causality code examples.

This reframing makes the explicit Context and the Causaloid first-class structures in the library. One important conjecture that follows is that the field of function theory becomes applicable to causality. For the user, the payoff is a single, coherent way to model dynamic causality in physics, finance, and any other science or engineering domain that involves complex dynamic processes.

A Layered Rust Stack

The DeepCausality project comprises a set of crates that together realize dynamic causality, each also usable on its own within the Rust ecosystem. The project is organized as a layered scientific-computing stack with the causal layer on top, and the layers compose through the higher-kinded type machinery established in the foundation layer. The stack consists of a foundation layer, the mathematical layers, a physics layer, the causal layer that defines dynamic causality, and a causal-discovery layer, with a horizontal metric crate providing a single source of truth for sign conventions across all of them.

Foundation layer

Three crates establish the foundation the DeepCausality project is built upon. The numerical foundation library (deep_causality_num) provides a complete trait hierarchy for abstract algebra, encoding the categorical structure of mathematical objects in the Rust type system. The hierarchy ranges from foundational structures (Magma, Semigroup, Monoid) through groups (Group, AbelianGroup) and rings (Ring, AssociativeRing, CommutativeRing, EuclideanDomain) to fields (Field, RealField, ComplexField) and module-and-algebra structures (Module, Algebra, AssociativeAlgebra, DivisionAlgebra), wired so that types implementing each level satisfy the corresponding mathematical laws as compile-time assertions. The crate also provides Float106, a 106-bit high-precision floating-point type with approximately thirty-two decimal digits of precision, comparable to IEEE binary128 but available now on stable Rust and several times faster on most hardware. Full implementations of Complex, Quaternion, and Octonion as division algebras are included. The library is macro-free, unsafe-free, and dependency-free, and supports no-std environments.

The higher-kinded type crate (deep_causality_haft) provides a working implementation of arity-5 higher-kinded types in Rust through type-level encoding and the witness pattern. It supplies the Effect, Functor, Applicative, Monad, CoMonad, and Arrow trait families that all higher layers build on. Rust does not provide higher-kinded types natively, and the haft crate is what allows the mathematical and causal crates to compose monadically; its value-level Arrow algebra is the foundation for the control flow in the Causal Flow Language described below.

The metric crate (deep_causality_metric) provides a single source of truth for metric signatures across the stack. It defines the East Coast convention (used in general relativity), the West Coast convention (used in particle physics), and the broader Clifford signature space Cl(p, q, r) that the multivector and topology crates build on. Its horizontal placement is what allows a particle-physics calculation in one layer and a general-relativity calculation in another to share compatible sign conventions without manual coordination, eliminating an entire class of consistency bugs.

Causal layer

The core crate (deep_causality_core) provides DeepCausality's foundational types: PropagatingEffect for stateless causal effects, PropagatingProcess for stateful effects with state and configuration channels, the CausalMonad with its bind operation, and the Causal Effect System runtime that coordinates causal models.

The main crate (deep_causality) builds on the core and on the wider stack to provide the Causaloid in its three isomorphic forms (Singleton, Collection, Graph), the Context with its Euclidean and non-Euclidean representations, the Causal State Machine, the Teloid and Effect Ethos for deontic governance, and the integration of all of these into one working framework. UltraGraph (ultragraph) is a high-performance two-phase hypergraph data structure that supports the CausaloidGraph and the Context Hypergraph and is independently usable wherever performance-constrained hypergraph composition is needed. The Uncertain type (deep_causality_uncertain) is a Rust implementation of Bornholt's Uncertain<T> as a first-order type for uncertain data.

The developer-facing surface is the Causal Flow Language (CFL), a fluent DSL exposed as CausalFlow in the deep_causality crate. It reaches the full expressiveness of the causal monad without its complexity: value seeds a chain, try_step and map transform it, branch chooses, and iterate_n, iterate_until, and iterate_to_fixpoint loop. Each verb lowers to the monad's bind and threads the value, state, context, error, and log channels automatically. Underneath, the Causal Arrow realizes the value-level Arrow algebra over the causal monad as its Kleisli arrow, so a pipeline is itself a reusable value that can be built once and run over many inputs.

Composition through higher-kinded types means that a tensor of multivectors over a topology defined as a lattice gauge field, with each layer respecting the algebraic laws of the underlying types and all sharing the metric crate's sign conventions, is expressible as a single type and operates monadically across the stack.

Causal discovery layer

The Causal Discovery Language (CDL, deep_causality_discovery) is a domain-specific language that bridges from raw observational data to executable causal models. It hosts two discovery algorithms as type-encoded peers: SURD, an information-theoretic decomposition that separates what a variable explains uniquely from what it shares redundantly and what emerges only from synergy; and BRCD (Bayesian Root-Cause Discovery), which ranks the variables whose conditional mechanism changed between a healthy and a failing regime to point an operator at the root cause of an incident. A configuration object is the single source of truth for a run: a staged typestate builder makes every required field a compile-time obligation and checks referenced files before the pipeline starts, after which the parameterless stages read only from that configuration. The chosen configuration selects one of two compile-time-isolated sub-pipelines that share no state until they converge at finalization, so asking a BRCD pipeline to select features, or crossing the two pipelines, does not compile. BRCD accepts an optional CPDAG over the variables when the causal structure is already known, and learns one from the normal data via the BOSS algorithm when none is supplied. The discovery language closes the loop from observational data to causal model that is left open in most causal frameworks.

Mathematical layers

Five crates provide the mathematical structures and operators over the foundation, most carrying higher-kinded type instances that allow composition with the others and with the causal layer. The tensor crate (deep_causality_tensor) provides multi-dimensional arrays with stride-based memory layout, broadcasting for element-wise operations, Einstein summation for matrix products and contractions, and Functor, Applicative, Monad, and CoMonad instances for functional composition.

The sparse crate (deep_causality_sparse) provides a compressed-sparse-row (CSR) matrix, the right representation when a system is large but mostly zeros, as causal graphs, discretized operators, and lattice problems usually are. It ships a conjugate-gradient solver for symmetric positive-definite systems, a higher-kinded type instance so a sparse matrix composes like the other structures, and optional zero-copy interop with the tensor crate.

The multivector crate (deep_causality_multivector) provides Clifford algebras over the dynamic signature space, with pre-configured constructors for Pauli algebra, spacetime algebra, conformal geometric algebra, projective geometric algebra in three dimensions, the Dixon algebra used in Standard Model particle physics, and the Grand Unified Algebra hosting the full spin(10) gauge symmetry. It implements Functor, Applicative, and Monad instances where the bind operation realizes the tensor product of algebras, allowing dimension-changing compositions to be expressed monadically.

The topology crate (deep_causality_topology) provides graphs, hypergraphs, simplicial complexes, manifolds, and point clouds, together with differential geometry operators (exterior derivative, Hodge star, codifferential, Hodge-Laplacian) and a lattice gauge field framework supporting U(1), SU(2), SU(3), and Lorentz gauge groups. The lattice gauge implementation is verified against twenty-four reference results from Creutz's Quarks, Gluons and Lattices. It implements Functor and BoundedComonad instances, which makes graph convolutions and cellular automata expressible through the comonadic extend operation.

The calculus crate (deep_causality_calculus) provides Arrow-native differentiation and integration operators. Differentiation is the tangent functor over dual numbers, exposed fluently as model.derivative(x) and field.gradient(&x). Integration is endomorphism iteration, with Euler and RK4 steppers driven by iterate_n, iterate_to_fixpoint, and iterate_until for fixed-horizon, steady-state, and integrate-until-event runs, while a quadrature fold integrates a closed-form integrand. Every operator is generic over the scalar type, so precision is a free parameter and dual numbers nest for higher derivatives, while the dual machinery, step coefficients, and loops stay invisible to the user.

These crates share the same higher-kinded type instances, which makes them freely combinable through one uniform mathematical surface. A single Functor, Monad, and CoMonad interface spans tensor algebra, multivectors, and topology; the sparse matrices plug into the same interface; and the calculus operators compose over all of them through the shared Arrow algebra. Tensor algebra combines with topology, with sparse representations, and now with calculus, each respecting the algebraic laws of the others, so a single computation can move across them without leaving the abstraction. The Uniform Math concept page covers the full surface.

Physics layer

The physics library (deep_causality_physics) builds on the layers below it, with kernels organized into thematic domains spanning astrophysics, condensed matter, classical dynamics, electromagnetism, fluid dynamics, materials science, magnetohydrodynamics, nuclear physics, photonics, quantum mechanics, relativity, thermodynamics, and wave mechanics, all using type-safe units. The library separates two levels of usage. Physics kernels are pure stateless functions for isolated equations such as the Schwarzschild radius, the Lorentz force, the Klein-Gordon equation, or the Lund string fragmentation; each kernel has a corresponding wrapper that lifts the return type into a propagating effect for composition in a causal pipeline. Theories are full physical frameworks (general relativity, electromagnetism, weak force, electroweak unification) implemented as gauge theories over the topology crate's gauge field abstraction, so different physical theories share the same field-strength computation, parallel transport, and Bianchi-identity machinery, with the gauge group as the only differentiator. The physics library is also generic over the floating-point type, so a simulation can run at single, double, or Float106 precision by changing a single type alias.

Because every physics kernel and theory ships a wrapper that lifts its result into a propagating effect or propagating process, physics plugs straight into the causal monad and the Causaloid. That cross-domain composition, physics together with any of the mathematical crates and with causal reasoning, rests on two shared foundations: the higher-kinded type machinery in deep_causality_haft and the common numeric tower in deep_causality_num.

A Computable Ethics Framework

Traditional causal models are overwhelmingly focused on passive inference and prediction. They provide a powerful way to answer "what if" questions but lack a formal, verifiable, and safe bridge from that knowledge to taking action. Safety, ethics, and alignment are treated as post hoc problems to be solved with testing and ad hoc rules.

DeepCausality treats verifiable safety as a first-class concern, built directly into the framework rather than bolted on afterward. The goal is to safeguard causal emergence, and the library provides two mechanisms:

• The Causal State Machine (CSM): links a causal inference to a deterministic action.
• The Effect Ethos: allows a system to formally verify that a proposed action is compliant with its mission and safety objectives before it is executed.

With the Effect Ethos, DeepCausality offers a feasible roadmap for building trustworthy, high-stakes autonomous systems that adhere to contextual rules of engagement encoded in an immutable ethos. The Effect Ethos inverts the verification and validation model by shifting safety objectives into the pre-design stage, converting existing rules of engagement into a testable ethos, which enables design-time safety and provable alignment.

Code Examples

Dynamic causal processes are deeply embedded in every major science and engineering domain, and the project reflects that. DeepCausality ships more than one hundred code examples spanning aerospace, astrophysics, medicine, materials science, geodesy, quantum computing, and classical causal inference.

The uniform math makes all of these advanced examples possible, because tensors, multivectors, topology, sparse matrices, and calculus compose uniformly. That means a single dynamic causal process can be multidisciplinary, multi-stage, and multi-physics at once. A handful of examples illustrate the range of applications DeepCausality enables.

• Recovering a planet's mass from clock data (geodesy): a multi-stage pipeline recovers Earth's geocentric gravitational constant, and from it the planetary mass, out of one GPS week of Galileo satellite-clock time-dilation data, validated against published references at about 0.2 percent. It effectively inverts general relativity in a few lines of code.
• General-relativistic magnetohydrodynamics (astrophysics): magnetized plasma flow is modeled under general relativity, composing several physical theories in one dynamic causal pipeline.
• Epilepsy surgery screening (medicine): each candidate brain region is evaluated as a counterfactual, do(connectome = resected), ranking resections by their predicted effect before anyone operates.
• Flight-envelope health monitoring (aerospace): one stateful pipeline collects sensor data, threads it through a bind chain, and checks it against an envelope hypergraph, with state and an audit log accumulating across every stage.
• Elastic stress on a tetrahedral mesh (materials engineering): strain, Hooke's law, Cauchy traction, a material rotor, and von Mises stress are computed across a 3D mesh in one comonadic extend, combining the tensor, multivector, and topology crates in a single expression.

These examples only scratch the surface. The full catalog reaches into thermodynamics, optics, fluid dynamics, electromagnetism, quantum field theory, oncology, cardiovascular medicine, metamaterials, and root-cause analysis, among others. Browse all examples in the project repository.