homalg · ModuleGroebnerBasis

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

Worked example

The complete checked program Reproduce Fisher's order-five elliptic-function normalization uses this API directly.

# SPDX-License-Identifier: MIT
# Copyright (c) 2026 Benjamin Antieau and Deven Manam
"""Reproduce Fisher's order-five elliptic-function normalization."""

from noether import Q
from noether.commalg import RationalFunctionField, WeilDivisor
from noether.numthy import EllipticCurve, NthPowerClassGroup


def main() -> None:
    coefficients = RationalFunctionField(Q, "lambda")
    parameter = coefficients.generator()
    curve = EllipticCurve(
        coefficients,
        [1 - parameter, -parameter, -parameter, 0, 0],
    )
    point = curve.point(0, 0)
    point.verify_exact_order(5)

    miller = curve.miller_function(point, 5)
    divisor = WeilDivisor(
        curve.underlying_curve,
        [
            (curve.origin().underlying_curve_point.as_closed_point(), 5),
            (point.underlying_curve_point.as_closed_point(), -5),
        ],
    )
    function = divisor.riemann_roch_space().basis[0]
    assert (function / miller.function).as_constant() is not None

    evaluation_at_two = function.evaluate_at((2 * point).underlying_curve_point)
    evaluation_at_four = function.evaluate_at((4 * point).underlying_curve_point)
    assert evaluation_at_two.value is not None
    assert evaluation_at_four.value is not None
    classes = NthPowerClassGroup(coefficients, 5)
    normalization = classes.class_of(evaluation_at_two.value) ** -2 * classes.class_of(
        evaluation_at_four.value
    )
    assert normalization.is_identity()
    print("order 5 verified; Riemann--Roch and Miller agree; normalization is trivial")


if __name__ == "__main__":
    main()

Run it with .venv/bin/python examples/26_elliptic_descent_functions.py.

homalg.ModuleGroebnerBasis

A complete reduced module Groebner basis with an exact change map.

PythonRust

class ModuleGroebnerBasis

noether::homalg::ModuleGroebnerBasis · Direct Rust declaration

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

Executable usage: validation/unit/homalg/test_module_facade.py:30 · validation/unit/homalg/test_module_facade.py:530 · validation/unit/homalg/test_module_facade.py:565 · validation/unit/homalg/test_module_facade.py:652

homalg.ModuleGroebnerBasis.basis

Return the basis recorded by this ModuleGroebnerBasis.

Detailed contract

Canonically ordered monic reduced basis as a generator map.

PythonRust

(self) -> Submodule[_GroebnerModuleRing]

noether::homalg::ModuleGroebnerBasis::basis · Direct Rust declaration

pub fn basis(&self) -> &Submodule<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/ModuleGroebnerBasis@1

Executable usage: examples/26_elliptic_descent_functions.py:28 · examples/30_modules_and_resolutions.py:27 · examples/30_modules_and_resolutions.py:28 · examples/30_modules_and_resolutions.py:29 · examples/33_simplicial_cohomology_operations.py:26 · examples/33_simplicial_cohomology_operations.py:27

homalg.ModuleGroebnerBasis.contains

Compute contains for this ModuleGroebnerBasis.

Detailed contract

Whether an ambient element belongs to the input submodule. Whether an ambient value belongs to the generated quotient submodule.

PythonRust

(self, value: ModuleElement[_GroebnerModuleRing]) -> bool

noether::homalg::ModuleGroebnerBasis::contains · Direct Rust declaration

pub fn contains( &self, value: &ModuleElement<PolynomialRing<C>>, ) -> Result<bool, ModuleGroebnerError>
pub fn contains( &self, value: &ModuleElement<QuotientRing<PolynomialRing<C>>>, ) -> Result<bool, 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/ModuleGroebnerBasis@1

Executable usage: examples/38_exact_linear_systems.py:73 · validation/unit/commalg/test_local_algebra.py:63 · validation/unit/commalg/test_prime_localization.py:50 · validation/unit/commalg/test_prime_localization.py:55 · validation/unit/groups/test_acceptance_workload.py:56 · validation/unit/groups/test_permutation_group_facade.py:81

