homalg · PresentedModuleHomology

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

Worked example

The complete checked program Reduce a module element and certify a minimal free resolution uses this API directly.

# SPDX-License-Identifier: MIT
# Copyright (c) 2026 Benjamin Antieau and Deven Manam
"""Reduce a module element and certify a minimal free resolution."""

from noether import Q
from noether.commalg import Degree, MonomialOrder, PolynomialRing
from noether.homalg import (
    FreeModule,
    ModuleElement,
    ModuleHomomorphism,
    ModuleMonomialOrder,
    PresentedModule,
    Submodule,
)
from noether.linalg import Matrix, Vector


def main() -> None:
    ring = PolynomialRing(Q, ["x", "y", "z", "w"])
    x, y, z, w = ring.generators()
    order = ModuleMonomialOrder.term_over_position(MonomialOrder.GREVLEX)

    ambient = FreeModule(ring, 2)
    first = ModuleElement(ambient, Vector.from_values(ring, [x, y]))
    second = ModuleElement(ambient, Vector.from_values(ring, [y, 1]))
    submodule = Submodule.from_generators(ambient, [first, second])
    basis = submodule.groebner_basis(order)
    reduction = basis.reduce(first + second * x)
    basis.verify()
    reduction.verify()
    assert reduction.is_member()

    target = FreeModule(ring, 1, grading_rank=1, degree_shifts=[Degree([0])])
    source = FreeModule(ring, 3, grading_rank=1, degree_shifts=[Degree([-2])] * 3)
    twisted_cubic = PresentedModule(
        ModuleHomomorphism(
            source,
            target,
            Matrix.from_rows(ring, [[x * z - y**2, x * w - y * z, y * w - z**2]]),
        )
    )
    resolution = twisted_cubic.minimal_free_resolution(order)
    resolution.verify()
    betti = resolution.graded_betti_table()
    betti.verify()
    assert betti.entries == [
        (0, Degree([0]), 1),
        (1, Degree([2]), 3),
        (2, Degree([3]), 2),
    ]
    print(f"module member certified; minimal Betti entries={betti.entries}")


if __name__ == "__main__":
    main()

Run it with .venv/bin/python examples/30_modules_and_resolutions.py.

homalg.PresentedModuleHomology

Exact cycles, boundaries, and quotient evidence for module-valued homology.

PythonRust

class PresentedModuleHomology

noether::homalg::PresentedModuleHomology · Direct Rust declaration

pub struct PresentedModuleHomology<R: Ring> { /* private fields */ }

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core, groebner-kernel, m4rst, m4rste, module-core, resolution-kernel, sparla
GIL	attached / bounded
Semantic ID	noether/homalg/PresentedModuleHomology@1

Executable usage: validation/unit/homalg/test_module_facade.py:300 · validation/unit/homalg/test_module_facade.py:307 · validation/unit/homalg/test_module_facade.py:38 · validation/unit/homalg/test_module_facade.py:549

homalg.PresentedModuleHomology.boundary_lift

Return the boundary lift recorded by this PresentedModuleHomology.

Detailed contract

Incoming differential factored through the cycle module.

PythonRust

(self) -> PresentedModuleHomomorphism[_GroebnerModuleRing]

noether::homalg::PresentedModuleHomology::boundary_lift · Direct Rust declaration

pub fn boundary_lift(&self) -> &PresentedModuleHomomorphism<R>

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core, groebner-kernel, m4rst, m4rste, module-core, resolution-kernel, sparla
GIL	attached / bounded
Semantic ID	noether/homalg/PresentedModuleHomology@1

Executable usage: validation/unit/homalg/test_module_facade.py:304

homalg.PresentedModuleHomology.cycle_inclusion

Return the cycle inclusion recorded by this PresentedModuleHomology.

Detailed contract

Exact inclusion of the cycle module into the middle term.

PythonRust

(self) -> PresentedModuleHomomorphism[_GroebnerModuleRing]

noether::homalg::PresentedModuleHomology::cycle_inclusion · Direct Rust declaration

pub fn cycle_inclusion(&self) -> &PresentedModuleHomomorphism<R>

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core, groebner-kernel, m4rst, m4rste, module-core, resolution-kernel, sparla
GIL	attached / bounded
Semantic ID	noether/homalg/PresentedModuleHomology@1

Executable usage: validation/unit/homalg/test_module_facade.py:303 · validation/unit/homalg/test_module_facade.py:304

