homalg · FreeResolution¶

18 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.FreeResolution`¶

A verified finite free resolution over a supported polynomial field.

PythonRust

class FreeResolution

noether::homalg::FreeResolution · Direct Rust declaration

pub struct FreeResolution<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/FreeResolution@1

Executable usage: validation/unit/commalg/test_polynomial_ideal_facade.py:36 · validation/unit/commalg/test_polynomial_ideal_facade.py:570 · validation/unit/homalg/test_module_facade.py:25 · validation/unit/homalg/test_module_facade.py:428 · validation/unit/homalg/test_module_facade.py:796 · validation/unit/homalg/test_module_facade.py:823

`homalg.FreeResolution.augmentation`¶

Return the augmentation recorded by this FreeResolution.

Detailed contract

Degree-zero map from the represented F_0 to the original presentation generators.

PythonRust

(self) -> ModuleHomomorphism[_GroebnerModuleRing]

noether::homalg::FreeResolution::augmentation · Direct Rust declaration

pub fn augmentation(&self) -> &ModuleHomomorphism<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/FreeResolution@1

Executable usage: validation/unit/homalg/test_module_facade.py:816 · validation/unit/homalg/test_module_facade.py:817 · validation/unit/homalg/test_module_facade.py:844 · validation/bench/magma_release.py:3120 · validation/bench/magma_release.py:3130 · validation/bench/magma_release.py:3141

`homalg.FreeResolution.augmentation_inverse`¶

Return the augmentation inverse recorded by this FreeResolution.

Detailed contract

Degree-zero inverse to the augmentation on the two presented cokernels.

PythonRust

(self) -> ModuleHomomorphism[_GroebnerModuleRing]

noether::homalg::FreeResolution::augmentation_inverse · Direct Rust declaration

pub fn augmentation_inverse(&self) -> &ModuleHomomorphism<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/FreeResolution@1

Executable usage: validation/unit/homalg/test_module_facade.py:818 · validation/unit/homalg/test_module_facade.py:845

`homalg.FreeResolution.completeness`¶

Return the completeness recorded by this FreeResolution.

Detailed contract

Exact completeness or truncation claim.

PythonRust

(self) -> ResolutionCompleteness

noether::homalg::FreeResolution::completeness · Direct Rust declaration

pub fn completeness(&self) -> &ResolutionCompleteness

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/FreeResolution@1

Executable usage: validation/unit/homalg/test_module_facade.py:422 · validation/unit/homalg/test_module_facade.py:423 · validation/unit/homalg/test_module_facade.py:812 · validation/unit/homalg/test_module_facade.py:813 · validation/unit/homalg/test_module_facade.py:820 · validation/unit/homalg/test_module_facade.py:821

`homalg.FreeResolution.differential`¶

Compute differential for this FreeResolution.

Detailed contract

Differential d_degree: F_degree -> F_(degree-1).

PythonRust

(self, degree: int) -> ModuleHomomorphism[_GroebnerModuleRing] | None

noether::homalg::FreeResolution::differential · Direct Rust declaration

pub fn differential(&self, degree: usize) -> Option<&ModuleHomomorphism<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/FreeResolution@1

Executable usage: validation/unit/commalg/test_kahler_differentials.py:142 · validation/unit/commalg/test_kahler_differentials.py:143 · validation/unit/homalg/test_chain_complex.py:27 · validation/unit/homalg/test_chain_complex.py:28 · validation/unit/homalg/test_module_facade.py:425 · validation/unit/homalg/test_module_facade.py:426

`homalg.FreeResolution.ext`¶

Compute ext for this FreeResolution.

Detailed contract

Compute Ext^degree(module(), coefficient_module) from this verified resolution of the first argument. Compute Ext^degree(module(), coefficient_module) from an honestly bounded quotient-ring resolution of the first argument.

PythonRust

(self, coefficient_module: PresentedModule[_GroebnerModuleRing], degree: int, order: ModuleMonomialOrder) -> DerivedModule[_GroebnerModuleRing]

noether::homalg::FreeResolution::ext · Direct Rust declaration

pub fn ext( &self, coefficient_module: &PresentedModule<PolynomialRing<C>>, degree: usize, order: ModuleMonomialOrder, ) -> Result<DerivedModule<PolynomialRing<C>>, DerivedError>
pub fn ext( &self, coefficient_module: &PresentedModule<QuotientRing<PolynomialRing<C>>>, degree: usize, order: ModuleMonomialOrder, ) -> Result<DerivedModule<QuotientRing<PolynomialRing<C>>>, DerivedError>

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	released
Semantic ID	noether/homalg/FreeResolution@1

Executable usage: validation/unit/homalg/test_module_facade.py:353 · validation/unit/homalg/test_module_facade.py:372 · validation/unit/homalg/test_module_facade.py:374 · validation/unit/homalg/test_module_facade.py:431 · validation/unit/infra/test_discovery.py:106 · validation/unit/infra/test_discovery.py:111

`homalg.FreeResolution.free_module`¶

Compute free module for this FreeResolution.

Detailed contract

Free module in one represented homological degree.

PythonRust

(self, degree: int) -> FreeModule[_GroebnerModuleRing] | None

noether::homalg::FreeResolution::free_module · Direct Rust declaration

pub fn free_module(&self, degree: usize) -> Option<&FreeModule<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/FreeResolution@1

Executable usage: validation/unit/homalg/test_module_facade.py:469 · validation/unit/homalg/test_module_facade.py:470 · validation/unit/homalg/test_module_facade.py:471 · validation/unit/homalg/test_module_facade.py:800 · validation/unit/homalg/test_module_facade.py:801 · validation/unit/homalg/test_module_facade.py:802

`homalg.FreeResolution.from_json`¶

Deserialize and revalidate a FreeResolution from typed JSON.

Detailed contract

Deserialize and independently revalidate a resolution. Deserialize and independently revalidate quotient-resolution evidence.

PythonRust

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

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

pub fn from_json(value: &str) -> Result<Self, NoetherError>where C: for<'de> Deserialize<'de>, C::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	released
Semantic ID	noether/homalg/FreeResolution@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.FreeResolution.from_maps`¶

