commalg · LocalIdeal

13 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.LocalIdeal

A canonical ideal in one polynomial localization.

PythonRust

class LocalIdeal

noether::commalg::LocalIdeal · Direct Rust declaration

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

Executable usage: validation/unit/commalg/test_local_algebra.py:70 · validation/unit/commalg/test_local_algebra.py:9

commalg.LocalIdeal.associated_graded

Compute associated graded for this LocalIdeal.

Detailed contract

Associated graded quotient of the local algebra by this ideal.

PythonRust

(self) -> QuotientRing[_ProjectedIdealFieldContext]

noether::commalg::LocalIdeal::associated_graded · Direct Rust declaration

pub fn associated_graded( &self, ) -> Result<QuotientRing<PolynomialRing<R>>, LocalAlgebraError>

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

Executable usage: validation/unit/commalg/test_local_algebra.py:66

commalg.LocalIdeal.contains

Compute contains for this LocalIdeal.

Detailed contract

Decide membership using a certified weak normal form.

PythonRust

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

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

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

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/LocalIdeal@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.LocalIdeal.dimension

Return the dimension recorded by this LocalIdeal.

Detailed contract

Krull dimension of the local quotient.

PythonRust

(self) -> int

noether::commalg::LocalIdeal::dimension · Direct Rust declaration

pub fn dimension(&self) -> Result<i64, LocalAlgebraError>

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/LocalIdeal@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

commalg.LocalIdeal.from_json

Deserialize and revalidate a LocalIdeal from typed JSON.

Detailed contract

Deserialize and exactly revalidate a local ideal.

PythonRust

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

noether::commalg::LocalIdeal::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, module-core, poly-core, resolution-kernel
GIL	attached / bounded
Semantic ID	noether/commalg/LocalIdeal@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.LocalIdeal.generators

Return the generators recorded by this LocalIdeal.

Detailed contract

Canonical Mora generators in translated coordinates.

PythonRust

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

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

pub fn generators(&self) -> &[Polynomial<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/LocalIdeal@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.LocalIdeal.multiplicity

Return the multiplicity recorded by this LocalIdeal.

Detailed contract

Hilbert–Samuel multiplicity of the local quotient.

PythonRust

(self) -> int

noether::commalg::LocalIdeal::multiplicity · Direct Rust declaration

pub fn multiplicity(&self) -> Result<Integer, LocalAlgebraError>

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

Executable usage: validation/unit/combin/test_acceptance_workload.py:64 · validation/unit/commalg/test_local_algebra.py:65 · validation/unit/commalg/test_local_algebra.py:82 · validation/unit/commalg/test_polynomial_facade.py:126 · validation/unit/commalg/test_polynomial_facade.py:158 · validation/unit/commalg/test_polynomial_facade.py:96

commalg.LocalIdeal.reduce

Compute reduce for this LocalIdeal.

Detailed contract

Certified weak normal form of one local element.

PythonRust

(self, value: LocalPolynomial[_ProjectedIdealFieldContext]) -> LocalReduction[_ProjectedIdealFieldContext]

noether::commalg::LocalIdeal::reduce · Direct Rust declaration

pub fn reduce( &self, value: &LocalPolynomial<R>, ) -> Result<LocalReduction<R>, LocalAlgebraError>

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/LocalIdeal@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

commalg.LocalIdeal.ring

Return the ring recorded by this LocalIdeal.

Detailed contract

Exact polynomial-localization context.

PythonRust

(self) -> LocalPolynomialRing[_ProjectedIdealFieldContext]

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

pub fn ring(&self) -> &LocalPolynomialRing<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/LocalIdeal@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.LocalIdeal.standard_basis

Compute standard basis for this LocalIdeal.

Detailed contract

Retained standard-basis evidence for this ideal.

PythonRust

(self) -> LocalStandardBasis[_ProjectedIdealFieldContext]

noether::commalg::LocalIdeal::standard_basis · Direct Rust declaration

pub fn standard_basis(&self) -> Result<LocalStandardBasis<R>, LocalAlgebraError>

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

Executable usage: validation/unit/commalg/test_local_algebra.py:55 · validation/unit/commalg/test_local_algebra.py:79

commalg.LocalIdeal.tangent_cone_ideal

Compute tangent cone ideal for this LocalIdeal.

Detailed contract

Tangent-cone ideal in the translated polynomial coordinates.

PythonRust

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

noether::commalg::LocalIdeal::tangent_cone_ideal · Direct Rust declaration

pub fn tangent_cone_ideal( &self, ) -> Result<Ideal<PolynomialRing<R>>, LocalAlgebraError>

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

Executable usage: validation/unit/commalg/test_local_algebra.py:83

commalg.LocalIdeal.to_json

Serialize this LocalIdeal to its canonical typed JSON representation.

Detailed contract

Serialize the exact local ideal.

PythonRust

(self) -> str

noether::commalg::LocalIdeal::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, module-core, poly-core, resolution-kernel
GIL	attached / bounded
Semantic ID	noether/commalg/LocalIdeal@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.LocalIdeal.verify

Replay and verify the mathematical evidence carried by this LocalIdeal.

Detailed contract

Recompute the canonical standard basis exactly.

PythonRust

(self) -> None

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

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

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/LocalIdeal@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