Simplicial Homology Library

A Go library for computing homology groups of simplicial complexes over the integers (Z).

Features

• Complete homology computation including Betti numbers and torsion coefficients
• Smith Normal Form algorithm for integer matrices
• Oriented simplices with proper boundary operator computation
• Built-in examples: sphere, torus, projective plane, and more
• Clean, idiomatic Go implementation focused on correctness and clarity

Installation

go get github.com/81ueman/simplex

Quick Start

package main

import (
    "fmt"
    "github.com/81ueman/simplex/complex"
    "github.com/81ueman/simplex/homology"
)

func main() {
    // Build a torus
    torus := complex.BuildTorus()

    // Compute homology
    result := homology.ComputeHomology(torus)

    // Display results
    fmt.Println(result)
    // Output:
    // Homology Groups:
    //   H_0 = Z
    //   H_1 = Z^2
    //   H_2 = Z
}

Architecture

The library is organized into several packages:

simplex - Core Simplex Types

• Oriented simplices with canonical ordering
• Face computation with correct boundary signs
• Efficient hashing for complex indexing

complex - Simplicial Complexes

• Simplicial complex construction and validation
• Built-in constructors for common spaces
• Closure under face operations

chain - Chain Groups

• Formal Z-linear combinations of simplices
• Boundary operator implementation
• Verification of ∂² = 0

matrix - Integer Linear Algebra

• Integer matrix operations
• Extended Euclidean algorithm for GCD
• Smith Normal Form computation

homology - Homology Computation

• Complete homology group calculation
• Betti numbers and torsion extraction
• Euler characteristic computation

Examples

Computing Homology of Classic Spaces

// Circle S¹
circle := complex.BuildCircle(6)
result := homology.ComputeHomology(circle)
// H_0 = Z, H_1 = Z

// Sphere S²
sphere := complex.BuildSphere(2)
result := homology.ComputeHomology(sphere)
// H_0 = Z, H_1 = 0, H_2 = Z

// Torus T²
torus := complex.BuildTorus()
result := homology.ComputeHomology(torus)
// H_0 = Z, H_1 = Z^2, H_2 = Z

// Projective Plane RP²
rp2 := complex.BuildProjectivePlane()
result := homology.ComputeHomology(rp2)
// H_0 = Z, H_1 = Z/2Z (torsion!), H_2 = 0

Building Custom Complexes

// Build from individual simplices
sc := complex.New()
tri1 := simplex.NewSimplex([]simplex.Vertex{0, 1, 2})
tri2 := simplex.NewSimplex([]simplex.Vertex{1, 2, 3})
sc.AddSimplex(tri1)
sc.AddSimplex(tri2)

// Or from maximal simplices (facets)
facets := []simplex.Simplex{tri1, tri2}
sc := complex.BuildFromFacets(facets)

Mathematical Background

Homology Groups

For a simplicial complex K, the k-th homology group is:

H_k(K) = ker(∂_k) / im(∂_{k+1})

where ∂_k : C_k → C_{k-1} is the boundary operator.

Computation via Smith Normal Form

The library computes homology using the Smith Normal Form of boundary matrices:

1. Construct boundary operators ∂_k and ∂_{k+1} as integer matrices
2. Compute Smith Normal Form: S = U·∂·V where S is diagonal
3. Extract Betti numbers: β_k = n_k - rank(∂_k) - rank(∂_{k+1})
4. Extract torsion: from invariant factors > 1 in SNF(∂_{k+1})

Betti Numbers

The k-th Betti number β_k counts the number of k-dimensional "holes":

• β_0 = number of connected components
• β_1 = number of 1-dimensional holes (loops)
• β_2 = number of 2-dimensional holes (voids)

Torsion

Torsion captures "twisting" in the space. For example:

• RP² has H_1(RP²) = Z/2Z torsion (Klein bottle property)
• Orientable surfaces have no torsion

Running the Examples

go run main.go

Output:

Simplicial Homology Computation Examples
=========================================

Computing homology of: Torus T²
----------------------------------------
Homology Groups:
  H_0 = Z
  H_1 = Z^2
  H_2 = Z

Betti Numbers: β_0=1, β_1=2, β_2=1
Euler Characteristic: χ = 0

Testing

Run all tests:

go test ./...

The test suite includes:

• Unit tests for all components
• Integration tests with known topological spaces
• Verification of ∂² = 0
• Smith Normal Form correctness tests

Design Principles

1. Correctness over performance: Optimized for < 100 simplices, clarity prioritized
2. Canonical representations: Simplices stored in canonical form to avoid duplicates
3. Orientation tracking: Proper handling of oriented simplices for integer homology
4. Idiomatic Go: Clean interfaces, explicit error handling, comprehensive tests

References

• Hatcher, "Algebraic Topology"
• Edelsbrunner & Harer, "Computational Topology"
• Smith Normal Form algorithms for homology computation

License

MIT

Author

Built with Claude Code