topology · FilteredComplex

14 accepted declarations. Python and Rust forms, contracts, evidence, failure boundaries, and checked usages are kept together below.

Worked example

The complete checked program See a one-cycle appear and die in a filtered triangle uses this API directly.

# SPDX-License-Identifier: MIT
# Copyright (c) 2026 Benjamin Antieau and Deven Manam
"""See a one-cycle appear and die in a filtered triangle."""

from noether.numthy import FiniteField
from noether.topology import FilteredComplex


def main() -> None:
    filtration = FilteredComplex(
        [
            ([0], 0.0),
            ([1], 0.0),
            ([2], 0.0),
            ([0, 1], 1.0),
            ([0, 2], 1.0),
            ([1, 2], 2.0),
            ([0, 1, 2], 3.0),
        ]
    )
    filtration.verify()
    barcode = filtration.persistent_homology(ring=FiniteField.prime(2))
    assert (1, 2.0, 3.0) in barcode
    assert barcode.betti_at(2.5) == [1, 1]
    print(f"barcode: {barcode.bars}")


if __name__ == "__main__":
    main()

Run it with .venv/bin/python examples/24_homology_and_persistence.py.

topology.FilteredComplex

A checked finite real-valued filtration of an abstract simplicial complex.

PythonRust

FilteredComplex(entries: list[tuple[list[int], float]])

noether::topology::FilteredComplex · Direct Rust declaration

pub struct FilteredComplex { /* private fields */ }

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, geom-core, m4rst, m4rste
GIL	attached / bounded
Semantic ID	noether/topology/FilteredComplex@1

Executable usage: examples/24_homology_and_persistence.py:10 · examples/24_homology_and_persistence.py:6 · validation/unit/geometry/test_acceptance_workload.py:10 · validation/unit/geometry/test_acceptance_workload.py:35 · validation/unit/infra/test_public_api_index.py:178 · validation/unit/infra/test_public_api_index.py:231

topology.FilteredComplex.__len__

Return len(self).

PythonRust

(self) -> int

noether::topology::FilteredComplex · Python projection

Python projection convenience over this Rust mathematical type

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, geom-core, m4rst, m4rste
GIL	attached / bounded
Semantic ID	noether/topology/FilteredComplex@1

Executable usage: validation/unit/topology/test_filtration_builders.py:109 · validation/unit/topology/test_filtration_builders.py:14

topology.FilteredComplex.alpha

Construct the alpha filtration carried by an existing triangulation.

Detailed contract

Construct the alpha filtration carried by a Delaunay triangulation. max_scale is a ball radius, matching Self::cech. max_dimension is the largest simplex dimension returned. The already-built triangulation is consumed as geometry but remains reusable by the caller; Noether does not triangulate the points again. use noether::geometry::{delaunay, PointCloud}; use noether::topology::FilteredComplex; let points = PointCloud::new(&[ vec![0.0, 0.0], vec![3.0, 0.0], vec![0.0, 4.0], ])?; let triangulation = delaunay(&points)?; let filtration = FilteredComplex::alpha(&triangulation, 3.0, 2)?; assert!(filtration.values().contains(&2.5));

PythonRust

(triangulation: Triangulation, *, max_scale: float, max_dimension: int, max_face_slots: int | None=None) -> FilteredComplex

noether::topology::FilteredComplex::alpha · Direct Rust declaration

pub fn alpha( triangulation: &Triangulation, max_scale: f64, max_dimension: usize, ) -> Result<Self, TopologyError>

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, geom-core, m4rst, m4rste
GIL	released
Semantic ID	noether/topology/FilteredComplex@1

Executable usage: validation/unit/geometry/test_acceptance_workload.py:35 · validation/unit/topology/test_filtration_builders.py:63 · validation/unit/topology/test_filtration_builders.py:74 · validation/unit/topology/test_filtration_builders.py:83 · validation/corpus/linalg/galois-orbit-cubic-independence.py:12 · validation/corpus/linalg/galois-orbit-cubic-independence.py:16

topology.FilteredComplex.cech

Construct a Čech filtration from a checked Euclidean point cloud.

Detailed contract

Construct the Čech filtration of a Euclidean point cloud. max_scale is a ball radius, so an edge of length d enters at d / 2. This differs deliberately from Vietoris–Rips’ distance axis.

PythonRust

(points: PointCloud, *, max_scale: float, max_dimension: int) -> FilteredComplex