Construct a FreeResolution using maps.

Detailed contract

Construct a resolution from exact maps and admit it only after an independent verification of every requested claim. This is the checked import path for complexes produced by another algorithm or computer algebra system. augmentation and augmentation_inverse must exhibit mutually inverse maps on the original and represented cokernels; merely matching Betti numbers or chain identities is not sufficient. Admit a bounded quotient-ring resolution only after replaying every represented exactness and augmentation claim.

PythonRust

(cls, module: PresentedModule[_GroebnerModuleRing], differentials: Sequence[ModuleHomomorphism[_GroebnerModuleRing]], augmentation: ModuleHomomorphism[_GroebnerModuleRing], augmentation_inverse: ModuleHomomorphism[_GroebnerModuleRing], completeness: ResolutionCompleteness, minimality: ResolutionMinimality) -> FreeResolution[_GroebnerModuleRing]

noether::homalg::FreeResolution::from_maps · Direct Rust declaration

pub fn from_maps( module: PresentedModule<PolynomialRing<C>>, differentials: Vec<ModuleHomomorphism<PolynomialRing<C>>>, augmentation: ModuleHomomorphism<PolynomialRing<C>>, augmentation_inverse: ModuleHomomorphism<PolynomialRing<C>>, completeness: ResolutionCompleteness, minimality: ResolutionMinimality, ) -> Result<Self, ResolutionError>
pub fn from_maps( module: PresentedModule<QuotientRing<PolynomialRing<C>>>, differentials: Vec<ModuleHomomorphism<QuotientRing<PolynomialRing<C>>>>, augmentation: ModuleHomomorphism<QuotientRing<PolynomialRing<C>>>, augmentation_inverse: ModuleHomomorphism<QuotientRing<PolynomialRing<C>>>, completeness: ResolutionCompleteness, minimality: ResolutionMinimality, ) -> Result<Self, ResolutionError>

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/FreeResolution@1

