commalg · PolynomialPrimeLocalIdeal

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

Worked example

The complete checked program Exact affine systems and canonical submodules over Z and Z/nZ uses this API directly.

# SPDX-License-Identifier: MIT
# Copyright (c) 2026 Benjamin Antieau and Deven Manam
"""Exact affine systems and canonical submodules over Z and Z/nZ."""

from __future__ import annotations

from noether import IntegerRing, Z
from noether.commalg import ResidueRing
from noether.homalg import FreeModule, ModuleElement, ModuleHomomorphism, Submodule
from noether.linalg import Matrix, Vector

operator = Matrix.from_rows(Z, [[2, 4, 0], [0, 0, 3]])
right_hand_side = Vector.from_values(Z, [6, 9])
integer_result = operator.solve_exact(right_hand_side)
assert integer_result.is_consistent
integer_solutions = integer_result.solutions
assert integer_solutions is not None
assert operator @ integer_solutions.particular_solution == right_hand_side
assert operator @ integer_solutions.homogeneous_generators == Matrix.zeros(Z, (2, 1))
integer_result.verify()

# Empty systems retain a replayable divisibility obstruction.
impossible = Matrix.from_rows(Z, [[6]]).solve_exact(Vector.from_values(Z, [9]))
assert not impossible.is_consistent
assert impossible.obstruction is not None
assert impossible.obstruction.left_gcd == 6
assert abs(impossible.obstruction.combined_rhs) == 9
impossible.obstruction.verify()

# Composite moduli are not treated as fields.  The result is an affine module,
# including all homogeneous torsion directions.
z12 = ResidueRing(12)
congruence = Matrix.from_rows(z12, [[8]]).solve_exact(Vector.from_values(z12, [4]))
assert congruence.is_consistent
congruence_solutions = congruence.solutions
assert congruence_solutions is not None
assert {
    (int(congruence_solutions.particular_solution[0]) + 3 * offset) % 12 for offset in range(4)
} == {
    2,
    5,
    8,
    11,
}
congruence.verify()

# Submodules retain a canonical normal form, so equality and lattice operations
# compare mathematics rather than the supplied generating lists.
ambient = FreeModule(Z, 2)


def element(x: int, y: int) -> ModuleElement[IntegerRing]:
    return ModuleElement(ambient, Vector.from_values(Z, [x, y]))


lattice = Submodule.from_generators(ambient, [element(2, 0), element(0, 3)])
assert lattice.finite_index() == 6
witness = lattice.membership_witness(element(6, 9))
assert witness is not None
witness.verify()
assert lattice.saturation().finite_index() == 1

homomorphism = ModuleHomomorphism(
    FreeModule(Z, 3),
    ambient,
    operator,
)
kernel_result = homomorphism.kernel()
image_result = homomorphism.image()
kernel = kernel_result.submodule
image = image_result.submodule
assert kernel.generator_count == 1
assert image.contains(element(2, 0))
kernel_result.verify()
image_result.verify()

print(
    "exact systems: integer affine rank 1; four Z/12Z solutions; "
    "index-6 lattice saturated and verified"
)

Run it with .venv/bin/python examples/38_exact_linear_systems.py.

commalg.PolynomialPrimeLocalIdeal

A canonical finitely generated ideal in a polynomial prime localization.

PythonRust

class PolynomialPrimeLocalIdeal

noether::commalg::PolynomialPrimeLocalIdeal · Direct Rust declaration

pub struct PolynomialPrimeLocalIdeal<R: Field> { /* private fields */ }

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core, groebner-kernel, module-core, poly-core, resolution-kernel
GIL	attached / bounded
Semantic ID	noether/commalg/PolynomialPrimeLocalIdeal@1

Executable usage: validation/unit/commalg/test_prime_localization.py:57 · validation/unit/commalg/test_prime_localization.py:9

commalg.PolynomialPrimeLocalIdeal.ambient_ideal

Return the ambient ideal recorded by this PolynomialPrimeLocalIdeal.

Detailed contract

Canonical ambient numerator ideal.

PythonRust

(self) -> Ideal[PolynomialRing[_ProjectedIdealFieldContext]]

noether::commalg::PolynomialPrimeLocalIdeal::ambient_ideal · Direct Rust declaration

pub fn ambient_ideal(&self) -> &Ideal<PolynomialRing<R>>

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core, groebner-kernel, module-core, poly-core, resolution-kernel
GIL	attached / bounded
Semantic ID	noether/commalg/PolynomialPrimeLocalIdeal@1

commalg.PolynomialPrimeLocalIdeal.certify_membership

Compute certify membership for this PolynomialPrimeLocalIdeal.

Detailed contract