homalg.PresentedModuleHomology.from_json

Deserialize and revalidate a PresentedModuleHomology from typed JSON.

Detailed contract

Deserialize and revalidate the complete structural diagram.

PythonRust

(cls, value: str) -> PresentedModuleHomology[_GroebnerModuleRing]

noether::homalg::PresentedModuleHomology::from_json · Direct Rust declaration

pub fn from_json(value: &str) -> Result<Self, NoetherError>where R: for<'de> Deserialize<'de>, R::Element: for<'de> Deserialize<'de>,

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core, groebner-kernel, m4rst, m4rste, module-core, resolution-kernel, sparla
GIL	attached / bounded
Semantic ID	noether/homalg/PresentedModuleHomology@1

Executable usage: validation/unit/category/test_category.py:14 · validation/unit/combin/test_acceptance_workload.py:65 · validation/unit/combin/test_acceptance_workload.py:86 · validation/unit/combin/test_graph_facade.py:106 · validation/unit/combin/test_graph_facade.py:25 · validation/unit/combinatorics/test_kashiwara_crystal.py:32

homalg.PresentedModuleHomology.incoming

Return the incoming recorded by this PresentedModuleHomology.

Detailed contract

Incoming differential whose image supplies the boundaries.

PythonRust

(self) -> PresentedModuleHomomorphism[_GroebnerModuleRing]

noether::homalg::PresentedModuleHomology::incoming · Direct Rust declaration

pub fn incoming(&self) -> &PresentedModuleHomomorphism<R>

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core, groebner-kernel, m4rst, m4rste, module-core, resolution-kernel, sparla
GIL	attached / bounded
Semantic ID	noether/homalg/PresentedModuleHomology@1

Executable usage: validation/unit/homalg/test_padic_homology_facade.py:102 · validation/unit/homalg/test_padic_homology_facade.py:103 · validation/unit/homalg/test_padic_homology_facade.py:161 · validation/unit/homalg/test_padic_homology_facade.py:193 · validation/unit/homalg/test_padic_homology_facade.py:194 · validation/unit/homalg/test_padic_homology_facade.py:195

homalg.PresentedModuleHomology.induced_map

Compute induced map for this PresentedModuleHomology.

Detailed contract

Induce the exact homology map of a three-term chain map. left, middle, and right map the incoming source, middle term, and outgoing target of self to the corresponding terms of target. Both chain squares are checked. The returned map retains a relation certificate proving that cycles map to cycles and boundaries to boundaries. Induce the exact quotient-module homology map of a checked three-term chain map.

PythonRust

(self, target: PresentedModuleHomology[_GroebnerModuleRing], left: PresentedModuleHomomorphism[_GroebnerModuleRing], middle: PresentedModuleHomomorphism[_GroebnerModuleRing], right: PresentedModuleHomomorphism[_GroebnerModuleRing], order: ModuleMonomialOrder) -> PresentedModuleHomomorphism[_GroebnerModuleRing]

noether::homalg::PresentedModuleHomology::induced_map · Direct Rust declaration

pub fn induced_map( &self, target: &Self, left: &PresentedModuleHomomorphism<PolynomialRing<C>>, middle: &PresentedModuleHomomorphism<PolynomialRing<C>>, right: &PresentedModuleHomomorphism<PolynomialRing<C>>, order: ModuleMonomialOrder, ) -> Result<PresentedModuleHomomorphism<PolynomialRing<C>>, ModuleGroebnerError>
pub fn induced_map( &self, target: &Self, left: &PresentedModuleHomomorphism<QuotientRing<PolynomialRing<C>>>, middle: &PresentedModuleHomomorphism<QuotientRing<PolynomialRing<C>>>, right: &PresentedModuleHomomorphism<QuotientRing<PolynomialRing<C>>>, order: ModuleMonomialOrder, ) -> Result<PresentedModuleHomomorphism<QuotientRing<PolynomialRing<C>>>, ModuleGroebnerError>

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core, groebner-kernel, m4rst, m4rste, module-core, resolution-kernel, sparla
GIL	attached / bounded
Semantic ID	noether/homalg/PresentedModuleHomology@1

Executable usage: validation/unit/commalg/test_quotient_facade.py:100 · validation/unit/commalg/test_quotient_facade.py:113 · validation/unit/commalg/test_quotient_facade.py:86 · validation/unit/commalg/test_rational_function_facade.py:123 · validation/unit/commalg/test_rational_function_facade.py:151 · validation/unit/homalg/test_module_facade.py:316

