SURD Algorithm
Relevant source files
The following files were used as context for generating this wiki page:
- deep_causality_algorithms/README.md
- deep_causality_algorithms/examples/README.md
- openspec/changes/archive/spec-kit-old/003-causal-disovery-dsl/spec.md
- deep_causality_algorithms/CHANGELOG.md
- openspec/changes/archive/2026-05-15-rebuild-website-astro/design.md
- deep_causality_algorithms/src/causal_discovery/surd/surd_algo.rs (Referenced via context)
- deep_causality_algorithms/src/causal_discovery/surd/surd_result.rs (Referenced via context)
The SURD (Synergistic, Unique, and Redundant Decomposition) algorithm is a high-performance computational causality tool implemented within the deep_causality_algorithms crate. It is designed to move beyond simple correlations by decomposing the mutual information between a set of source variables and a target variable into fundamental components: Synergistic, Unique, and Redundant information. This decomposition enables a deep understanding of causal structures in complex, multi-variable dynamic systems.
Sources: deep_causality_algorithms/README.md:14-20, deep_causality_algorithms/examples/README.md:5-10
Within the broader project, SURD serves as a bridge from observational data to executable causal models. It provides the data-driven evidence required to identify multi-causal structures, which can then be modeled using Causaloids and CausaloidGraphs.
Sources: deep_causality_algorithms/README.md:120-125
Core Components and Architecture
The algorithm operates primarily on joint probability distributions represented as multi-dimensional arrays. It supports both standard numerical data and incomplete datasets through specific variants.
Causal Decomposition Types
The algorithm quantifies causal influence through four primary metrics:
| Component | Description |
|---|---|
| Redundant (R) | Overlapping information provided by multiple source variables. |
| Unique (U) | Direct and independent information provided by a single source. |
| Synergistic (S) | Emergent information that only exists when sources are combined. |
| Information Leak | Unexplained target behavior, quantifying unobserved factors or noise. |
Sources: deep_causality_algorithms/README.md:23-28, deep_causality_algorithms/examples/README.md:12-18
Algorithmic Flow
The following diagram illustrates the high-level data flow from raw input to the final decomposition result.
The algorithm processes a CausalTensor and applies a MaxOrder configuration to manage complexity before generating a comprehensive SurdResult.
Sources: deep_causality_algorithms/README.md:38-45, openspec/changes/archive/spec-kit-old/003-causal-disovery-dsl/spec.md:154-159
Implementation Details
Complexity Management
To prevent exponential complexity growth ($O(2^N)$), the algorithm utilizes the MaxOrder enum. This allows developers to cap the analysis to a specific number of interactions (e.g., pairwise), reducing complexity to polynomial levels ($O(N^k)$).
Sources: deep_causality_algorithms/README.md:47-50
Parallelization
When the parallel feature flag is enabled, the main decomposition loop leverages the rayon crate to execute across all available CPU cores. This significantly reduces execution time for high-dimensional datasets.
Sources: deep_causality_algorithms/README.md:51-53, openspec/changes/archive/spec-kit-old/003-causal-disovery-dsl/spec.md:118-121
Handling Incomplete Data (SURD-CDL)
A specialized variant, surd_states_cdl, is designed for real-world datasets with missing values. It operates on CausalTensor<Option<f64>>, ignoring None values during calculations and propagating uncertainty to the results.
Sources: deep_causality_algorithms/README.md:31-36, deep_causality_algorithms/CHANGELOG.md:104-106
Integration with Causal Discovery DSL
The SURD algorithm is a core component of the Causal Discovery Domain Specific Language (DSL). It is integrated via the CQD (Causal Qualities Discovery) workflow, which streamlines the transition from raw files to formatted causal insights.
The sequence shows how SURD interacts with feature selection and result analysis within the automated discovery pipeline.
Sources: openspec/changes/archive/spec-kit-old/003-causal-disovery-dsl/spec.md:20-35, openspec/changes/archive/spec-kit-old/003-causal-disovery-dsl/spec.md:162-175
From Discovery to Modeling
The output of the SURD algorithm is used to parameterize and structure DeepCausality models through specific heuristics:
- Mapping to CausaloidGraph:
- Unique Influence: Translated to a directed edge between two
Causaloids. - Synergistic Influence: Translated to a many-to-one connection in the graph.
- Information Leak: Informs the degree of randomness modeled in a target
Causaloid.
- Unique Influence: Translated to a directed edge between two
- Mapping to Causaloid Logic:
- State-dependent maps provide the conditional logic for the
causal_fn. - Strong Synergy results in
AggregateLogic::All(Conjunction) in aCausaloidCollection. - Unique/Redundant influences result in
AggregateLogic::Any(Disjunction). - Mixed Influences results in
AggregateLogic::Some(k)(Threshold logic).
- State-dependent maps provide the conditional logic for the
Sources: deep_causality_algorithms/README.md:126-146, openspec/changes/archive/spec-kit-old/003-causal-disovery-dsl/spec.md:197-215
Summary
The SURD algorithm provides a mathematically rigorous framework for identifying the nature of causal interactions within data. By decomposing information into synergistic, unique, and redundant components, it allows the deep_causality framework to automatically transition from observational datasets to structured, executable causal models that reflect the true underlying dynamics of a system.
Sources: deep_causality_algorithms/README.md:148-151, openspec/changes/archive/2026-05-15-rebuild-website-astro/design.md:155-165