Executable usage: validation/unit/homalg/test_module_facade.py:837 · validation/bench/macaulay2_core.py:1561

`homalg.FreeResolution.graded_betti_table`¶

Compute graded betti table for this FreeResolution.

Detailed contract

Derive exact multigraded Betti numbers from verified minimal shifts.

PythonRust

(self: FreeResolution[_FieldModuleRing]) -> GradedBettiTable

noether::homalg::FreeResolution::graded_betti_table · Direct Rust declaration

pub fn graded_betti_table( &self, ) -> Result<GradedBettiTable, GradedBettiTableError>

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	released
Semantic ID	noether/homalg/FreeResolution@1

Executable usage: examples/30_modules_and_resolutions.py:44 · validation/unit/homalg/test_module_facade.py:825 · validation/unit/homalg/test_module_facade.py:850 · validation/unit/homalg/test_module_facade.py:862 · validation/unit/homalg/test_module_facade.py:874 · validation/bench/macaulay2_core.py:1262

`homalg.FreeResolution.is_minimal`¶

Test whether this FreeResolution is minimal.

Detailed contract

Whether minimality has been independently verified.

PythonRust

(self) -> bool

noether::homalg::FreeResolution::is_minimal · Direct Rust declaration

pub fn is_minimal(&self) -> bool

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/FreeResolution@1

Executable usage: validation/unit/homalg/test_module_facade.py:500 · validation/unit/homalg/test_module_facade.py:815 · validation/unit/homalg/test_module_facade.py:830 · validation/unit/homalg/test_module_facade.py:832 · validation/unit/homalg/test_module_facade.py:836 · validation/unit/homalg/test_module_facade.py:873

`homalg.FreeResolution.length`¶

Return the length recorded by this FreeResolution.

Detailed contract

Greatest represented homological degree.

PythonRust

(self) -> int

noether::homalg::FreeResolution::length · Direct Rust declaration

pub fn length(&self) -> usize

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/FreeResolution@1

Executable usage: validation/unit/groups/test_permutation_group_facade.py:52 · validation/unit/groups/test_permutation_group_facade.py:53 · validation/unit/groups/test_permutation_group_facade.py:54 · validation/unit/groups/test_permutation_group_facade.py:55 · validation/unit/groups/test_permutation_group_facade.py:56 · validation/unit/homalg/test_module_facade.py:421

`homalg.FreeResolution.minimality`¶

Return the minimality recorded by this FreeResolution.

Detailed contract

Exact minimality claim.

PythonRust

(self) -> ResolutionMinimality

noether::homalg::FreeResolution::minimality · Direct Rust declaration

pub fn minimality(&self) -> &ResolutionMinimality

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/FreeResolution@1

Executable usage: validation/unit/homalg/test_module_facade.py:814 · validation/unit/homalg/test_module_facade.py:831 · validation/unit/homalg/test_module_facade.py:832 · validation/unit/homalg/test_module_facade.py:833 · validation/unit/homalg/test_module_facade.py:835 · validation/bench/macaulay2_core.py:1656

`homalg.FreeResolution.minimalize`¶

Compute minimalize for this FreeResolution.

Detailed contract

Cancel every homogeneous unit entry and verify the resulting minimal complex and its induced equivalence to the original presentation.

PythonRust

(self: FreeResolution[_FieldModuleRing]) -> FreeResolution[_FieldModuleRing]

noether::homalg::FreeResolution::minimalize · Direct Rust declaration

pub fn minimalize(&self) -> Result<Self, ResolutionError>

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	released
Semantic ID	noether/homalg/FreeResolution@1

Executable usage: validation/unit/homalg/test_module_facade.py:827 · validation/unit/infra/test_discovery.py:109

`homalg.FreeResolution.module`¶

Return the module recorded by this FreeResolution.

Detailed contract

Presented module augmented by this resolution.

PythonRust

