linalg · DistributedPLUQFactorization¶
7 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.
linalg.DistributedPLUQFactorization¶
Owned distributed PLUQ decomposition with convention P L U Q = A.
noether::linalg::DistributedPLUQFactorization · Python projection
| Contract | Value |
|---|---|
| Guarantee | checked deterministic result |
| Determinism | deterministic |
| Availability | MPI-enabled build (distributed feature) |
| Domain implementation crates | noether, flint-core, m4rst, m4rst-distributed, m4rste, mzs, pwvla, spar-core, sparla, sparb, lattice-enum |
| GIL | attached / bounded |
linalg.DistributedPLUQFactorization.l¶
Return the l recorded by this DistributedPLUQFactorization.
noether::linalg::DistributedPLUQFactorization · Python projection
| Contract | Value |
|---|---|
| Guarantee | checked deterministic result |
| Determinism | deterministic |
| Availability | MPI-enabled build (distributed feature) |
| Domain implementation crates | noether, flint-core, m4rst, m4rst-distributed, m4rste, mzs, pwvla, spar-core, sparla, sparb, lattice-enum |
| GIL | attached / bounded |
Executable usage: validation/unit/linalg/test_exact_linear_algebra_facade.py:47 · validation/unit/linalg/test_exact_linear_algebra_facade.py:50
linalg.DistributedPLUQFactorization.p¶
Return the p recorded by this DistributedPLUQFactorization.
noether::linalg::DistributedPLUQFactorization · Python projection
| Contract | Value |
|---|---|
| Guarantee | checked deterministic result |
| Determinism | deterministic |
| Availability | MPI-enabled build (distributed feature) |
| Domain implementation crates | noether, flint-core, m4rst, m4rst-distributed, m4rste, mzs, pwvla, spar-core, sparla, sparb, lattice-enum |
| GIL | attached / bounded |
Executable usage: validation/unit/combinatorics/test_boundary.py:21 · validation/unit/combinatorics/test_boundary.py:22 · validation/unit/combinatorics/test_boundary.py:23 · validation/unit/combinatorics/test_partition_types.py:63 · validation/unit/combinatorics/test_partition_types.py:64 · validation/unit/infra/test_docs_site_generator.py:103
linalg.DistributedPLUQFactorization.q¶
Return the q recorded by this DistributedPLUQFactorization.
noether::linalg::DistributedPLUQFactorization · Python projection
| Contract | Value |
|---|---|
| Guarantee | checked deterministic result |
| Determinism | deterministic |
| Availability | MPI-enabled build (distributed feature) |
| Domain implementation crates | noether, flint-core, m4rst, m4rst-distributed, m4rste, mzs, pwvla, spar-core, sparla, sparb, lattice-enum |
| GIL | attached / bounded |
Executable usage: validation/unit/infra/test_macaulay2_benchmark_protocol.py:1005 · validation/unit/infra/test_macaulay2_benchmark_protocol.py:1041 · validation/unit/infra/test_macaulay2_benchmark_protocol.py:1068 · validation/unit/infra/test_macaulay2_benchmark_protocol.py:1090 · validation/unit/infra/test_macaulay2_benchmark_protocol.py:181 · validation/unit/infra/test_macaulay2_benchmark_protocol.py:226
linalg.DistributedPLUQFactorization.rank¶
Return the rank recorded by this DistributedPLUQFactorization.
noether::linalg::DistributedPLUQFactorization · Python projection
| Contract | Value |
|---|---|
| Guarantee | checked deterministic result |
| Determinism | deterministic |
| Availability | MPI-enabled build (distributed feature) |
| Domain implementation crates | noether, flint-core, m4rst, m4rst-distributed, m4rste, mzs, pwvla, spar-core, sparla, sparb, lattice-enum |
| GIL | attached / bounded |
Executable usage: examples/38_exact_linear_systems.py:78 · examples/distributed/f2_linear_algebra.py:34 · examples/distributed/f2_linear_algebra.py:54 · examples/distributed/f2_linear_algebra.py:55 · examples/distributed/f2_linear_algebra.py:60 · validation/unit/combin/test_acceptance_workload.py:74
linalg.DistributedPLUQFactorization.u¶
Return the u recorded by this DistributedPLUQFactorization.
noether::linalg::DistributedPLUQFactorization · Python projection
| Contract | Value |
|---|---|
| Guarantee | checked deterministic result |
| Determinism | deterministic |
| Availability | MPI-enabled build (distributed feature) |
| Domain implementation crates | noether, flint-core, m4rst, m4rst-distributed, m4rste, mzs, pwvla, spar-core, sparla, sparb, lattice-enum |
| GIL | attached / bounded |
Executable usage: validation/unit/commalg/test_affine_normalization_facade.py:151 · validation/unit/commalg/test_affine_normalization_facade.py:152 · validation/unit/commalg/test_affine_normalization_facade.py:153 · validation/unit/commalg/test_affine_normalization_facade.py:156 · validation/unit/commalg/test_base_change.py:116 · validation/unit/commalg/test_base_change.py:117
linalg.DistributedPLUQFactorization.verify¶
Replay and verify the mathematical evidence carried by this DistributedPLUQFactorization.
noether::linalg::DistributedPLUQFactorization · Python projection
| Contract | Value |
|---|---|
| Guarantee | checked deterministic result |
| Determinism | deterministic |
| Availability | MPI-enabled build (distributed feature) |
| Domain implementation crates | noether, flint-core, m4rst, m4rst-distributed, m4rste, mzs, pwvla, spar-core, sparla, sparb, lattice-enum |
| GIL | released |
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