DeepCausality Topology

Topological Data Analysis (TDA) and Causal Geometry for Rust

deep_causality_topology is a core crate of the deep_causality project, providing rigorous topological data structures and algorithms for causal modeling, geometric deep learning, and complex systems analysis.

It bridges the gap between discrete data (graphs, point clouds) and continuous geometric structures (manifolds, simplicial complexes), enabling advanced reasoning about the "shape" and connectivity of causal systems.

Features

• Comprehensive Topological Types:
  • Graph: Efficient sparse-matrix based graphs for causal networks.
  • Hypergraph: Modeling higher-order relationships (hyperedges) between multiple nodes.
  • SimplicialComplex: Generalizing graphs to higher dimensions (triangles, tetrahedra) to capture voids and holes.
  • LatticeComplex (alias CubicalComplex): The cubical complex of a regular ℤᴰ grid, with optional periodic boundaries — the natural substrate for voxel grids, sensor arrays, and lattice gauge theory.
  • CellComplex: General CW-complex over arbitrary user-defined cells.
  • Manifold: Validated geometric structures, generic over any chain complex (Manifold<K: ChainComplex, F>).
  • PointCloud: Raw multi-dimensional data with Vietoris-Rips triangulation capabilities.
• Unified Chain-Complex Abstraction:
  • ChainComplex trait: A single static-dispatch trait (GAT-backed cell iteration, Cow-returning boundary/coboundary matrices) that SimplicialComplex, LatticeComplex, and CellComplex all implement. Downstream code (notably Manifold's differential operators) reads ∂ and δ through the trait — zero-copy on the cache-rich simplicial path, lazy-memoized on the cubical path.
• Topological Algorithms:
  • Vietoris-Rips Triangulation: Convert point clouds into simplicial complexes at a given scale.
  • Euler Characteristic: Compute topological invariants ($\chi$) to classify shapes (e.g., healthy vs. pathological tissue).
  • Boundary/Coboundary Operators: Sparse matrix operators for algebraic topology computations.
  • Betti Numbers: Counting independent k-dimensional holes via the rank of ∂.
• Algebraic Topology & Differential Geometry:
  • Chain Algebra: Perform algebraic operations on chains (formal sums of simplices) and verify fundamental topological theorems like ∂∂=0.
  • Differential Operators: Compute the exterior derivative (d), Hodge star (⋆), codifferential (δ), and Hodge-Laplacian (Δ) on discrete differential forms, on both the simplicial and cubical paths (the cubical star covers unit/uniform/per-axis/per-edge metric tiers, with the diagonal memoized per grade).
  • Hodge Theory: Detect topological features like holes and voids by finding harmonic forms (solutions to Δω = 0).
  • Poisson Solves & Projections: Manifold::leray_project (the divergence-free projection of a 1-form) and hodge_decompose route their grade-0 Poisson solves through a dispatch over three domain classes — fully periodic uniform boxes solve directly via rFFT (torus eigenbasis), wall-bounded/mixed uniform boxes solve directly via DCT-I/DFT (the boundary-corrected Δ₀ diagonalizes exactly in the cosine basis), and everything else (per-edge metrics, degenerate extents) falls back to Jacobi-preconditioned CG on the mass-weighted normal form. The direct paths are exact to rounding with no iteration budget.
  • Constrained Leray Projection: Manifold::leray_project_constrained_opts projects onto the intersection of the divergence-free subspace with an essential edge constraint set (u|_E = 0) — the M-orthogonal intersection projection that wall-bounded no-slip flows require (the plain projector and the coordinate constraint do not commute). Runs the masked-mass Poisson solve through Jacobi-PCG.
  • Boundary-Corrected Hodge Star: on open (wall) lattice axes, dual volumes clip by 2^{-b} per boundary incidence (wall faces halve, edges quarter, 3D corners eighth); fully periodic lattices are bit-unchanged. The corrected star keeps M_k·Δ_k symmetric positive (semi)definite — the property the CG solves and the energy arguments rely on.
  • Compiled DEC Stencils: DecStencilTables compiles per-manifold flat gather tables for d, δ, and the convective chain (interior-product transport + cup-product wedge), folding incidence signs, Hodge diagonals, transport weights, and cup signs into the stored coefficients — the streaming evaluation strategy behind the DEC Navier–Stokes solver's hot loop, equivalence-gated against the generic operators in CI.
• Neighborhood Strategies (static-dispatch zero-sized strategy types):
  • Chain-complex-generic: FaceAdjacent, CofaceAdjacent — defined via ∂ and δ, work on any ChainComplex.
  • Grid-only: VonNeumann, Moore, KRing<const K: usize> — implemented for LatticeComplex<D> only. Useful for cellular-automata, sensor fusion, image filters, voxel-based diffusion.
  • Users add their own strategies (anisotropic LIDAR cones, half-space RF, etc.) by implementing Neighborhood<K> for a custom zero-sized type.
• Higher-Kinded Types (HKT):
  • Implements Functor, BoundedComonad (Extract/Extend), and BoundedAdjunction (Unit/Counit) via deep_causality_haft.
  • Enables functional geometric patterns like "neighborhood extraction" (Comonad) and "geometric realization" ( Adjunction).
  • Witnesses ship for each topology: SimplicialManifoldWitness<C> (full HKT stack), GenericManifoldWitness<K> (Functor over any chain complex), and LatticeComplexWitness<D> for the lattice-complex HKT plumbing.

Core Concepts

Traits

Mathematical Naming Convention

This crate uses dual names only where the same mathematical object lives at the intersection of two equally-canonical traditions — never as a back-compat shim or cosmetic preservation. The principle, applied object by object:

LatticeComplex<D> ↔ CubicalComplex<D>

The struct stores shape: [usize; D] + periodic: [bool; D] — a regular $\mathbb{Z}^D$ grid, with elementary cubes computed on demand. Two mathematical traditions describe this same object, each emphasizing a different structural layer:

• Physics / number theory: "lattice." Meaning #3 in standard math vocabulary — a regular integer grid such as $\mathbb{Z}^D$ or a bounded box thereof. The substrate-emphasizing name. Used by LatticeGaugeField, lattice QCD, the Ising model, crystallography.
• Algebraic topology: "cubical complex." Kaczynski–Mischaikow–Mrozek (Computational Homology, 2004, Def. 2.36) and Edelsbrunner–Harer (Computational Topology). The cellular-decomposition-emphasizing name — the cubes are products of degenerate and non-degenerate intervals (which is exactly what the orientation bitmask on LatticeCell<D> encodes).

Both names are equally canonical for what they emphasize. LatticeComplex<D> is the declared type; CubicalComplex<D> is a pub type alias on it. Use whichever name fits the surrounding text — neither is a "primary" choice over the other.

The same dual-name principle applies to the elementary cell: LatticeCell<D> ↔ CubicalCell<D>. No other aliases exist in the lattice family — types like DualLatticeComplex<D>, LatticeComplexWitness<D>, or the per-axis iterators have only their canonical name because there is no genuinely distinct cubic-specialization reading for them.

Scope note. LatticeComplex<D> represents specifically the cubical complex of a regular $\mathbb{Z}^D$ grid. It is not a sparse cubical complex (only-active-cubes) or an irregular one (cubes of varying side lengths) — those are deferred follow-ups.

ReggeGeometry<T> ↔ CubicalReggeGeometry<D>

These are parallel by role, not by alias: each is the discrete-geometry / metric data on its respective complex, and each is named after the same construction (Regge calculus) transported to a different cellular world:

• ReggeGeometry<T> — Tullio Regge's original 1961 construction for simplicial complexes: edge lengths plus deficit angles on codimension-2 hinges, yielding a discrete general relativity.
• CubicalReggeGeometry<D> — the same construction on a cubical complex. Sometimes called "cubical Regge calculus" or "hypercubic Regge calculus" in the lattice quantum gravity literature. Stage C ships the edge-length storage layer (unit / isotropic / per-axis / per-edge) and the Lorentzian-signature computation; cell volumes, deficit angles, Hodge ⋆, and per-cell metric tensors are forward-looking and tracked as a follow-up.

The naming is parallel because the math is parallel.

Manifold<K: ChainComplex, F> ↔ SimplicialManifold<C, F>

The struct is generic over the underlying chain complex K and the field data type F:

• Manifold<K, F> — the general form. K can be any ChainComplex (currently SimplicialComplex<C>, LatticeComplex<D>, CellComplex<C>, or user-defined). The optional metric is typed via K::Metric (the associated type on ChainComplex), so a simplicial manifold carries Option<ReggeGeometry<C>> and a lattice manifold carries Option<CubicalReggeGeometry<D>> — with no dyn, no enum, no runtime dispatch.
• SimplicialManifold<C, F> = Manifold<SimplicialComplex<C>, F> — alias for the textbook simplicial case. Existing simplicial code uses this name unchanged.

ChainComplex (was CWComplex)

The trait was renamed to align with algebraic-topology textbook usage. Chain complex is the standard term for a sequence of abelian groups (here, free $\mathbb{Z}$-modules generated by k-cells) connected by boundary operators with $\partial \circ \partial = 0$. The previous name CWComplex referred more narrowly to the underlying CW (Closure-finite, Weak topology) cellular structure. Functionally identical; just the textbook-correct name.

Lattice Gauge Field Verification ✓

The LatticeGaugeField implementation is verified against known results from lattice gauge theory (M. Creutz, Quarks, Gluons and Lattices, Cambridge 1983).

24 Physics Verification Tests:

Run verification tests:

cargo test -p deep_causality_topology verification_tests --release

Usage

Add this crate to your Cargo.toml:

deep_causality_topology = { version = "0.1" }

1. Basic Graph Construction

Efficiently model causal dependencies using sparse adjacency matrices.

use deep_causality_sparse::CsrMatrix;
use deep_causality_tensor::CausalTensor;
use deep_causality_topology::{Graph, GraphTopology};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Adjacency: 0->1, 1->2
    let adj = CsrMatrix::from_triplets(3, 3, &[(0, 1, 1), (1, 2, 1)])?;
    let data = CausalTensor::new(vec![1.0, 2.0, 3.0], vec![3])?;

    let graph = Graph::new(adj, data, 0)?;

    println!("Neighbors of 1: {:?}", graph.get_neighbors(1)?);
    Ok(())
}

