Context & Hypergraphs
Relevant source files
The following files were used as context for generating this wiki page:
Context in the DeepCausality framework represents an explicit, dynamic environment where causal reasoning occurs. Unlike classical frameworks that assume a fixed background spacetime, DeepCausality utilizes a Context primitive—implemented as a hypergraph—to carry the operational environment, including sensor data, non-linear temporal structures, and non-Euclidean spatial locations. This detaches causality from static backgrounds, allowing the environment itself to be queryable and mutable.
The underlying data structure for both the Context and causal graphs is UltraGraph, a specialized hypergraph backend. UltraGraph is designed to solve the engineering trade-off between fast mutation (required during graph construction) and high-performance traversal (required for causal reasoning) through a dual-state architecture.
Sources: README.md:144-149, AGENTS.md:131-135, website/web/src/content/blog/en/lessons-learned-from-rewriting-ultraGraph.md:12-18
UltraGraph: The Hypergraph Backend
UltraGraph serves as the backend for CausaloidGraph and Context. Its architecture is defined by a "Two-State" design that optimizes for different stages of the causal reasoning lifecycle.
Two-State Architecture
To provide both flexibility and raw speed, UltraGraph transitions between two internal representations:
| State | Name | Internal Structure | Optimization Target |
|---|---|---|---|
| Evolve | DynamicGraph | Adjacency List (Vec<Vec<...>>) | O(1) additions of nodes/edges; high mutability. |
| Analyze | CsmGraph | Compressed Sparse Row (CSR) | Cache-friendly, immutable traversals; zero locking. |
Sources: website/web/src/content/blog/en/lessons-learned-from-rewriting-ultraGraph.md:34-45, README.md:213-215
State Transitions
The transition between these states is managed by .freeze() and .unfreeze() methods. Freezing the graph creates an immutable, "frozen" representation optimized for analytics, while unfreezing returns it to a mutable state for further modification.
This "stop-the-world" approach ensures that during complex causal analysis, the graph structure remains consistent and performant without the overhead of locks.
Sources: website/web/src/content/blog/en/lessons-learned-from-rewriting-ultraGraph.md:47-51
Contextual Data Flow
The Context acts as the "where" of causality. It provides the necessary environment for Causaloids to operate. In a multi-stage causal model, the Context is responsible for providing data to the reasoning engine and maintaining state across evaluations.
Component Interaction
The relationship between Context, Causaloids, and the reasoning engine is illustrated below:
The Context is detached from a fixed spacetime, making it queryable and dynamic. It allows for the representation of complex dependencies that might change as the system state evolves.
Sources: README.md:144-149, AGENTS.md:131-135
Performance by Design
The implementation of the hypergraph structures within DeepCausality prioritizes "mechanical sympathy" to ensure high-performance execution in Rust.
- Struct of Arrays (SoA): The CSR format in
CsmGraphuses parallel vectors (e.g.,Vec<target>andVec<weight>) instead of an Array of Structs. This reduces memory bandwidth requirements when algorithms only need to traverse topology. - Adaptive Algorithms: Methods like
contains_edgeadapt at runtime based on node degree—using linear scans for low-degree nodes and binary searches for "super-nodes." - Zero-Cost Abstractions: Traversal methods return
impl Iteratorrather than heap-allocated vectors, providing a read-only window into CSR memory without unnecessary allocations.
Sources: website/web/src/content/blog/en/lessons-learned-from-rewriting-ultraGraph.md:58-71
Key Primitives and Types
| Primitive | Description | File Path |
|---|---|---|
| Context | An explicit hypergraph environment for causal reasoning. | README.md |
| UltraGraph | The backend hypergraph supporting two-state execution. | ultragraph/README.md |
| DynamicGraph | The mutable state of UltraGraph using adjacency lists. | website/web/src/content/blog/en/lessons-learned-from-rewriting-ultraGraph.md |
| CsmGraph | The immutable state of UltraGraph using CSR format. | website/web/src/content/blog/en/lessons-learned-from-rewriting-ultraGraph.md |
Sources: README.md:144-149, website/web/src/content/blog/en/lessons-learned-from-rewriting-ultraGraph.md:34-45
Context and Hypergraphs provide the structural foundation for DeepCausality's dynamic reasoning. By detaching environmental data from static backgrounds and utilizing a high-performance, two-state hypergraph (UltraGraph), the framework enables context-aware causal inference that is both flexible during model construction and blazing fast during execution.