linalg · SmithNormalFormWithTransforms

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

Worked example

The complete checked program Compute a fast Smith form without transformation matrices uses this API directly.

# SPDX-License-Identifier: MIT
# Copyright (c) 2026 Benjamin Antieau and Deven Manam
"""Compute a fast Smith form without transformation matrices."""

from noether import Z
from noether.linalg import Matrix


def main() -> None:
    matrix = Matrix.from_rows(Z, [[2, 4, 4], [6, 6, 12], [10, 4, 16]])
    smith = matrix.smith_normal_form()
    smith.verify()
    assert all(
        right % left == 0
        for left, right in zip(smith.invariant_factors, smith.invariant_factors[1:])
    )
    print(f"invariant factors: {smith.invariant_factors}")


if __name__ == "__main__":
    main()

Run it with .venv/bin/python examples/04_smith_normal_form.py.

linalg.SmithNormalFormWithTransforms

Smith normal form with explicit left and right unimodular witnesses.

PythonRust

class SmithNormalFormWithTransforms

noether::linalg::SmithNormalFormWithTransforms · Direct Rust declaration

pub struct SmithNormalFormWithTransforms { /* private fields */ }

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core, m4rst, m4rst-distributed, m4rste, mzs, pwvla, spar-core, sparla, sparb, lattice-enum
GIL	attached / bounded
Semantic ID	noether/linalg/SmithNormalFormWithTransforms@1

Executable usage: validation/unit/infra/test_discovery.py:23 · validation/unit/linalg/test_exact_linear_algebra_facade.py:28 · validation/unit/linalg/test_exact_linear_algebra_facade.py:410 · validation/unit/linalg/test_exact_linear_algebra_facade.py:411 · validation/unit/linalg/test_exact_linear_algebra_facade.py:422

linalg.SmithNormalFormWithTransforms.form

Diagonal Smith form with the same shape as the input.

PythonRust

(self) -> Matrix[IntegerRing]

noether::linalg::SmithNormalFormWithTransforms · 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, m4rst, m4rst-distributed, m4rste, mzs, pwvla, spar-core, sparla, sparb, lattice-enum
GIL	attached / bounded
Semantic ID	noether/linalg/SmithNormalFormWithTransforms@1

Executable usage: examples/04_smith_normal_form.py:3 · validation/unit/commalg/test_intersection_theory.py:100 · validation/unit/homalg/test_acceptance_workload.py:63 · validation/unit/homalg/test_padic_homology_facade.py:138 · validation/unit/homalg/test_padic_homology_facade.py:216 · validation/unit/infra/test_discovery.py:20

linalg.SmithNormalFormWithTransforms.invariant_factors

Positive nonzero invariant factors in divisibility-chain order.

PythonRust

(self) -> list[int]

noether::linalg::SmithNormalFormWithTransforms · 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, m4rst, m4rst-distributed, m4rste, mzs, pwvla, spar-core, sparla, sparb, lattice-enum
GIL	attached / bounded
Semantic ID	noether/linalg/SmithNormalFormWithTransforms@1

Executable usage: examples/04_smith_normal_form.py:15 · examples/04_smith_normal_form.py:17 · validation/unit/homalg/test_finite_group_cohomology.py:112 · validation/unit/homalg/test_finite_group_cohomology.py:37 · validation/unit/infra/test_repr_protocol.py:86 · validation/unit/infra/test_repr_protocol.py:88

linalg.SmithNormalFormWithTransforms.left

Left unimodular matrix in left @ source @ right == form.

Detailed contract

The left unimodular matrix.

PythonRust

(self) -> Matrix[IntegerRing]

noether::linalg::SmithNormalFormWithTransforms::left · Direct Rust declaration

pub fn left(&self) -> &Matrix<IntegerRing>

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core, m4rst, m4rst-distributed, m4rste, mzs, pwvla, spar-core, sparla, sparb, lattice-enum
GIL	attached / bounded
Semantic ID	noether/linalg/SmithNormalFormWithTransforms@1

Executable usage: examples/04_smith_normal_form.py:14 · examples/04_smith_normal_form.py:15 · validation/unit/combin/test_acceptance_workload.py:101 · validation/unit/combin/test_acceptance_workload.py:98 · validation/unit/commalg/test_groebner_verification_budget.py:30 · validation/unit/commalg/test_groebner_verification_budget.py:31

linalg.SmithNormalFormWithTransforms.rank

Rank over the integers.

PythonRust

(self) -> int

noether::linalg::SmithNormalFormWithTransforms · 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, m4rst, m4rst-distributed, m4rste, mzs, pwvla, spar-core, sparla, sparb, lattice-enum
GIL	attached / bounded
Semantic ID	noether/linalg/SmithNormalFormWithTransforms@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

linalg.SmithNormalFormWithTransforms.right

