DeepCausality

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. Take a look at how is deep causality different from deep learning?

🤔 Why DeepCausality?

1. DeepCausality is written in Rust with production grade safety, reliability, and performance in mind.
2. DeepCausality provides recursive causal data-structures that enable concise expression of 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 simplified modelling of complex tempo-spatial patterns.
5. DeepCausality comes with Causal State Machine (CSM)
6. DeepCausality is small, efficient, and fast, really fast. Run benchmarks and see it.
7. DeepCausality comes with plenty of tests

📚 Docs

• API Docs
• Motivation
• How is deep causality different?
• Causal Structure
• Causal State Machine (CSM)
• Concepts
• Context
• Heilmeier Questions
• Limitations

🚀 Install

Just run:

cargo add deep_causality

Alternatively, add the following to your Cargo.toml

deep_causality = { git = "https://github.com/deepcausality/deep_causality.git", tag = "0.2.4" }

⭐ Usage

See:

• Benchmarks
• Examples
• Tests

Causal State Machine

A causal state machine is used to model a context-free system where each cause maps to a known effect. For example, a sensor network screens an industry site for smoke, fire, and explosions. Because the sensors are reliable, whenever the sensor exceeds a certain threshold, an alert will be raises. This kind of system could be implemented in many different ways, but as the example shows, the causal state machine makes the system relatively easy to maintain and extent. New sensors, for example from a drone inspection, can be added and evaluated dynamically.

Full example code

const SMOKE_SENSOR: usize = 1;
const FIRE_SENSOR: usize = 2;
const EXPLOSION_SENSOR: usize = 3;

pub fn run() {
    let data = [0.0f64];
    let smoke_causloid = get_smoke_sensor_causaloid();
    let smoke_cs = CausalState::new(SMOKE_SENSOR, 1, &data, &smoke_causloid);
    let smoke_ca = get_smoke_alert_action();

    let fire_causaloid = get_fire_sensor_causaloid();
    let fire_cs = CausalState::new(FIRE_SENSOR, 1, &data, &fire_causaloid);
    let fire_ca = get_fire_alert_action();

    let explosion_causaloid = get_explosion_sensor_causaloid();
    let explosion_cs = CausalState::new(EXPLOSION_SENSOR, 1, &data, &explosion_causaloid);
    let explosion_ca = get_explosion_alert_action();

    let state_actions = &[
        (&smoke_cs, &smoke_ca),
        (&fire_cs, &fire_ca),
    ];

    println!("Create Causal State Machine");
    let csm = CSM::new(state_actions);

    let smoke_data = get_smoke_sensor_data();
    let fire_data = get_fire_sensor_data();
    let exp_data = get_explosion_sensor_data();

    println!("Add a new sensor");
    csm.add_single_state(EXPLOSION_SENSOR, (&explosion_cs, &explosion_ca)).expect("Failed to add Explosion sensor");

    println!("Start data feed and monitor senors");
    for i in 0..12 {
        wait();
        csm.eval_single_state(SMOKE_SENSOR, &[smoke_data[i]]).expect("Panic: Smoke sensor failed");

        csm.eval_single_state(FIRE_SENSOR, &[fire_data[i]]).expect("Panic: Fire sensor failed");

        csm.eval_single_state(EXPLOSION_SENSOR, &[exp_data[i]]).expect("Panic: Explosion sensor failed");
    }
}

🛠️ Cargo & Make

Cargo works as expected, but in addition to cargo, a makefile exists that abstracts over a number of additional tools you may have to install before all make commands work:

• clippy
• nextest
• outdated
• udeps
• audit

    make build          Builds the code base incrementally (fast).
    make bench          Runs all benchmarks across all crates.
    make check          Checks the code base for security vulnerabilities.
    make example        Runs the default example: Smoking.
    make fix            Auto-fixes linting issues as reported by cargo and clippy.
    make test           Runs all tests across all crates.

🙏 Credits

The project took inspiration by work from several researchers and their teams:

• 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

Parts of the implementation are inspired by:

• Differentiable Types
• Extension Trait
• Storage API

👨‍💻👩‍💻 Contribution

Contributions are welcomed especially related to documentation, example code, and fixes. If unsure where to start, just open an issue and ask. For larger code contributions, please run make check locally before opening a PR and please add tests to make the PR merge relatively straight forward.

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

📜 Licence

This project is licensed under the MIT license.

👮️ Security

For details about security, please read the security policy.

💻 Author

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