root · IntegerRing¶

12 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.

`IntegerRing`¶

The canonical Python context for the ring of integers.

PythonRust

class IntegerRing

noether::IntegerRing · Direct Rust declaration

pub struct IntegerRing;

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core
GIL	attached / bounded
Semantic ID	noether/root/IntegerRing@1

Executable usage: examples/38_exact_linear_systems.py:52 · examples/38_exact_linear_systems.py:7 · validation/unit/infra/test_discovery.py:29 · validation/unit/infra/test_public_api_index.py:154 · validation/unit/infra/test_public_api_index.py:262 · validation/unit/infra/test_public_api_index.py:83

`IntegerRing.call`¶

Coerce the supplied input through this context or mathematical map.

PythonRust

(self, value: int) -> int

noether::root::IntegerRing · Python projection

Python projection convenience over this Rust mathematical type

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core
GIL	attached / bounded
Semantic ID	noether/root/IntegerRing@1

Executable usage: validation/unit/infra/test_discovery.py:57 · validation/unit/infra/test_public_api_index.py:155 · validation/unit/infra/test_public_api_index.py:169

`IntegerRing.extended_gcd`¶

Return a normalized Bézout witness for two integers.

PythonRust

(self, left: int, right: int) -> BezoutIdentity[int]

noether::root::IntegerRing::extended_gcd · Direct Rust declaration

fn extended_gcd( &self, a: &Self::Element, b: &Self::Element, ) -> BezoutIdentity<Self>

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core
GIL	attached / bounded
Semantic ID	noether/root/IntegerRing@1

Executable usage: examples/01_bezout_certificates.py:9 · validation/unit/infra/test_public_api_index.py:154 · validation/unit/test_bezout_facade.py:22 · validation/unit/test_bezout_facade.py:41 · validation/unit/test_bezout_facade.py:49 · validation/unit/test_bezout_facade.py:53

`IntegerRing.finite_field_map`¶

Return the canonical unital map into one explicit finite field.

Detailed contract

Canonical unital map into one explicit finite field.

PythonRust

(self, target: FiniteField) -> IntegerFiniteFieldMap

noether::root::IntegerRing::finite_field_map · Direct Rust declaration

pub fn finite_field_map(&self, target: &FiniteField) -> IntegerFiniteFieldMap

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core
GIL	attached / bounded
Semantic ID	noether/root/IntegerRing@1

Executable usage: validation/unit/commalg/test_polynomial_homomorphism.py:22 · validation/unit/commalg/test_polynomial_homomorphism.py:31 · validation/unit/commalg/test_polynomial_homomorphism.py:46 · validation/unit/commalg/test_polynomial_homomorphism.py:70 · validation/unit/commalg/test_polynomial_homomorphism.py:76 · validation/unit/commalg/test_polynomial_homomorphism.py:82

`IntegerRing.from_json`¶

Deserialize and validate the singleton integer-ring context.

PythonRust

(cls, value: str) -> IntegerRing

noether::root::IntegerRing::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
GIL	attached / bounded
Semantic ID	noether/root/IntegerRing@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

`IntegerRing.gcd`¶

Return the nonnegative greatest common divisor.

PythonRust

(self, left: int, right: int) -> int

noether::root::IntegerRing::gcd · Direct Rust declaration

fn gcd(&self, a: &Self::Element, b: &Self::Element) -> Self::Element

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core
GIL	attached / bounded
Semantic ID	noether/root/IntegerRing@1

Executable usage: examples/01_bezout_certificates.py:12 · validation/unit/commalg/test_polynomial_facade.py:385 · validation/unit/commalg/test_polynomial_facade.py:452 · validation/unit/commalg/test_polynomial_facade.py:469 · validation/unit/commalg/test_polynomial_facade.py:474 · validation/unit/commalg/test_polynomial_facade.py:498

`IntegerRing.ideal`¶

Construct the canonical principal ideal generated by integers.

Detailed contract

Construct the canonical principal ideal generated by the supplied integers. The empty family and an all-zero family both give (0).

PythonRust

(self, generators: Iterable[int]) -> Ideal[IntegerRing]

noether::root::IntegerRing::ideal · Direct Rust declaration

pub fn ideal<I>(&self, generators: I) -> Ideal<IntegerRing>where I: IntoIterator<Item = Integer>,

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core
GIL	attached / bounded
Semantic ID	noether/root/IntegerRing@1

