DeepCausality Overview
Relevant source files
The following files were used as context for generating this wiki page:
DeepCausality is a Rust-based dynamic-causality framework designed for fast, deterministic, and context-aware causal reasoning in advanced systems. It serves as the reference implementation for the Effect Propagation Process (EPP), an axiomatic foundation for causality that is spacetime-agnostic, general-relativistic-native, and quantum-native. Unlike classical frameworks such as Pearl's SCM or Granger causality which assume static structures, DeepCausality supports dynamic, adaptive, and emergent causal modalities.
Sources: README.md:65-74, AGENTS.md:120-125
The project is structured as a 20-crate monorepo, providing a unified mathematical foundation where tensors, geometric algebra, and topology share a single categorical interface. This architecture allows complex multi-physics pipelines to compose across different domains in a single monadic flow.
Sources: README.md:144-149, AGENTS.md:138-140
Core Theoretical Foundation
DeepCausality is built upon the single functional-dependency axiom: m₂ = m₁ >>= f. This axiom defines causality as a monadic dependency where no background spacetime is assumed. The framework operationalizes this axiom through three primary computable primitives and a safety layer for handling emergent behavior.
Sources: README.md:112-117, design.md:124-128
The Three Primitives
- Causaloid and CausalMonad: These represent the structural and sequential expressions of the monadic axiom. They are isomorphic and can be composed freely.
- Context: A dynamic hypergraph that carries the operational environment, including spatial and temporal structures.
- Causal State Machine (CSM): Acts as a bridge between causal inference and action, allowing proposed actions to be verified against state before execution.
Sources: README.md:119-141, AGENTS.md:131-136
Theoretical Components Table
| Component | Description | Primary Role |
|---|---|---|
| Causaloid | Polymorphic container for causal functions. | Structural representation (Singleton, Collection, Graph). |
| CausalMonad | The bind side of the monadic axiom. | Sequential reasoning and Kleisli composition. |
| Context | Hypergraph representing the environment. | Detaching causality from fixed spacetime via queries. |
| CSM | Bridge between inference and action. | Decoupling state from action for verification. |
| Effect Ethos | Deontic safety layer. | Resolving normative conflicts in emergent systems. |
| Sources: README.md:119-142, design.md:129-131 |
System Architecture and Data Flow
DeepCausality utilizes a "Two-State" architecture for its graph structures, specifically within the UltraGraph backend, to solve the conflict between fast mutation and fast traversal.
Sources: lessons-learned-from-rewriting-ultraGraph.md:19-25
The diagram shows the transition between a flexible adjacency list for construction and a Compressed Sparse Row (CSR) format for high-performance analysis.
Sources: lessons-learned-from-rewriting-ultraGraph.md:27-42
Propagating Carriers
The framework uses two primary carriers for effect propagation:
PropagatingEffect<T>: Used for stateless effect propagation, carrying a value, an error, and an audit log.PropagatingProcess<T>: Used for stateful propagation, adding State and Context to the carrier.
Sources: README.md:129-133
Causal Discovery DSL
The deep_causality_discovery crate provides a Domain Specific Language (DSL) for Causal Qualities Discovery (CQD). This DSL utilizes the Typestate Pattern to enforce the semantic order of discovery steps at compile time.
Sources: spec.md:28-35, spec.md:104-106
Discovery Pipeline Workflow
The workflow transitions through several distinct states to ensure data integrity and process validity:
Sources: spec.md:154-171
Discovery Components
| Step | Trait / Type | Description |
|---|---|---|
| Data Loading | ProcessDataLoader | Loads data from CSV or Parquet into a CausalTensor. |
| Feature Selection | FeatureSelector | Applies algorithms like mRMR to rank variables. |
| Discovery | CausalDiscovery | Applies algorithms like SURD to find influences. |
| Analysis | ProcessResultAnalyzer | Recommends Causaloid structures based on results. |
| Formatting | ProcessResultFormatter | Prepares results for human-readable output. |
| Sources: spec.md:116-135 |
Mathematical Foundations
DeepCausality implements a uniform mathematical stack via higher-kinded types (HKT) in the deep_causality_haft crate. This allows the integration of diverse domains without serialization overhead.
Sources: README.md:144-150
Categorical Mapping Table
| Domain | Type | Categorical Role |
|---|---|---|
| Mechanics | CausalTensor<T> | Functor (mapping over field data) |
| Algebra | CausalMultiVector<T> | Monad (chaining geometric operations) |
| Topology | Manifold<T> | Comonad (neighborhood analysis) |
| Causality | PropagatingEffect<T> | Monad (sequencing + audit logs) |
| Sources: README.md:144-150 |
The framework also includes advanced precision through Float106, providing approximately 32 decimal digits of precision while maintaining faster speeds than standard IEEE binary128.
Sources: README.md:103
Project Documentation and Research
The project maintains a rigorous documentation standard through a series of EPP preprints and a technical monograph.
Sources: papers/README.md:12-18
Monograph Volumes
- Metaphysics: The philosophical foundation of process metaphysics.
- Formalization: The mathematical rigor of the EPP.
- Ontology: The categorical structure of causal entities.
- Epistemology: Knowledge representation within the framework.
- Teleology: Goal-oriented behavior and safety layers.
Sources: papers/README.md:20-80, design.md:145-151
Conclusion
DeepCausality provides a comprehensive infrastructure for dynamic causal reasoning by combining functional programming primitives with advanced mathematics and a two-state graph architecture. By centering on the monadic axiom of effect propagation, it enables the construction of complex, verifiable systems that remain deterministic even as their internal causal structures evolve.
Sources: README.md:112-117, lessons-learned-from-rewriting-ultraGraph.md:89-95