homalg.ModuleGroebnerBasis.from_json

Deserialize and revalidate a ModuleGroebnerBasis from typed JSON.

Detailed contract

Deserialize and independently reverify a complete result. Deserialize and independently reverify a complete quotient-module basis.

PythonRust

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

noether::homalg::ModuleGroebnerBasis::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	attached / bounded
Semantic ID	noether/homalg/ModuleGroebnerBasis@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.ModuleGroebnerBasis.hilbert_series

Compute hilbert series for this ModuleGroebnerBasis.

Detailed contract

Exact Hilbert series of the ambient free-module quotient by the input.

PythonRust

(self: ModuleGroebnerBasis[_FieldModuleRing]) -> HilbertSeries

noether::homalg::ModuleGroebnerBasis::hilbert_series · Direct Rust declaration

pub fn hilbert_series(&self) -> Result<HilbertSeries, 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/ModuleGroebnerBasis@1

Executable usage: validation/unit/commalg/test_monomial_ideal_facade.py:48 · validation/unit/commalg/test_monomial_ideal_facade.py:86 · validation/unit/commalg/test_polynomial_ideal_facade.py:204 · validation/unit/commalg/test_quotient_facade.py:125 · validation/unit/homalg/test_module_facade.py:261 · validation/unit/homalg/test_module_facade.py:502

homalg.ModuleGroebnerBasis.initial_submodule

Compute initial submodule for this ModuleGroebnerBasis.

Detailed contract

Monomial submodule generated by the leading module monomials.

PythonRust

(self: ModuleGroebnerBasis[_FieldModuleRing]) -> Submodule[_FieldModuleRing]

noether::homalg::ModuleGroebnerBasis::initial_submodule · Direct Rust declaration

pub fn initial_submodule( &self, ) -> Result<Submodule<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/ModuleGroebnerBasis@1

Executable usage: validation/unit/homalg/test_module_facade.py:653 · validation/unit/homalg/test_module_facade.py:725

homalg.ModuleGroebnerBasis.input

Return the input recorded by this ModuleGroebnerBasis.

Detailed contract

Original generated submodule.

PythonRust

(self) -> Submodule[_GroebnerModuleRing]

noether::homalg::ModuleGroebnerBasis::input · Direct Rust declaration

pub fn input(&self) -> &Submodule<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/ModuleGroebnerBasis@1

Executable usage: validation/unit/infra/test_mpi_scale_report.py:331 · validation/unit/infra/test_mpi_scale_report.py:363 · validation/unit/infra/test_mpi_scale_report.py:450 · validation/unit/infra/test_mpi_scale_report.py:458 · validation/unit/infra/test_mpi_scale_report.py:469 · validation/unit/infra/test_mpi_scale_report.py:488

homalg.ModuleGroebnerBasis.is_complete

Test whether this ModuleGroebnerBasis is complete.

Detailed contract

This value is complete. Resource-bounded computations fail instead of returning a partial result that could be mistaken for complete.

PythonRust

(self) -> bool

noether::homalg::ModuleGroebnerBasis::is_complete · Direct Rust declaration

