Skip to content

linalg · SmithNormalForm

8 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.SmithNormalForm

Smith normal form of an integer matrix without transformation matrices.

class SmithNormalForm

noether::linalg::SmithNormalForm · Direct Rust declaration

pub struct SmithNormalForm { /* 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/SmithNormalForm@1

Executable usage: validation/unit/infra/test_discovery.py:19 · validation/unit/infra/test_public_api_index.py:83 · validation/unit/infra/test_public_api_index.py:84 · validation/unit/infra/test_public_api_index.py:98 · validation/unit/linalg/test_exact_linear_algebra_facade.py:27 · validation/unit/linalg/test_exact_linear_algebra_facade.py:310

linalg.SmithNormalForm.form

Diagonal Smith form with the same shape as the input.

Detailed contract

The diagonal Smith form, with the same shape as the input matrix.

(self) -> Matrix[IntegerRing]

noether::linalg::SmithNormalForm::form · Direct Rust declaration

pub fn form(&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/SmithNormalForm@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.SmithNormalForm.invariant_factors

Positive nonzero invariant factors in divisibility-chain order.

Detailed contract

Nonzero diagonal entries in positive divisibility-chain order.

(self) -> list[int]

noether::linalg::SmithNormalForm::invariant_factors · Direct Rust declaration

pub fn invariant_factors(&self) -> &[Integer]
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/SmithNormalForm@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.SmithNormalForm.rank

Rank over the integers.

Detailed contract

Rank of the input over the integers (equivalently over the rationals).

(self) -> int

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

Input matrix retained as the verification witness.

Detailed contract

The input matrix retained as the result’s verification witness.

(self) -> Matrix[IntegerRing]

noether::linalg::SmithNormalForm::source · Direct Rust declaration

pub fn source(&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/SmithNormalForm@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.SmithNormalForm.validity

Mathematical assumptions under which the result is valid.

Detailed contract

Mathematical assumptions under which this result is valid.

(self) -> MathematicalValidity

noether::linalg::SmithNormalForm::validity · Direct Rust declaration

pub fn validity(&self) -> &MathematicalValidity
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/SmithNormalForm@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.SmithNormalForm.verification

Strategy-specific checks supporting the result.

(self) -> SmithVerification

noether::linalg::SmithNormalForm::verification · Direct Rust declaration

pub fn verification(&self) -> &SmithVerification
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/SmithNormalForm@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.SmithNormalForm.verify

Recheck the Smith conventions and retained input witness.

Detailed contract

Recheck the diagonal conventions and recompute the form from the source.

(self) -> None

noether::linalg::SmithNormalForm::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/SmithNormalForm@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