groups · WeightLattice

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.

groups.WeightLattice

A free weight lattice with a named basis and an explicit basis convention.

PythonRust

WeightLattice(basis_names: Sequence[str])

noether::groups::WeightLattice · Direct Rust declaration

pub struct WeightLattice { /* private fields */ }

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

Executable usage: validation/unit/groups/test_weight_characters.py:34 · validation/unit/groups/test_weight_characters.py:35 · validation/unit/groups/test_weight_characters.py:9

groups.WeightLattice.__eq__

Test mathematical equality with another value.

PythonRust

(self, other: object) -> bool

noether::groups::WeightLattice · 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, perm-core
GIL	attached / bounded
Semantic ID	noether/groups/WeightLattice@1

groups.WeightLattice.basis_convention

Return the basis convention recorded by this WeightLattice.

PythonRust

(self) -> WeightBasisConvention

noether::groups::WeightLattice · 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, perm-core
GIL	attached / bounded
Semantic ID	noether/groups/WeightLattice@1

groups.WeightLattice.basis_names

Return the basis names recorded by this WeightLattice.

Detailed contract

Ordered basis labels used by Chern polynomial contexts.

PythonRust

(self) -> list[str]

noether::groups::WeightLattice::basis_names · Direct Rust declaration

pub fn basis_names(&self) -> &[String]

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

groups.WeightLattice.from_json

Deserialize and revalidate a WeightLattice from typed JSON.

Detailed contract

Deserialize and revalidate the complete basis context.

PythonRust

(value: str) -> WeightLattice

noether::groups::WeightLattice::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, perm-core
GIL	attached / bounded
Semantic ID	noether/groups/WeightLattice@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

groups.WeightLattice.homomorphism

Compute homomorphism for this WeightLattice.

Detailed contract

Construct and check a homomorphism out of this lattice.

PythonRust

(self, target: WeightLattice, basis_images: Sequence[Weight]) -> WeightLatticeMap

noether::groups::WeightLattice::homomorphism · Direct Rust declaration

pub fn homomorphism( &self, target: WeightLattice, basis_images: Vec<Vec<Integer>>, ) -> Result<WeightLatticeMap, RepresentationError>

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

Executable usage: examples/38_exact_linear_systems.py:63 · examples/38_exact_linear_systems.py:68 · examples/38_exact_linear_systems.py:69 · validation/unit/commalg/test_base_change.py:118 · validation/unit/commalg/test_base_change.py:123 · validation/unit/commalg/test_base_change.py:124

groups.WeightLattice.identity_map

Compute identity map for this WeightLattice.

Detailed contract

Identity lattice map.

PythonRust

(self) -> WeightLatticeMap

noether::groups::WeightLattice::identity_map · Direct Rust declaration

pub fn identity_map(&self) -> WeightLatticeMap

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

Executable usage: validation/unit/groups/test_weight_characters.py:40

groups.WeightLattice.rank

Return the rank recorded by this WeightLattice.

Detailed contract

Lattice rank.

PythonRust

(self) -> int

noether::groups::WeightLattice::rank · Direct Rust declaration

pub fn rank(&self) -> usize

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

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

groups.WeightLattice.standard

Construct a WeightLattice using standard.

Detailed contract

Canonical rank-rank standard lattice with basis x1,...,xrank.

PythonRust

(rank: int) -> WeightLattice

noether::groups::WeightLattice::standard · Direct Rust declaration

pub fn standard(rank: usize) -> Result<Self, RepresentationError>

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

Executable usage: validation/unit/commalg/test_monomial_ideal_facade.py:57 · validation/unit/commalg/test_polynomial_facade.py:34 · validation/unit/commalg/test_polynomial_facade.py:42 · validation/unit/commalg/test_polynomial_facade.py:43 · validation/unit/commalg/test_polynomial_facade.py:44 · validation/unit/commalg/test_polynomial_facade.py:45

groups.WeightLattice.to_json

Serialize this WeightLattice to its canonical typed JSON representation.

Detailed contract

Serialize the complete basis context.

PythonRust

(self) -> str

noether::groups::WeightLattice::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, perm-core
GIL	attached / bounded
Semantic ID	noether/groups/WeightLattice@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

groups.WeightLattice.type_a

Construct a WeightLattice using type a.

Detailed contract

Fundamental-weight lattice for SL_n, with basis alpha1,...,alpha(n-1).

PythonRust

(n: int) -> WeightLattice

noether::groups::WeightLattice::type_a · Direct Rust declaration

pub fn type_a(n: usize) -> Result<Self, RepresentationError>

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

Executable usage: validation/unit/groups/test_weight_characters.py:35

groups.WeightLattice.type_a_degree

Return the type a degree recorded by this WeightLattice.

PythonRust

(self) -> int | None

noether::groups::WeightLattice · 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, perm-core
GIL	attached / bounded
Semantic ID	noether/groups/WeightLattice@1