homology-operator

Binary homology operators: kernels, linear representatives, weighted geometry, and persistent transport.

中文 · Documentation · API · Mathematics · Development · MIT License

This project introduces a binary homology operator on the original chain space and provides its Python/Rust implementation. Its kernel realizes homology; the accompanying projection selects cycle representatives that obey all linear relations. Weighted action supplies class mass, distance, and support. Transport between kernels realizes the persistence module of a finite filtration. Definitions and proofs are in the mathematics document; the separate Mathematics section below gives the core relations.

The Python correctness reference uses only the standard library. An optional Rust extension provides packed algebra, compact actions, supported solvers, and batch queries. The Python package version is 0.0.2, an early release. Check the PyPI version record for upload status. The project uses the MIT License.

When to use it

Use the library when you already have F2 boundary matrices and need homology and weighted geometry in the original ordered coordinates, or a finite sequence of chain windows for joint persistence and geometric tracking. Inputs, projections, solver records, and results can be saved and independently checked.

The public input is a chain window. General point-cloud, Rips, and complex builders must be supplied by the caller. True minimum class mass is currently unavailable; selected_mass measures the representative selected by the current projection.

Installation

Python 3.10+ is required. Once the PyPI release is published:

python -m pip install homology-operator==0.0.2

The reference can also be installed from source:

git clone https://github.com/proffitteoy/homology-operator.git
cd homology-operator
python -m pip install .
python examples/single_scale.py

Virtual environments, uv, and optional Rust builds are covered in installation and platform support.

A minimal example

Two vertices joined by one edge represent the same H0 class:

from homology_operator import (
    ChainWindow, HomologyOperator, Matrix, ProjectionProblem, solve_projection,
)

window = ChainWindow(
    k=0,
    A=Matrix.zero(0, 2),
    D=Matrix.from_rows(((1,), (1,))),
    basis_previous=(),
    basis_current=("v0", "v1"),
    basis_next=("edge",),
    weights=(10, 1),
)
solution = solve_projection(ProjectionProblem(window))
if solution.projection is None:
    raise RuntimeError((solution.status, solution.diagnostics))
op = HomologyOperator(window, solution)

assert op.betti() == 1
assert op.same_class((1, 0), (0, 1))
assert op.class_distance((1, 0), (0, 1)) == 0
assert op.class_representative((0, 1)) == (1, 0)
assert op.selected_mass((0, 1)) == 10

query = op.readout("selected_mass", (0, 1))
assert query.state == "Computed" and query.exact
record = op.to_result()

Here the selected representative has mass 10, although another representative of the same class has mass 1. The default FeasibleSolver validates a projection and does not certify minimum stretch. Projection feasibility, exact evaluation of the current objective, and global optimality are reported separately.

project and apply_operator accept arbitrary chains. Class queries require cycles. Matrix and vector coordinates must be integer 0/1 values; invalid inputs are explicitly rejected.

Finite filtrations

Provide a window and operator at each stage. Ordered basis identifiers determine the coordinate inclusions in all three degrees:

from dataclasses import replace
from homology_operator import OperatorFamily

before = replace(window, D=Matrix.zero(2, 0), basis_next=())
windows = (before, window)
operators = tuple(
    HomologyOperator(w, solve_projection(ProjectionProblem(w))) for w in windows
)
family = OperatorFamily((0, 1), windows, operators)

assert family.transport_rank(0, 1).value == 1
barcode = family.barcode()
assert barcode.state == "Computed"
assert family.track_mass((1, 1), 0, 1).value == 0

Barcodes come from T_ij=P_j J_ij|ker(L_i). barcode() reads adjacent transport; barcode_basis() and rank_table() explicitly request potentially quadratic outputs. Intervals use half-open stage endpoints, with None for survival under the declared constant terminal extension. Family snapshots default to schema 2; schema 1 remains readable. See the English guide.

Mathematics

Definition and construction

The input is a finite based chain window in a fixed degree with positive coordinate weights:

C_{k+1}\xrightarrow{D}C_k\xrightarrow{A}C_{k-1},\qquad AD=0.

Choose algebraic generalized inverses with $AGA=A$ and $DUD=D$ and construct

P=(I+DU)(I+GA),\qquad L=I+P,\qquad
\boxed{\ker L=\mathrm{im}\,P\cong H_k(C;\mathbf F_2).}

Each kernel vector uniquely represents a homology class. $P$ preserves cycle classes and enforces linear relations between all representatives: $P(z+y)=Pz+Py$. The same weighted action supplies topology, representative mass, class distance, shared support, and worst stretch. Projected transport between kernels realizes the entire persistence module of a finite filtration, from which the barcode is read. Definitions and proofs are in operator theory.

Minimum stretch

Legal projections need not be unique. Minimum stretch controls every cycle:

\Gamma_w(P)=\max_{0\ne z,\ Az=0}\frac{m_w(Pz)}{m_w(z)},\qquad
\Gamma_*=\min_{P\ \mathrm{legal}}\Gamma_w(P),\qquad
m_w(x)=\sum_{i:x_i=1}w_i.

This equals the minimum-stretch linear section problem for the homology quotient. If $\beta>0$, $1\le\Gamma_*\le\beta$. In the six-edge complex, a minimum-total-mass basis gives masses $(8,8,12)$ and stretch $4/3$; a minimum-stretch operator gives $(8,9,9)$ and stretch $9/8$. Shared-support cancellation controls the combined class. The complete example exhausts all four sections; runnable code reads all values from the actual operator.

The default solver constructs a legal operator. Exact solvers certify optimality within their domains through independent certificates. The eigenvalues of $L$ are only $0,1$; its weighted action supplies geometry.

Capabilities and limits

Every solver output is independently checked for P²=P, AP=0, PD=0, and preservation of cycle homology. Exact F2 algebra does not certify floating-point geometry or the global optimum.

Documentation, contribution, and citation

The English documentation provides installation, quickstart, task guides, API and mathematical references, and development instructions:

• Operator theory: definition, kernel theorem, sections, stretch, geometry, and transport
• Installation and quickstart
• Python API
• Results and serialization
• Implementation architecture and solver contract
• Development and validation
• Implementation status and evidence

Report issues through GitHub Issues. See Contributing before submitting changes. The early-release compatibility policy and publishing procedure are in development.

For research, cite the actual software version and commit. Machine-readable metadata is provided in CITATION.cff. The theory is tied to homology-operator-lab at a fixed commit; its code and validation results are not this package's runtime dependencies or acceptance evidence. See source and dependency notices.

License and release status

The repository uses the MIT License. The Python distribution provides an OS-independent wheel and source archive. During 0.x, patch releases preserve the public API; breaking changes require a minor-version increase and release notes. Existing schema 1/2 snapshots remain covered by restoration tests. Native ABI compatibility is checked independently by semantics version; the extension is built separately from matching source.