(self) -> PresentedModule[_GroebnerModuleRing]

noether::homalg::FreeResolution::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/FreeResolution@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.FreeResolution.to_json`¶

Serialize this FreeResolution to its canonical typed JSON representation.

Detailed contract

Serialize all exact maps and the completeness claim as typed JSON.

PythonRust

(self) -> str

noether::homalg::FreeResolution::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	released
Semantic ID	noether/homalg/FreeResolution@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.FreeResolution.tor`¶

Compute tor for this FreeResolution.

Detailed contract

Compute Tor_degree(module(), coefficient_module) from this verified resolution. Compute Tor_degree(module(), coefficient_module) from an honestly bounded quotient-ring resolution.

PythonRust

(self, coefficient_module: PresentedModule[_GroebnerModuleRing], degree: int, order: ModuleMonomialOrder) -> DerivedModule[_GroebnerModuleRing]

noether::homalg::FreeResolution::tor · Direct Rust declaration

pub fn tor( &self, coefficient_module: &PresentedModule<PolynomialRing<C>>, degree: usize, order: ModuleMonomialOrder, ) -> Result<DerivedModule<PolynomialRing<C>>, DerivedError>
pub fn tor( &self, coefficient_module: &PresentedModule<QuotientRing<PolynomialRing<C>>>, degree: usize, order: ModuleMonomialOrder, ) -> Result<DerivedModule<QuotientRing<PolynomialRing<C>>>, DerivedError>

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	released
Semantic ID	noether/homalg/FreeResolution@1

Executable usage: validation/unit/homalg/test_module_facade.py:353 · validation/unit/homalg/test_module_facade.py:371 · validation/unit/homalg/test_module_facade.py:373 · validation/unit/homalg/test_module_facade.py:390 · validation/unit/homalg/test_module_facade.py:399 · validation/unit/homalg/test_module_facade.py:405

`homalg.FreeResolution.verify`¶

Replay and verify the mathematical evidence carried by this FreeResolution.

Detailed contract

Independently recheck endpoints, chain identities, augmentation image, and image-kernel equality in every claimed position. Independently verify a finite or honestly truncated free resolution over a polynomial quotient.

PythonRust

(self) -> None

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

pub fn verify(&self) -> Result<(), ResolutionError>

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	released
Semantic ID	noether/homalg/FreeResolution@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

homalg · FreeResolution¶

Worked example¶

homalg.FreeResolution¶

homalg.FreeResolution.augmentation¶

homalg.FreeResolution.augmentation_inverse¶

homalg.FreeResolution.completeness¶

homalg.FreeResolution.differential¶

homalg.FreeResolution.ext¶

homalg.FreeResolution.free_module¶

homalg.FreeResolution.from_json¶

homalg.FreeResolution.from_maps¶

homalg.FreeResolution.graded_betti_table¶

homalg.FreeResolution.is_minimal¶

homalg.FreeResolution.length¶

homalg.FreeResolution.minimality¶

homalg.FreeResolution.minimalize¶

homalg.FreeResolution.module¶

homalg.FreeResolution.to_json¶

homalg.FreeResolution.tor¶

homalg.FreeResolution.verify¶

`homalg.FreeResolution`¶

`homalg.FreeResolution.augmentation`¶

`homalg.FreeResolution.augmentation_inverse`¶

`homalg.FreeResolution.completeness`¶

`homalg.FreeResolution.differential`¶

`homalg.FreeResolution.ext`¶

`homalg.FreeResolution.free_module`¶

`homalg.FreeResolution.from_json`¶

`homalg.FreeResolution.from_maps`¶

`homalg.FreeResolution.graded_betti_table`¶

`homalg.FreeResolution.is_minimal`¶

`homalg.FreeResolution.length`¶

`homalg.FreeResolution.minimality`¶

`homalg.FreeResolution.minimalize`¶

`homalg.FreeResolution.module`¶

`homalg.FreeResolution.to_json`¶

`homalg.FreeResolution.tor`¶

`homalg.FreeResolution.verify`¶