pub const fn is_complete(&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/ModuleGroebnerBasis@1

Executable usage: validation/unit/homalg/test_module_facade.py:651 · validation/unit/homalg/test_module_facade.py:720 · validation/corpus/homalg/oscar-module-kernel.py:39

homalg.ModuleGroebnerBasis.leading_monomials

Return the leading monomials recorded by this ModuleGroebnerBasis.

Detailed contract

Ordered leading module monomials of the reduced basis.

PythonRust

(self) -> list[ModuleMonomial]

noether::homalg::ModuleGroebnerBasis::leading_monomials · Direct Rust declaration

pub fn leading_monomials(&self) -> &[ModuleMonomial]

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

Executable usage: validation/unit/homalg/test_module_facade.py:655 · validation/unit/homalg/test_module_facade.py:661

homalg.ModuleGroebnerBasis.lift

Compute lift for this ModuleGroebnerBasis.

Detailed contract

Original-generator coordinates when value belongs to the submodule.

PythonRust

(self, value: ModuleElement[_GroebnerModuleRing]) -> ModuleElement[_GroebnerModuleRing] | None

noether::homalg::ModuleGroebnerBasis::lift · Direct Rust declaration

pub fn lift( &self, value: &ModuleElement<PolynomialRing<C>>, ) -> Result<Option<ModuleElement<PolynomialRing<C>>>, ModuleGroebnerError>
pub fn lift( &self, value: &ModuleElement<QuotientRing<PolynomialRing<C>>>, ) -> Result<Option<ModuleElement<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/ModuleGroebnerBasis@1

Executable usage: examples/11_qadic_witt_vectors.py:12 · examples/11_qadic_witt_vectors.py:13 · examples/11_qadic_witt_vectors.py:14 · examples/11_qadic_witt_vectors.py:15 · validation/unit/commalg/test_acceptance_workload.py:33 · validation/unit/commalg/test_acceptance_workload.py:34

homalg.ModuleGroebnerBasis.multigraded_hilbert_numerator

Compute multigraded hilbert numerator for this ModuleGroebnerBasis.

Detailed contract

Multigraded Hilbert numerator of the quotient of the ambient free module by the input submodule. The ambient module must carry explicit algebraic shifts, with the convention that R(a) contributes T^-a. The computed reduced basis must be homogeneous for the polynomial-ring grading. These checks keep an arbitrary filtered module from being mislabeled as multigraded.

PythonRust

(self: ModuleGroebnerBasis[_FieldModuleRing]) -> list[tuple[Degree, int]]

noether::homalg::ModuleGroebnerBasis::multigraded_hilbert_numerator · Direct Rust declaration

pub fn multigraded_hilbert_numerator( &self, ) -> Result<Vec<(Degree, Integer)>, 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/ModuleGroebnerBasis@1

Executable usage: validation/unit/commalg/test_monomial_ideal_facade.py:80 · validation/unit/commalg/test_monomial_ideal_facade.py:86 · validation/unit/homalg/test_module_facade.py:257 · validation/unit/homalg/test_module_facade.py:263

homalg.ModuleGroebnerBasis.normal_form

Compute normal form for this ModuleGroebnerBasis.

Detailed contract

Canonical normal form of an ambient element. Canonical normal form in the ambient quotient free module.

PythonRust

(self, value: ModuleElement[_GroebnerModuleRing]) -> ModuleElement[_GroebnerModuleRing]

noether::homalg::ModuleGroebnerBasis::normal_form · Direct Rust declaration

pub fn normal_form( &self, value: &ModuleElement<PolynomialRing<C>>, ) -> Result<ModuleElement<PolynomialRing<C>>, ModuleGroebnerError>
pub fn normal_form( &self, value: &ModuleElement<QuotientRing<PolynomialRing<C>>>, ) -> Result<ModuleElement<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/ModuleGroebnerBasis@1

Executable usage: validation/unit/commalg/test_graded_commutative_facade.py:26 · validation/unit/commalg/test_integer_groebner_facade.py:17 · validation/unit/commalg/test_polynomial_ideal_facade.py:194 · validation/unit/commalg/test_polynomial_ideal_facade.py:409 · validation/unit/commalg/test_polynomial_ideal_facade.py:441 · validation/unit/commalg/test_polynomial_ideal_facade.py:52

homalg.ModuleGroebnerBasis.order

Return the order recorded by this ModuleGroebnerBasis.

Detailed contract

Exact module-monomial order.

PythonRust

(self) -> ModuleMonomialOrder

noether::homalg::ModuleGroebnerBasis::order · Direct Rust declaration

pub fn order(&self) -> &ModuleMonomialOrder

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

Executable usage: examples/11_qadic_witt_vectors.py:14 · examples/12_number_field_ideals.py:13 · examples/12_number_field_ideals.py:14 · examples/12_number_field_ideals.py:17 · examples/15_groebner_twisted_cubic.py:18 · examples/19_permutation_groups.py:13

homalg.ModuleGroebnerBasis.reduce

Compute reduce for this ModuleGroebnerBasis.

Detailed contract

Reduce an ambient element and retain quotient and original-generator coordinates. Reduce an ambient quotient-module element and retain both basis and original-generator coordinates.

PythonRust

(self, value: ModuleElement[_GroebnerModuleRing]) -> ModuleReduction[_GroebnerModuleRing]

noether::homalg::ModuleGroebnerBasis::reduce · Direct Rust declaration

pub fn reduce( &self, value: &ModuleElement<PolynomialRing<C>>, ) -> Result<ModuleReduction<PolynomialRing<C>>, ModuleGroebnerError>
pub fn reduce( &self, value: &ModuleElement<QuotientRing<PolynomialRing<C>>>, ) -> Result<ModuleReduction<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/ModuleGroebnerBasis@1

Executable usage: examples/30_modules_and_resolutions.py:28 · validation/unit/commalg/test_local_algebra.py:56 · validation/unit/commalg/test_polynomial_ideal_facade.py:270 · validation/unit/commalg/test_polynomial_ideal_facade.py:304 · validation/unit/homalg/test_local_module.py:28 · validation/unit/homalg/test_module_facade.py:525

homalg.ModuleGroebnerBasis.schreyer_order

Compute schreyer order for this ModuleGroebnerBasis.

Detailed contract

Exact Schreyer order induced on the ordered basis-generator module. Exact Schreyer order induced on the ordered quotient-basis generators.

PythonRust

(self) -> ModuleMonomialOrder

noether::homalg::ModuleGroebnerBasis::schreyer_order · Direct Rust declaration

pub fn schreyer_order(&self) -> ModuleMonomialOrder

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

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

homalg.ModuleGroebnerBasis.syzygies

Compute syzygies for this ModuleGroebnerBasis.

Detailed contract

Compute generators for all relations among the original input generators using Schreyer’s critical-pair theorem and the retained change map. Relations among the original quotient-module generators.

PythonRust

(self) -> Submodule[_GroebnerModuleRing]

noether::homalg::ModuleGroebnerBasis::syzygies · Direct Rust declaration

pub fn syzygies( &self, ) -> Result<Submodule<PolynomialRing<C>>, ModuleGroebnerError>
pub fn syzygies( &self, ) -> Result<Submodule<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/ModuleGroebnerBasis@1

Executable usage: validation/unit/homalg/test_module_facade.py:738 · validation/unit/homalg/test_module_facade.py:765 · validation/bench/macaulay2_core.py:8 · validation/bench/magma_release.py:1279 · validation/bench/magma_release.py:1292 · validation/bench/magma_release.py:1305

homalg.ModuleGroebnerBasis.to_json

Serialize this ModuleGroebnerBasis to its canonical typed JSON representation.

Detailed contract

Serialize the exact input, order, basis, transformation, and leaders.

PythonRust

(self) -> str

noether::homalg::ModuleGroebnerBasis::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/ModuleGroebnerBasis@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.ModuleGroebnerBasis.transformation

Return the transformation recorded by this ModuleGroebnerBasis.

Detailed contract

Map expressing every basis generator in the original generators.

PythonRust

(self) -> ModuleHomomorphism[_GroebnerModuleRing]

noether::homalg::ModuleGroebnerBasis::transformation · Direct Rust declaration

pub fn transformation(&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/ModuleGroebnerBasis@1

Executable usage: examples/04_smith_normal_form.py:3 · validation/unit/linalg/test_lattice_facade.py:172 · validation/unit/linalg/test_lattice_facade.py:173 · validation/unit/linalg/test_lattice_facade.py:179 · validation/bench/macaulay2_core.py:1372 · validation/corpus/linalg/picard-cremona-transformations.py:20

homalg.ModuleGroebnerBasis.verify

Replay and verify the mathematical evidence carried by this ModuleGroebnerBasis.

Detailed contract

Recheck normalization, change-map identities, input equivalence, and Buchberger’s criterion without trusting construction metadata. Independently reconstruct the lifted polynomial calculation and check the projected canonical basis and transformation.

PythonRust

(self) -> None

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

pub fn verify(&self) -> 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/ModuleGroebnerBasis@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