homalg.PresentedModuleHomology.module

Return the module recorded by this PresentedModuleHomology.

Detailed contract

Presented homology module ker(outgoing) / im(incoming).

PythonRust

(self) -> PresentedModule[_GroebnerModuleRing]

noether::homalg::PresentedModuleHomology::module · Direct Rust declaration

pub fn module(&self) -> &PresentedModule<R>

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core, groebner-kernel, m4rst, m4rste, module-core, resolution-kernel, sparla
GIL	attached / bounded
Semantic ID	noether/homalg/PresentedModuleHomology@1

Executable usage: examples/30_modules_and_resolutions.py:3 · examples/30_modules_and_resolutions.py:51 · examples/40_exterior_algebra.py:13 · examples/40_exterior_algebra.py:14 · examples/40_exterior_algebra.py:20 · examples/40_exterior_algebra.py:21

homalg.PresentedModuleHomology.outgoing

Return the outgoing recorded by this PresentedModuleHomology.

Detailed contract

Outgoing differential whose kernel supplies the cycles.

PythonRust

(self) -> PresentedModuleHomomorphism[_GroebnerModuleRing]

noether::homalg::PresentedModuleHomology::outgoing · Direct Rust declaration

pub fn outgoing(&self) -> &PresentedModuleHomomorphism<R>

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core, groebner-kernel, m4rst, m4rste, module-core, resolution-kernel, sparla
GIL	attached / bounded
Semantic ID	noether/homalg/PresentedModuleHomology@1

Executable usage: validation/unit/homalg/test_padic_homology_facade.py:101 · validation/unit/homalg/test_padic_homology_facade.py:103 · validation/unit/homalg/test_padic_homology_facade.py:192 · validation/unit/homalg/test_padic_homology_facade.py:194 · validation/unit/homalg/test_padic_homology_facade.py:195 · validation/unit/homalg/test_padic_homology_facade.py:210

homalg.PresentedModuleHomology.quotient_projection

Return the quotient projection recorded by this PresentedModuleHomology.

Detailed contract

Quotient map from cycles onto the homology module.

PythonRust

(self) -> PresentedModuleHomomorphism[_GroebnerModuleRing]

noether::homalg::PresentedModuleHomology::quotient_projection · Direct Rust declaration

pub fn quotient_projection(&self) -> &PresentedModuleHomomorphism<R>

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core, groebner-kernel, m4rst, m4rste, module-core, resolution-kernel, sparla
GIL	attached / bounded
Semantic ID	noether/homalg/PresentedModuleHomology@1

Executable usage: validation/unit/homalg/test_module_facade.py:172 · validation/unit/homalg/test_module_facade.py:173 · validation/unit/homalg/test_module_facade.py:389 · validation/unit/homalg/test_module_facade.py:392

homalg.PresentedModuleHomology.to_json

Serialize this PresentedModuleHomology to its canonical typed JSON representation.

Detailed contract

Serialize the complete homology diagram and all relation witnesses.

PythonRust

(self) -> str

noether::homalg::PresentedModuleHomology::to_json · Direct Rust declaration

pub fn to_json(&self) -> Result<String, NoetherError>where R: Serialize, R::Element: Serialize,

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core, groebner-kernel, m4rst, m4rste, module-core, resolution-kernel, sparla
GIL	attached / bounded
Semantic ID	noether/homalg/PresentedModuleHomology@1

Executable usage: validation/unit/category/test_category.py:14 · validation/unit/category/test_category.py:15 · validation/unit/combin/test_acceptance_workload.py:30 · validation/unit/combin/test_acceptance_workload.py:65 · validation/unit/combin/test_acceptance_workload.py:86 · validation/unit/combin/test_graph_facade.py:106

homalg.PresentedModuleHomology.verify

Replay and verify the mathematical evidence carried by this PresentedModuleHomology.

Detailed contract

Recompute the two exactness statements defining this homology module. Recompute the two exactness statements defining this quotient-module homology value.

PythonRust

(self, order: ModuleMonomialOrder) -> None

noether::homalg::PresentedModuleHomology::verify · Direct Rust declaration

pub fn verify( &self, order: ModuleMonomialOrder, ) -> Result<(), ModuleGroebnerError>

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core, groebner-kernel, m4rst, m4rste, module-core, resolution-kernel, sparla
GIL	attached / bounded
Semantic ID	noether/homalg/PresentedModuleHomology@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