Causal Tensors
Relevant source files
The following files were used as context for generating this wiki page:
- README.md
- AGENTS.md
- deep_causality_discovery/README.md
- openspec/changes/archive/spec-kit-old/001-mrmr-feature-selector/spec.md
- openspec/changes/archive/spec-kit-old/003-causal-disovery-dsl/spec.md
- openspec/changes/archive/spec-kit-old/005-right-now-there/spec.md
- deep_causality_algorithms/CHANGELOG.md
Causal Tensors (CausalTensor<T>) serve as the primary multi-dimensional numerical data structure within the DeepCausality ecosystem. They are designed to hold observational data—typically represented as samples (rows) and features (columns)—and act as the fundamental input for causal discovery algorithms, feature selection processes, and mathematical transformations across physics and topology modules.
Within the overall architecture, Causal Tensors provide a uniform interface that allows data to flow seamlessly from ingestion (e.g., CSV or Parquet files) through Causal Discovery Language (CDL) pipelines, ultimately informing the creation of Causaloids and Context structures.
Sources: README.md:129-135, AGENTS.md:104-106, deep_causality_discovery/README.md:21-25
Architecture and Core Functionality
Causal Tensors are implemented as N-dimensional arrays that support broadcasting, Einstein summation, and categorical interfaces such as Functors, Applicatives, and Monads. This design allows them to bridge different scientific silos, enabling a single pipeline to step from raw field data to complex causal logic without serialization overhead.
Technical Characteristics
| Feature | Description |
|---|---|
| Dimensionality | Supports N-dimensional structures for complex numerical data. |
| Categorical Role | Acts as a Functor, allowing mapping over field data. |
| Numerical Precision | Supports standard types and high-precision Float106. |
| Missing Data | Supports Option<f64> variants to handle NaN values without introducing bias. |
Sources: README.md:130, README.md:188-195, openspec/changes/archive/spec-kit-old/005-right-now-there/spec.md:65-70
Data Flow Transformation
The following diagram illustrates how Causal Tensors act as the central data carrier in a discovery pipeline, transforming from raw input to analyzed causal insights.
Causal Tensors facilitate the transition from observational data to structural models by providing the numerical basis for algorithms like SURD and mRMR.
Sources: deep_causality_discovery/README.md:21-43, openspec/changes/archive/spec-kit-old/003-causal-disovery-dsl/spec.md:143-160
Causal Discovery Integration
Causal Tensors are central to the Causal Discovery Language (CDL). The CDL uses a typestate-builder pattern to ensure that tensors are processed in a valid sequence.
Feature Selection (mRMR)
The Maximum Relevance and Minimum Redundancy (mRMR) algorithm accepts a CausalTensor containing samples and features. It calculates F-statistics for relevance and Pearson correlation for redundancy to output a ranked list of feature identifiers.
Missing Data Handling
To prevent bias from NaN substitution (imputation), the system provides an OptionNoneDataCleaner which transforms a CausalTensor<f64> into a CausalTensor<Option<f64>>.
- Pairwise Deletion: Statistical calculations like mRMR operate on
Somevalues and ignoreNonevalues. - Sample Validation: If a pair of columns has insufficient
Somesamples after deletion, the system returns aSampleTooSmallerror.
Sources: openspec/changes/archive/spec-kit-old/001-mrmr-feature-selector/spec.md:55-65, openspec/changes/archive/spec-kit-old/005-right-now-there/spec.md:17-25, openspec/changes/archive/spec-kit-old/005-right-now-there/spec.md:76-81
Mathematical and Physics Context
Beyond data discovery, Causal Tensors are part of a "Uniform Mathematics" stack. They share a categorical interface with MultiVectors and Manifolds via higher-kinded types (HKT).
This architecture allows a single bind chain to curvature data from a Tensor (General Relativity) into a MultiVector (Lorentz force) and eventually into a PropagatingEffect for causal logic.
Sources: README.md:131-135, README.md:188-195, AGENTS.md:120-125
Key Entities and Types
| Entity | Role in Causal Tensor System |
|---|---|
CausalTensor<T> | The primary data structure for N-dimensional numerical data. |
MrmrResult | A dedicated type for results generated by the mRMR algorithm from a tensor. |
OptionNoneDataCleaner | Component that converts f64 values to Some(f64) and NaN to None. |
TensorProduct | Implementation moved directly into the CausalTensor type for performance. |
Sources: deep_causality_algorithms/CHANGELOG.md:46, deep_causality_algorithms/CHANGELOG.md:83, openspec/changes/archive/spec-kit-old/005-right-now-there/spec.md:83-85
Summary
Causal Tensors are the numerical backbone of the DeepCausality framework. They provide the necessary abstraction to handle raw data, manage missing values through optional types, and participate in high-level categorical compositions across physics and topology. By unifying these domains under a single tensor interface, the project enables fast, deterministic, and context-aware causal reasoning over complex multi-stage models.
Sources: README.md:130-135, deep_causality_discovery/README.md:7-12