Overview

DeepCausality is a hypergeometric computational causality library that enables fast, context-aware causal reasoning over complex multi-stage causality models. DeepCausality pioneers uniform reasoning across deterministic and probabilistic modalities across static and dynamic contextual causal models. DeepCausality comprises of three core pillars: The Context is an explicit and dynamic hypergraph that models the operational environment, supporting non-Euclidean and non-linear temporal structures. The Causaloid is a polymorphic, composable unit that can encapsulate a causal function. The Effect Ethos is a deontic guardrail that uses a defeasible calculus to ensure a system's actions remain verifiably aligned with its safety and mission objectives. The DeepCausality project is hosted as a sandbox project in the Linux Foundation for Data & Ai.

The Three Pillars of DeepCausality

DeepCausality comprises of three main components:

1. The Causaloid:

• What it is: A self-contained, single unit of causality.
• What it does: It holds a single causal function that receives an incoming effect, runs its causal function, and emits a new, outgoing effect.

2. The Context:

• What it is: The explicit environment where the Causaloids operate. It holds all the factual data.
• What it does: The Context is a super-flexible data structure (a hypergraph) that holds all the facts about the world: the current time, sensor readings, locations on a map, etc.

3. The Effect Ethos

• What it is: A programmable ethos, to encode and verify operational rules.
• What it does: A Causaloid might reason, "Based on the data, the most logical action is X." But before action X can be taken, the Effect Ethos steps in and checks against a set of rules. It answers the question: "Should this happen?"

DeepCausality is a framework for building systems that can reason about cause and effect in complex, dynamic environments. It achieves this by treating causality as a process of effect propagation between simple, composable * Causaloids* that operate on an explicit, flexible Context, all governed by a verifiable safety layer called the * Effect Ethos*. For an introduction to DeepCausality, see the introduction document and the more detailed deep dive.

The Foundation of DeepCausality

DeepCausality implements the Effect Propagation Process (EPP), which uses a single axiomatic foundation of causality as a functional dependency (E2 = f(E1)). From this single axiom, it derives the context to support Euclidean, non-Euclidean and non-linear, structures, the causaloid for handling static and dynamic causal structures, and the effect ethos. The full text of the EPP monograph is accessible via the the publication repository.

Why DeepCausality?

1. DeepCausality is written in Rust with production-grade safety, reliability, and performance thanks to its UltraGraph backend.

2. DeepCausality provides recursive causal data structures that concisely express arbitrary complex causal structures.

3. DeepCausality enables context awareness across complex data stored in multiple contexts.

4. DeepCausality simplifies modeling of complex tempo-spatial patterns and non-Euclidean geometries.

5. DeepCausality supports adaptive reasoning.

6. DeepCausality comes with Causal State Machine (CSM).

7. DeepCausality supports programmable ethics via the EffectEthos.

📚 Docs

• API Docs

• Documentation

• Changelog

• Slides

• Introduction

• Architecture

• Background

• Concepts

🌎 Community

• Discord
• GH Discussions
• LF Email Lists

🚀 Getting Started

In your project folder, just run in a terminal:

cargo add deep_causality

• Starter Example
• More Examples
• Tests

How to run the example code

git clone https://github.com/deepcausality-rs/deep_causality.git

cd deep_causality

make example

📦 Sub-Crates

• deep_causality: The main DeepCausality library.
• deep_causality_algorithms: Provides algorithms for the DeepCausality library.
• deep_causality_data_structures: Provides data structures for the DeepCausality library.
• deep_causality_discovery: A custom DSL for causal discovery.
• deep_causality_macros: Provides macros for the DeepCausality library (deprecated).
• deep_causality_num: Numerical traits and utils used across the other crates.
• deep_causality_rand: Random number generator and statistical distributions used in deep_causality_tensor and other
• deep_causality_tensor: A custom tensor type used in deep_causality_algorithms and deep_causality_discovery crates.
• deep_causality_uncertain: Provides a custom crate for handling uncertainty.
• examples: A collection of example code.
• ultragraph: A hyper-graph library used as a backend in the deep_causality library.

🛠️ Build & Test

Cargo works as expected, but in addition to cargo, a makefile exists that abstracts over several additional tools you for linting and formatting. To check and install missing tools, please run the following command:

    make install

You find the install script in the script folder.

The script tests and tries to install all required developer dependencies. if the automatic install fails, the script will show a link with further installation instructions.

After all dependencies have been installed, the following commands are ready to use.

    make build          Builds the code base incrementally (fast) for dev.
    make bench          Runs all benchmarks across all crates.
    make check          Checks the code base for security vulnerabilities.
    make example        Runs the example code.
    make fix            Fixes linting issues as reported by clippy
    make format         Formats call code according to cargo fmt style
    make install        Tests and installs all make script dependencies
    make start          Starts the dev day with updating rust, pulling from git remote, and build the project
    make test           Runs all tests across all crates.

The scripts called by each make command are located in the script folder.

In addition to Cargo and related tools, the entire mono-repo is configured to build and test with Bazel. Please install bazelisk as it is the only requirement to build the repo with Bazel. For more details on working with Bazel, see the Bazel document.

👨‍💻👩‍💻 Contribution

Contributions are welcomed especially related to documentation, example code, and fixes. If unsure where to start, open an issue and ask. For more significant code contributions, please run make test and make check locally before opening a PR.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in deep_causality by you, shall be licensed under the MIT license without additional terms or conditions.

For details:

• Charta
• Code of Conduct
• Contributing
• Release
• Support

🙏 Credits

The project took inspiration from several researchers and their projects in the field:

• Judea Pearl at UCLA
• Lucien Hardy at the Perimeter Institute
• Kenneth O. Stanley
• Ilya Shpitser
• Miguel Hernan, Causal Lab at Harvard University
• Elias Bareinboim at Columbia University
• Causality and Machine Learning at Microsoft Research
• Causal ML at uber.

DeepCausality implements the following research publications:

• "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"

Parts of the implementation are also inspired by:

• Differentiable Types
• Extension Trait
• Storage API
• gTime: Time Graph

Finally, inspiration, especially related to the hypergraph structure, was derived from reading the Quanta Magazine.

📜 Licence

This project is licensed under the MIT license.

👮️ Security

For details about security, please read the security policy.

🎁 Sponsors

JetBrains, the premier software development IDE provider, has granted a free all-product license to the DeepCausality project. The project team expresses its gratitude towards JetBrains generous support.