Right unimodular matrix in left @ source @ right == form.

Detailed contract

The right unimodular matrix.

PythonRust

(self) -> Matrix[IntegerRing]

noether::linalg::SmithNormalFormWithTransforms::right · Direct Rust declaration

pub fn right(&self) -> &Matrix<IntegerRing>

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core, m4rst, m4rst-distributed, m4rste, mzs, pwvla, spar-core, sparla, sparb, lattice-enum
GIL	attached / bounded
Semantic ID	noether/linalg/SmithNormalFormWithTransforms@1

Executable usage: examples/04_smith_normal_form.py:14 · examples/04_smith_normal_form.py:15 · validation/unit/combin/test_acceptance_workload.py:101 · validation/unit/combin/test_acceptance_workload.py:98 · validation/unit/commalg/test_groebner_verification_budget.py:31 · validation/unit/commalg/test_groebner_verification_budget.py:34

linalg.SmithNormalFormWithTransforms.smith

The Smith result shared with the fast no-transform endpoint.

PythonRust

(self) -> SmithNormalForm

noether::linalg::SmithNormalFormWithTransforms::smith · Direct Rust declaration

pub fn smith(&self) -> &SmithNormalForm

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core, m4rst, m4rst-distributed, m4rste, mzs, pwvla, spar-core, sparla, sparb, lattice-enum
GIL	attached / bounded
Semantic ID	noether/linalg/SmithNormalFormWithTransforms@1

Executable usage: examples/04_smith_normal_form.py:11 · examples/04_smith_normal_form.py:12 · examples/04_smith_normal_form.py:15 · examples/04_smith_normal_form.py:17 · validation/unit/infra/test_discovery.py:74 · validation/unit/infra/test_discovery.py:76

linalg.SmithNormalFormWithTransforms.source

Input matrix retained as the verification witness.

PythonRust

(self) -> Matrix[IntegerRing]

noether::linalg::SmithNormalFormWithTransforms · 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, m4rst, m4rst-distributed, m4rste, mzs, pwvla, spar-core, sparla, sparb, lattice-enum
GIL	attached / bounded
Semantic ID	noether/linalg/SmithNormalFormWithTransforms@1

Executable usage: examples/09_finite_field_isomorphisms.py:11 · examples/09_finite_field_isomorphisms.py:13 · examples/09_finite_field_isomorphisms.py:9 · examples/30_modules_and_resolutions.py:34 · examples/30_modules_and_resolutions.py:37 · validation/unit/category/test_acceptance_workload.py:25

linalg.SmithNormalFormWithTransforms.validity

Mathematical assumptions under which the result is valid.

PythonRust

(self) -> MathematicalValidity

noether::linalg::SmithNormalFormWithTransforms · 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, m4rst, m4rst-distributed, m4rste, mzs, pwvla, spar-core, sparla, sparb, lattice-enum
GIL	attached / bounded
Semantic ID	noether/linalg/SmithNormalFormWithTransforms@1

Executable usage: validation/unit/commalg/test_intersection_theory.py:48 · validation/unit/commalg/test_intersection_theory.py:83 · validation/unit/homalg/test_chain_complex.py:42 · validation/unit/homalg/test_padic_homology_facade.py:157 · validation/unit/homalg/test_padic_homology_facade.py:168 · validation/unit/homalg/test_padic_homology_facade.py:172

linalg.SmithNormalFormWithTransforms.verification

Strategy-specific checks supporting the Smith result.

PythonRust

(self) -> SmithVerification

noether::linalg::SmithNormalFormWithTransforms · 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, m4rst, m4rst-distributed, m4rste, mzs, pwvla, spar-core, sparla, sparb, lattice-enum
GIL	attached / bounded
Semantic ID	noether/linalg/SmithNormalFormWithTransforms@1

Executable usage: validation/unit/commalg/test_groebner_verification_budget.py:3 · validation/unit/infra/test_mpi_scale_report.py:291 · validation/unit/infra/test_mpi_scale_report.py:311 · validation/unit/infra/test_slurm_handoff.py:129 · validation/unit/infra/test_slurm_handoff.py:587 · validation/unit/linalg/test_acceptance_workload.py:139

linalg.SmithNormalFormWithTransforms.verify

Verify canonical form, unimodularity, and the reconstruction identity.

PythonRust

(self) -> None

noether::linalg::SmithNormalFormWithTransforms::verify · Direct Rust declaration

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

Contract	Value
Guarantee	checked deterministic result
Determinism	deterministic
Availability	default CPU build
Domain implementation crates	noether, flint-core, m4rst, m4rst-distributed, m4rste, mzs, pwvla, spar-core, sparla, sparb, lattice-enum
GIL	attached / bounded
Semantic ID	noether/linalg/SmithNormalFormWithTransforms@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