deepcausality-rs / deep_causality

Hyper-geometric computational causality library for Rust

Web: https://deepcausality.com

DeepCausality is a hyper-geometric computational causality library that enables fast and deterministic context-aware causal reasoning over complex multi-stage causality models. Deep Causality adds only minimal overhead and thus is suitable for real-time applications without additional acceleration hardware.

DeepCausality is hosted as a sandbox project in the LF AI & Data Foundation.

🤔 Why DeepCausality?

1. DeepCausality is written in Rust with safety, reliability, and performance in mind.
2. DeepCausality provides recursive causal data structures that concisely express arbitrary complex causal structures.
3. DeepCausality enables context awareness across data-like, time-like, space-like, spacetime-like entities stored within (multiple) context-hyper-graphs.
4. DeepCausality simplifies modeling of complex tempo-spatial patterns.
5. DeepCausality comes with Causal State Machine (CSM)

📚 Docs

• API Docs
• Documentation
• Changelog
• Slides

🚀 Getting Started

In your project folder, just run in a terminal:

cargo add deep_causality

See the starter example.

How to run the example code

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

cd deep_causality

make example

You can also run the example code from the project root with cargo:

# make sure you're in the project root folder
cd deep_causality

# CSM (Causal State Machine)
cargo run --release --bin example-csm

# CTX (Context) 
cargo run --release --bin example-ctx

# Smoking inference
cargo run --release --bin example-smoking

# Getting started example
cargo run --release --bin starter

📦 Sub-Crates

• Datastructures
• Ultragraph
• Macros

⭐ Usage

Docs:

• Introduction
• Architecture
• Background
• Concepts

Code:

• Benchmarks
• Example code
• Tests

🛠️ Cargo & Make

Cargo works as expected, but in addition to cargo, a makefile exists that abstracts over several additional tools you may have to install before all make commands work. To do so, please run the following command:

    make install

The make install command 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.

👩‍👩‍👧‍👦 Community

• Charta
• Code of Conduct
• Support

👨‍💻👩‍💻 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:

• Code of Conduct
• Contributing
• Release

🙏 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 at OpenAI
• Ilya Shpitser at Johns Hopkins University
• Miguel Hernan, Causal Lab at Harvard University
• Elias Bareinboim at Columbia University
• Causality and Machine Learning at Microsoft Research
• Causal ML at uber.

Parts of the implementation are 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 tool provider, has granted a free all-product license under its open-source community support program to the DeepCausality project. The project team expresses its gratitude towards JetBrains generous contribution. Thank you for your commitment to OSS development!

💻 Author

• Marvin Hansen.
• Github GPG key ID: 369D5A0B210D39BC
• GPG Fingerprint: 4B18 F7B2 04B9 7A72 967E 663E 369D 5A0B 210D 39BC

deep_causality's Issues

Add depedency install to cargo tools used in scripts for make

**Is your feature request related to a problem? **

Right now, multiple cargo sub commands must be installed manually to make the various scripts used in the makefile work.

Describe the solution you'd like

make install

Describe alternatives you've considered

keep install manually or add make install script that tries to install as much automatically as possible.

Additional context

Add any other context or screenshots about the feature request here.

Move graph datastructure into separate crate

Is your feature request related to a problem? Please describe.

Right now, causal graph and context graph both re-invent the wheel by implementing the same data structure thus making the code harder to maintain.

Describe the solution you'd like

• Move graph datastructure into separate crate
• Replace custom implementation in causal graph and context graph with the new crate
• Remove unnecessary dependencies from main crate.

Describe alternatives you've considered

I have evaluated and benchmarked petgraph and Hypergraph and while petgraph has the performance requirements, it lacks some custom functionality needed in the deep causality crate. Therefore, its best to build a custom wrapper around petgraph, and move the entire graph data structure into a separate crate for better maintainability.

Additional context
N/A

Make Spatial and Temporable trait generic

**Is your feature request related to a problem? **

Right now, adjustable types only work for data and time, but not for space and SpaceTime.

For space, the adjustable protocol cannot be implemented together with spatial, which makes impossible
to use in a context.

For time, implementing temporable and adjustable would require a primitive and a generic field of time unit.

Clearly, none of this is necessary.

Make Spatial and Temporable trait generic over type T with some requirements for math operations, for example

pub trait Temporable: Identifiable where T: Default + Add<T, Output=T> + Mul<T, Output=T> // ...

Describe alternatives you've considered

Keeping the traits as it is means no generic adjustable context.

Patching around with primitive and generic versions of the same field.

Additional context

Adjustable context may become a critical feature later on, especially combined with multi-context
so this needs to be fixed.

Increase Test Coverage

Currently, the core library is reasonable tested but some gaps exists.

The easiest way to get started:

1. Check the code coverage report:
   https://app.codecov.io/gh/deepcausality-rs/deep_causality

2. See where some gaps are

3. Look at the existing tests. Most are easy to copy & modify.
   https://github.com/deepcausality-rs/deep_causality/tree/main/deep_causality/tests

4. Add some new tests. Make sure you run make test & make check before before opening a PR.
   See details for make in the BUILD document.

5. Make a PR and wait for review

Refactor complex types into multiple smaller files

Is your feature request related to a problem? Please describe.

A number of complex types (Causaloid, etc) have grown very large and are hard to maintain.

Describe the solution you'd like

In Rust, multiple impl blocks can span across multiple files. Therefore, split those large and complex types into multiple
impl blocks that are more focused (i.e. implement just one trait instead of five) and put each block into one file.

Describe alternatives you've considered
/

Additional context
/

Remove lifelines in the public API.

**Is your feature request related to a problem? **

Currently, lifelines in the public API cause problems with Async & Tokio.

Describe the solution you'd like

Remove lifelines in the public API.
Replace references with smart pointers i.e. ARC.

Describe alternatives you've considered

N/A

Additional context

https://users.rust-lang.org/t/tokio-stream-borrow-checker-argument-requires-that-context-is-borrowed-for-static/105957/5

Add support for multiple contexts.

**Is your feature request related to a problem? **

Currently, only one context can be used in causal model

Describe the solution you'd like

Add support for multiple contexts. Specifically, 1 ...n contexts that are user selectable via the API.

Describe alternatives you've considered

Keep just one context.

Additional context

The feature is elaborated in the documentation, but not yet available,

https://deepcausality.com/docs/

Automate release process

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Right now, a new release has way to many manual steps:

1. Add tag
2. Add Gh release
3. write / generate release notes
4. Bump up version in Cargo.toml
5. Release to crate.io from bash

Describe the solution you'd like
A clear and concise description of what you want to happen.

Adopt one of those release automation bots:

https://github.com/MarcoIeni/release-plz

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Either you automate the mundane tasks or you work like a monkey.

Additional context
Add any other context or screenshots about the feature request here.

/

Add fuzzing to CI

Is your feature request related to a problem?

https://about.gitlab.com/blog/2020/12/03/how-to-fuzz-rust-code/

https://github.com/rust-fuzz/cargo-fuzz

Describe the solution you'd like

A clear and concise description of what you want to happen.

Describe alternatives you've considered

A clear and concise description of any alternative solutions or features you've considered.

Additional context

Add any other context or screenshots about the feature request here.

Post project Charta