noether::topology::FilteredComplex::cech · Direct Rust declaration

pub fn cech( points: &PointCloud, max_scale: f64, max_dimension: usize, ) -> Result<Self, TopologyError>

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, geom-core, m4rst, m4rste
GIL	released
Semantic ID	noether/topology/FilteredComplex@1

Executable usage: validation/unit/topology/test_filtration_builders.py:52 · validation/unit/topology/test_filtration_builders.py:56

topology.FilteredComplex.constant

Give every simplex of complex the same filtration value.

Detailed contract

Give every simplex of complex the same finite filtration value.

PythonRust

(complex: SimplicialComplex, value: float=0.0) -> FilteredComplex

noether::topology::FilteredComplex::constant · Direct Rust declaration

pub fn constant( complex: &SimplicialComplex, value: f64, ) -> Result<Self, TopologyError>

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, geom-core, m4rst, m4rste
GIL	attached / bounded
Semantic ID	noether/topology/FilteredComplex@1

Executable usage: validation/unit/commalg/test_curve_facade.py:150 · validation/unit/commalg/test_normalization_facade.py:71 · validation/unit/commalg/test_polynomial_ideal_facade.py:304 · validation/unit/commalg/test_polynomial_ideal_facade.py:409 · validation/unit/commalg/test_polynomial_ideal_facade.py:413 · validation/unit/commalg/test_polynomial_ideal_facade.py:62

topology.FilteredComplex.dimension

Largest simplex dimension; the empty filtered complex has dimension -1.

Detailed contract

Largest simplex dimension, or -1 for the empty filtered complex.

PythonRust

(self) -> int

noether::topology::FilteredComplex::dimension · Direct Rust declaration

pub fn dimension(&self) -> i64

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, geom-core, m4rst, m4rste
GIL	attached / bounded
Semantic ID	noether/topology/FilteredComplex@1

Executable usage: examples/03_exact_linear_systems.py:15 · examples/03_exact_linear_systems.py:16 · examples/15_groebner_twisted_cubic.py:14 · examples/15_groebner_twisted_cubic.py:28 · examples/27_weight_characters.py:25 · examples/34_finite_group_cohomology.py:13

topology.FilteredComplex.entries

Canonical (simplex, value) entries.

PythonRust

(self) -> list[tuple[list[int], float]]

noether::topology::FilteredComplex · Python projection

Python projection convenience over this Rust mathematical type

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, geom-core, m4rst, m4rste
GIL	attached / bounded
Semantic ID	noether/topology/FilteredComplex@1

Executable usage: examples/30_modules_and_resolutions.py:46 · examples/30_modules_and_resolutions.py:51 · validation/unit/homalg/test_padic_homology_facade.py:161 · validation/unit/infra/test_boundary_properties.py:28 · validation/unit/infra/test_boundary_properties.py:29 · validation/unit/infra/test_docs_site_generator.py:24

topology.FilteredComplex.is_empty

Whether no nonempty simplex is present.

PythonRust

(self) -> bool

noether::topology::FilteredComplex::is_empty · Direct Rust declaration

pub fn is_empty(&self) -> bool

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, geom-core, m4rst, m4rste
GIL	attached / bounded
Semantic ID	noether/topology/FilteredComplex@1

Executable usage: validation/unit/combinatorics/test_poset.py:113 · validation/unit/topology/test_filtration_builders.py:119 · validation/unit/topology/test_persistence_facade.py:45 · validation/unit/topology/test_persistence_facade.py:47 · validation/unit/topology/test_simplicial_complex_facade.py:47 · validation/unit/topology/test_simplicial_complex_facade.py:49

topology.FilteredComplex.persistent_homology

Persistent homology over Q or a finite field.

Detailed contract

Persistent homology over Q or a finite field.

Prime fields use the specialized sparse engine reduction. Extension fields use the generic facade reduction as the exact correctness floor.

Compute persistent homology over an exact field. This generic reduction is the correctness floor. Implementations may dispatch to a packed or sparse reducer for a particular field and workload, but must return the same checked Barcode.

PythonRust

(self, *, ring: RationalField | FiniteField) -> Barcode

noether::topology::FilteredComplex::persistent_homology · Direct Rust declaration

pub fn persistent_homology<R: Field>( &self, field: R, ) -> Result<Barcode<R>, TopologyError>

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Dispatch / backing	m4rst, m4rste, noether generic
GIL	released
Semantic ID	noether/topology/FilteredComplex@1
Contexts	Q, finite fields
Failures	unsupported coefficient context, integral barcode request

