Differential Topology & Lattices
Relevant source files
The following files were used as context for generating this wiki page:
Differential Topology & Lattices within the DeepCausality framework provide the rigorous mathematical foundation for modeling causal dependencies over complex geometric and topological structures. This module bridges discrete data, such as point clouds and graphs, with continuous geometric structures like manifolds and simplicial complexes. By treating causality as a spacetime-agnostic functional dependency, the system enables advanced reasoning about the "shape" and connectivity of causal systems in a way that is general-relativistic-native and quantum-native.
The module implements a unified ChainComplex abstraction that allows various topological structures—Simplicial Complexes, Lattice Complexes (Cubical Complexes), and Cell Complexes—to share a common interface for algebraic topology computations. This infrastructure supports discrete differential geometry operators, such as the Hodge-Laplacian and exterior derivative, which are essential for simulating physical processes and detecting topological invariants like Betti numbers and Euler characteristics.
Sources: deep_causality_topology/README.md, README.md:27-35
Unified Chain-Complex Architecture
The architecture relies on the ChainComplex trait, which unifies diverse topological types under a single static-dispatch interface. This trait replaces the former CWComplex naming to align with algebraic-topology standards. It provides essential methods for cell iteration, boundary/coboundary matrix generation, and Betti number computation.
The diagram shows the relationship between the central ChainComplex interface and the concrete implementations that drive the topological reasoning engine.
Sources: deep_causality_topology/README.md, openspec/changes/archive/2026-05-19-add-cubical-complexes/tasks.md:46-75
Core Topological Types
| Type | Description | Mathematical Structure |
|---|---|---|
| SimplicialComplex | Collection of simplices closed under sub-simplices. | Simplicial Complex $K$ |
| LatticeComplex | Cubical complex of a regular $\mathbb{Z}^D$ grid, supporting periodic boundaries. | Lattice-supported cubical complex |
| Manifold | A complex $K$ paired with a field $F$ and optional metric. | Discrete manifold over $K$ |
| CellComplex | Generalized complex over arbitrary user-defined cells. | CW-Complex |
| PointCloud | Set of points in $\mathbb{R}^n$ used for Vietoris-Rips triangulation. | Discrete Metric Space |
Sources: deep_causality_topology/README.md
Discrete Differential Geometry
The framework implements discrete differential operators that allow for calculus on manifolds and complexes. These operators are critical for solving physical equations (e.g., the Heat Equation) and performing Hodge Theory to detect holes and voids in data.
Differential Operators and Forms
The system supports discrete differential k-forms ($\Omega^k(M)$) and several key operators:
- Exterior Derivative ($d$): Maps k-forms to (k+1)-forms.
- Codifferential ($\delta$): The adjoint of the exterior derivative.
- Hodge Star ($\star$): Maps k-forms to (n-k)-forms, capturing duality.
- Hodge-Laplacian ($\Delta$): Defined as $\Delta = d\delta + \delta d$. Harmonic forms are solutions to $\Delta\omega = 0$.
Sources: deep_causality_topology/README.md, openspec/changes/archive/physics_gauge_field_review.md:120-145
Neighborhood Strategies
To facilitate computations like convolutions and cellular automata, the module uses zero-sized strategy types for neighbor enumeration:
- Generic Strategies:
FaceAdjacentandCofaceAdjacentwork on anyChainComplex. - Grid-Specific:
VonNeumann,Moore, andKRingare specialized forLatticeComplex.
Sources: deep_causality_topology/README.md, openspec/changes/archive/2026-05-19-add-cubical-complexes/tasks.md:144-153
Lattice Gauge Theory
The LatticeGaugeField implementation provides a Wilson-formulation for gauge theory, verified against 24 reference results from established physics literature. This is used for prototyping lattice QCD and other quantum field theories.
This flowchart illustrates the flow from the underlying lattice structure to the computation of physical observables and Monte Carlo dynamics.
Sources: deep_causality_topology/README.md, openspec/changes/archive/topology_gauge_field_lattice_review_two.md:16-55
Supported Gauge Groups
The implementation includes several standard Lie groups used in physics:
- U(1): Electromagnetism.
- SU(2): Weak interaction.
- SU(3): Strong interaction (QCD).
- Lorentz: General Relativity.
- StandardModel: Combined gauge groups for the full Standard Model.
Sources: openspec/changes/archive/physics_gauge_field_review.md:46-68
Higher-Kinded Types (HKT) Integration
DeepCausality leverages the deep_causality_haft crate to provide functional geometric abstractions. This allows a single bind chain to step through different mathematical domains (Tensors → MultiVectors → Manifolds) without serialization overhead.
Categorical Mappings
| Domain | Type | Categorical Role |
|---|---|---|
| Mechanics | CausalTensor<T> | Functor (map over data) |
| Algebra | CausalMultiVector<T> | Monad (chain operations) |
| Topology | Manifold<T> | Comonad (neighborhood analysis) |
| Causality | PropagatingEffect<T> | Monad (sequencing + logs) |
Sources: README.md:140-155, deep_causality_topology/README.md
Functional Patterns
- Comonad (Extract/Extend): Used for "neighborhood extraction" and local computations like GNNs or cellular automata.
- Adjunction (Unit/Counit): Used for "geometric realization" (e.g., embedding discrete data into a topological structure).
- Functor: Allows mapping functions over data stored within a topology or manifold.
Sources: deep_causality_topology/README.md, openspec/changes/archive/2026-05-19-add-cubical-complexes/tasks.md:156-160
Regge Geometry and Curvature
The module implements Regge Calculus to provide discrete metrics and curvature calculations.
- ReggeGeometry: Simplicial metric involving edge lengths and deficit angles on codimension-2 hinges.
- CubicalReggeGeometry: The cubical analogue for
LatticeComplex, supporting edge-length storage and Lorentzian signatures. - CurvatureTensor: Provides methods for computing Riemann, Ricci, and Weyl curvature tensors, including the Ricci scalar and Einstein tensor.
Sources: deep_causality_topology/README.md, openspec/changes/archive/physics_gauge_field_review.md:78-116
Summary
The Differential Topology & Lattices module serves as the geometric engine of DeepCausality. By unifying discrete topological structures under the ChainComplex trait and providing high-performance implementations of discrete differential operators and gauge fields, it enables causal reasoning that is intrinsically aware of the underlying geometric constraints of a system. This integration of algebraic topology with functional programming patterns ensures that the framework remains both mathematically rigorous and computationally efficient.