2. Manifold Analysis (Euler Characteristic)

Validate geometric shapes and compute topological invariants.

use deep_causality_topology::{Manifold, SimplicialComplex, Simplex, Skeleton};
// ... (Setup complex) ...

// Compute Euler Characteristic: Chi = V - E + F ...
let chi = manifold.euler_characteristic();
// Chi = 1 (Contractible/Solid)
// Chi = 0 (Hole/Circle)
// Chi = 2 (Sphere)

3. Point Cloud Triangulation (i.e. MRI Image Analysis)

Convert raw sensor data into structured geometry to detect anomalies (e.g., tumors/voids).

use deep_causality_topology::PointCloud;

// 1. Ingest Raw MRI Data
let pc = PointCloud::new(points_tensor, metadata, 0) ?;

// 2. Triangulate (Vietoris-Rips)
let complex = pc.triangulate(0.6) ?;

// 3. Diagnose based on Topology
let chi = complex.euler_characteristic();
if chi <= 0 {
println ! ("Pathological: Detected Void/Necrosis");
}

4. Differential Geometry (Heat Equation)

Simulate physical processes like diffusion on complex geometries using the Hodge-Laplacian.

use deep_causality_topology::{Manifold, PointCloud};
// ... (Setup manifold from a PointCloud) ...

// Set initial heat distribution (a 0-form)
// ...

// Time-step the heat equation: ∂u/∂t = -Δu
for _ in 0..num_steps {
let laplacian = manifold.laplacian(0);
// ... update data using: new_data = current_data - dt * laplacian
}

Higher-Kinded Types (HKT)

This crate leverages deep_causality_haft to provide functional geometric abstractions.

• Functor: Map functions over the data stored in the topology (e.g., transform node weights).
• BoundedComonad (Extract/Extend):
  • Extract: Get the value at the current "cursor" (focus).
  • Extend: Apply a local computation (convolution) over the neighborhood of every point to produce a new topology. This is the foundation of Graph Neural Networks (GNNs) and Cellular Automata.
• BoundedAdjunction (Unit/Counit):
  • Unit: Embed discrete data into a topological structure.
  • Counit: Project/Integrate topological data back into a flat representation.

Witnesses

Examples

To run examples:

cargo run -p deep_causality_topology --example point_cloud_triangulation

Contribution

Contributions are welcomed especially related to documentation, example code, and fixes. If unsure where to start, just open an issue and ask.

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.