Expand description
Chain complexes, boundary operators, and homology over a chosen coefficient field.
§What this crate is for
A chain complex is a sequence of modules C_k with maps ∂ₖ : C_k → C_{k−1} satisfying
∂ₖ ∘ ∂ₖ₊₁ = 0. That definition mentions no space, no metric and no cell. Homology —
H_k = ker ∂ₖ / im ∂ₖ₊₁ — is defined the moment the composite vanishes, and everything needed to
compute it is linear algebra over the boundary matrices.
Geometry supplies chain complexes, and is not the only thing that does. A quantum
error-correcting code is a chain complex with no cells: H_X and H_Z are parity-check matrices
whose product vanishes over 𝔽₂, and their homology is the code’s logical space. A crate that
wanted homology should not have to carry a Hodge star to get it.
So the chain-complex layer lives here, and deep_causality_topology supplies the geometric half
on top of it.
§The law
Every implementor of ChainComplex owes ∂ₖ ∘ ∂ₖ₊₁ = 0. It is not checkable by the trait, and
every Betti number this crate computes is wrong without it.
§Coefficients
Boundary matrices carry i8, because their entries are incidence numbers lying in {−1, 0, 1}
by construction. The coefficient field is a property of the computation rather than of the
complex, and HomologyField carries it at the call site. The two answers differ: real
projective space has β₁ = 0 over ℚ and β₁ = 1 over 𝔽₂.
§Why the dependency set is two crates
Every other math crate here depends on deep_causality_algebra, and most provide
deep_causality_haft HKT witnesses. This one does neither, for the same reason in both cases:
it has no generic parameter for either to attach to.
Algebra bounds coefficient types, and this crate has no coefficient type. Across
deep_causality_topology and deep_causality_linear the algebra tower appears as a bound on a
container’s element parameter — RealField on 77 sites, Field on 24, Ring on 7 — as in
Chain<T> where T: AbelianGroup or SimplicialComplex<T> where T: RealField. No container
in the workspace implements an algebra trait; the only impl AbelianGroup for is the tower’s
own blanket over scalars.
Here the coefficients are fixed. ChainComplex::boundary_matrix returns CsrMatrix<i8>
because incidence numbers lie in {−1, 0, 1} by construction, Gf2Chain’s entries are always
Gf2, and HomologyField is an enum naming a field rather than a parameter ranging over one.
There is no T to constrain, so a dependency on the tower would be an unused one — and
cargo-machete in .github/workflows/rust_deps.yml would say so.
Gf2Chain<W> is not a functor in W. Every HKT witness in the workspace binds
type Type<T> to a container generic in its element: CsrMatrix<T>, DenseVector<T>,
Chain<T>. W is the storage word — u8 through u64 — and the elements are single bits.
fmap: Gf2Chain<A> -> Gf2Chain<B> would mean re-packing into a different word width, which maps
no content and satisfies no functor law about it.
Both crates remain reachable transitively through deep_causality_linear. If a coefficient
parameter is ever added — a ChainComplex<R> over a general ring, which
openspec/changes/archive/2026-08-30-extract-homology-crate/design.md rejects on the merits — the algebra bound
arrives with it.
Re-exports§
pub use crate::errors::homology_error::HomologyError;pub use crate::errors::homology_error::HomologyErrorEnum;pub use crate::traits::chain_complex::ChainComplex;pub use crate::types::gf2_chain::Gf2Chain;pub use crate::types::homology_field::HomologyField;