Executable usage: examples/24_homology_and_persistence.py:22 · validation/unit/infra/test_public_api_index.py:178 · validation/unit/infra/test_public_api_index.py:231 · validation/unit/topology/test_acceptance_workload.py:30 · validation/unit/topology/test_acceptance_workload.py:31 · validation/unit/topology/test_acceptance_workload.py:32

topology.FilteredComplex.simplices

Simplices in canonical filtration order.

PythonRust

(self) -> list[list[int]]

noether::topology::FilteredComplex::simplices · Direct Rust declaration

pub fn simplices(&self) -> &[Simplex]

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, geom-core, m4rst, m4rste
GIL	attached / bounded
Semantic ID	noether/topology/FilteredComplex@1

Executable usage: examples/28_steiner_categories.py:25 · validation/unit/geometry/test_acceptance_workload.py:42 · validation/unit/geometry/test_geometry_facade.py:60 · validation/unit/geometry/test_geometry_facade.py:64 · validation/unit/geometry/test_geometry_facade.py:82 · validation/unit/topology/test_persistence_facade.py:60

topology.FilteredComplex.slice_at

The sublevel simplicial complex with value at most scale.

Detailed contract

The sublevel simplicial complex containing cells with value at most scale.

PythonRust

(self, scale: float) -> SimplicialComplex

noether::topology::FilteredComplex::slice_at · Direct Rust declaration

pub fn slice_at(&self, scale: f64) -> Result<SimplicialComplex, TopologyError>

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, geom-core, m4rst, m4rste
GIL	attached / bounded
Semantic ID	noether/topology/FilteredComplex@1

Executable usage: validation/unit/topology/test_acceptance_workload.py:39 · validation/unit/topology/test_persistence_facade.py:103

topology.FilteredComplex.values

Finite filtration values aligned with simplices.

Detailed contract

Finite filtration values aligned with simplices.

PythonRust

(self) -> list[float]

noether::topology::FilteredComplex::values · Direct Rust declaration

pub fn values(&self) -> &[f64]

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, geom-core, m4rst, m4rste
GIL	attached / bounded
Semantic ID	noether/topology/FilteredComplex@1

Executable usage: validation/unit/combinatorics/test_partition_types.py:3 · validation/unit/commalg/test_context_tower_workload.py:70 · validation/unit/commalg/test_context_tower_workload.py:82 · validation/unit/homalg/test_exact_submodules.py:31 · validation/unit/homalg/test_exact_submodules.py:32 · validation/unit/homalg/test_exterior_algebra.py:382

topology.FilteredComplex.verify

Recheck finiteness, uniqueness, face closure, and monotonicity.

PythonRust

(self) -> None

noether::topology::FilteredComplex · Python projection

Python projection convenience over this Rust mathematical type

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, geom-core, m4rst, m4rste
GIL	attached / bounded
Semantic ID	noether/topology/FilteredComplex@1

Executable usage: examples/01_bezout_certificates.py:10 · examples/01_bezout_certificates.py:3 · examples/03_exact_linear_systems.py:13 · examples/03_exact_linear_systems.py:3 · examples/04_smith_normal_form.py:12 · examples/06_shortest_lattice_vectors.py:12

topology.FilteredComplex.vietoris_rips

Construct a Vietoris–Rips filtration from any checked finite metric.

Detailed contract

Construct the Vietoris–Rips filtration of any checked finite metric. max_scale is a distance. max_dimension is the largest simplex dimension materialized; homology in degree k needs it to be at least k + 1 so deaths can be detected.

PythonRust

(metric: Metric, *, max_scale: float, max_dimension: int) -> FilteredComplex

noether::topology::FilteredComplex::vietoris_rips · Direct Rust declaration

pub fn vietoris_rips<M: Metric + ?Sized>( metric: &M, max_scale: f64, max_dimension: usize, ) -> Result<Self, TopologyError>

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, geom-core, m4rst, m4rste
GIL	released
Semantic ID	noether/topology/FilteredComplex@1

Executable usage: validation/unit/topology/test_filtration_builders.py:104 · validation/unit/topology/test_filtration_builders.py:118 · validation/unit/topology/test_filtration_builders.py:30 · validation/unit/topology/test_filtration_builders.py:44 · validation/unit/topology/test_filtration_builders.py:88 · validation/unit/topology/test_filtration_builders.py:97