Executable usage: examples/12_number_field_ideals.py:17 · examples/12_number_field_ideals.py:18 · examples/12_number_field_ideals.py:19 · examples/12_number_field_ideals.py:3 · examples/15_groebner_twisted_cubic.py:12 · examples/15_groebner_twisted_cubic.py:13

`IntegerRing.one`¶

Compute one for this IntegerRing.

PythonRust

(self) -> int

noether::root::IntegerRing::one · Direct Rust declaration

fn one(&self) -> Self::Element

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core
GIL	attached / bounded
Semantic ID	noether/root/IntegerRing@1

Executable usage: examples/02_ball_arithmetic.py:13 · examples/11_qadic_witt_vectors.py:11 · examples/24_homology_and_persistence.py:3 · examples/31_local_fields_and_precision.py:27 · validation/unit/combinatorics/test_poset.py:3 · validation/unit/commalg/test_acceptance_workload.py:37

`IntegerRing.rational_embedding`¶

Return the canonical unital embedding Z -> Q.

Detailed contract

The canonical unital embedding Z -> Q.

PythonRust

(self) -> IntegerRationalEmbedding

noether::root::IntegerRing::rational_embedding · Direct Rust declaration

pub const fn rational_embedding(&self) -> IntegerRationalEmbedding

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core
GIL	attached / bounded
Semantic ID	noether/root/IntegerRing@1

Executable usage: validation/unit/commalg/test_base_change.py:27 · validation/unit/commalg/test_polynomial_homomorphism.py:93 · validation/unit/commalg/test_polynomial_ideal_facade.py:301 · validation/unit/commalg/test_polynomial_ideal_facade.py:302 · validation/unit/test_coefficient_maps.py:24 · validation/unit/test_coefficient_maps.py:64

`IntegerRing.reduction`¶

Return canonical reduction into one explicit residue ring.

Detailed contract

Canonical reduction into one explicit residue ring.

PythonRust

(self, target: ResidueRing) -> IntegerReduction

noether::root::IntegerRing::reduction · Direct Rust declaration

pub fn reduction(&self, target: &ResidueRing) -> IntegerReduction

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core
GIL	attached / bounded
Semantic ID	noether/root/IntegerRing@1

Executable usage: examples/30_modules_and_resolutions.py:28 · examples/30_modules_and_resolutions.py:30 · examples/30_modules_and_resolutions.py:31 · validation/unit/combinatorics/test_poset.py:101 · validation/unit/combinatorics/test_poset.py:102 · validation/unit/combinatorics/test_poset.py:103

`IntegerRing.to_json`¶

Serialize the singleton integer-ring context as canonical typed JSON.

PythonRust

(self) -> str

noether::root::IntegerRing::to_json · Direct Rust declaration

pub fn to_json(self) -> Result<String, NoetherError>

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core
GIL	attached / bounded
Semantic ID	noether/root/IntegerRing@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

`IntegerRing.zero`¶

Compute zero for this IntegerRing.

PythonRust

(self) -> int

noether::root::IntegerRing::zero · Direct Rust declaration

fn zero(&self) -> Self::Element

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core
GIL	attached / bounded
Semantic ID	noether/root/IntegerRing@1

Executable usage: examples/08_finite_field_extensions.py:11 · examples/10_padic_hensel_lifting.py:15 · examples/40_exterior_algebra.py:26 · examples/distributed/f2_linear_algebra.py:28 · examples/distributed/f2_linear_algebra.py:29 · examples/distributed/f2_linear_algebra.py:30

root · IntegerRing¶

Worked example¶

IntegerRing¶

IntegerRing.__call__¶

IntegerRing.extended_gcd¶

IntegerRing.finite_field_map¶

IntegerRing.from_json¶

IntegerRing.gcd¶

IntegerRing.ideal¶

IntegerRing.one¶

IntegerRing.rational_embedding¶

IntegerRing.reduction¶

IntegerRing.to_json¶

IntegerRing.zero¶

`IntegerRing`¶

`IntegerRing.call`¶

`IntegerRing.extended_gcd`¶

`IntegerRing.finite_field_map`¶

`IntegerRing.from_json`¶

`IntegerRing.gcd`¶

`IntegerRing.ideal`¶

`IntegerRing.one`¶

`IntegerRing.rational_embedding`¶

`IntegerRing.reduction`¶

`IntegerRing.to_json`¶

`IntegerRing.zero`¶