Certify membership by the exact colon criterion. For value = f/d, membership is equivalent to (ambient_ideal : f) not being contained in the localization prime. The first canonical colon generator outside the prime is retained as the unit multiplier in a replayable local linear-combination identity.

PythonRust

(self, value: PolynomialPrimeLocalElement[_ProjectedIdealFieldContext]) -> PolynomialPrimeLocalMembership[_ProjectedIdealFieldContext]

noether::commalg::PolynomialPrimeLocalIdeal::certify_membership · Direct Rust declaration

pub fn certify_membership( &self, value: &PolynomialPrimeLocalElement<R>, ) -> Result<PolynomialPrimeLocalMembership<R>, PrimeLocalizationError>

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core, groebner-kernel, module-core, poly-core, resolution-kernel
GIL	attached / bounded
Semantic ID	noether/commalg/PolynomialPrimeLocalIdeal@1

Executable usage: validation/unit/commalg/test_prime_localization.py:42 · validation/unit/commalg/test_prime_localization.py:43

commalg.PolynomialPrimeLocalIdeal.contains

Compute contains for this PolynomialPrimeLocalIdeal.

Detailed contract

Decide exact membership in this localized ideal.

PythonRust

(self, value: PolynomialPrimeLocalElement[_ProjectedIdealFieldContext]) -> bool

noether::commalg::PolynomialPrimeLocalIdeal::contains · Direct Rust declaration

pub fn contains( &self, value: &PolynomialPrimeLocalElement<R>, ) -> Result<bool, PrimeLocalizationError>

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

commalg.PolynomialPrimeLocalIdeal.from_json

Deserialize and revalidate a PolynomialPrimeLocalIdeal from typed JSON.

Detailed contract

Deserialize and independently revalidate a prime-local ideal.

PythonRust

(cls, value: str) -> PolynomialPrimeLocalIdeal[CoefficientRing]

noether::commalg::PolynomialPrimeLocalIdeal::from_json · Direct Rust declaration

pub fn from_json(value: &str) -> Result<Self, NoetherError>

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

commalg.PolynomialPrimeLocalIdeal.generators

Return the generators recorded by this PolynomialPrimeLocalIdeal.

Detailed contract

Canonical local generators, each with denominator one.

PythonRust

(self) -> list[PolynomialPrimeLocalElement[_ProjectedIdealFieldContext]]

noether::commalg::PolynomialPrimeLocalIdeal::generators · Direct Rust declaration

pub fn generators( &self, ) -> Result<Vec<PolynomialPrimeLocalElement<R>>, PrimeLocalizationError>

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core, groebner-kernel, module-core, poly-core, resolution-kernel
GIL	attached / bounded
Semantic ID	noether/commalg/PolynomialPrimeLocalIdeal@1

Executable usage: examples/14_weighted_polynomials.py:11 · examples/15_groebner_twisted_cubic.py:11 · examples/15_groebner_twisted_cubic.py:19 · examples/17_weighted_power_series.py:15 · examples/18_finite_field_schemes.py:12 · examples/30_modules_and_resolutions.py:20

commalg.PolynomialPrimeLocalIdeal.ring

Return the ring recorded by this PolynomialPrimeLocalIdeal.

Detailed contract

Exact prime-local coefficient context.

PythonRust

(self) -> PolynomialPrimeLocalization[_ProjectedIdealFieldContext]

noether::commalg::PolynomialPrimeLocalIdeal::ring · Direct Rust declaration

pub fn ring(&self) -> &PolynomialPrimeLocalization<R>

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core, groebner-kernel, module-core, poly-core, resolution-kernel
GIL	attached / bounded
Semantic ID	noether/commalg/PolynomialPrimeLocalIdeal@1

Executable usage: examples/11_qadic_witt_vectors.py:3 · examples/13_chinese_remainder_theorem.py:10 · examples/13_chinese_remainder_theorem.py:12 · examples/13_chinese_remainder_theorem.py:9 · examples/14_weighted_polynomials.py:10 · examples/14_weighted_polynomials.py:11

commalg.PolynomialPrimeLocalIdeal.to_json

Serialize this PolynomialPrimeLocalIdeal to its canonical typed JSON representation.

Detailed contract

Serialize the canonical local ideal.

PythonRust

(self) -> str

noether::commalg::PolynomialPrimeLocalIdeal::to_json · Direct Rust declaration

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

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

commalg.PolynomialPrimeLocalIdeal.verify

Replay and verify the mathematical evidence carried by this PolynomialPrimeLocalIdeal.

Detailed contract

Recompute the canonical numerator ideal.

PythonRust

(self) -> None

noether::commalg::PolynomialPrimeLocalIdeal::verify · Direct Rust declaration

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

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