Integer Matrix API¶

Functions for computing SNF, HNF, and elementary divisors of integer matrices.

All functions accept a DenseIntMatrix, SparseIntMatrix, or a plain dict conforming to either schema. See Input Formats for details.

Functions¶

snforacle.interface.smith_normal_form ¶

smith_normal_form(
    matrix: Any, backend: _IntBackend | None = None
) -> SNFResult

Compute the Smith normal form of an integer matrix.

Parameters:

Name	Type	Description	Default
`matrix`	`Any`	The input matrix as a `DenseIntMatrix`, `SparseIntMatrix`, or a plain `dict` conforming to one of those schemas.	required
`backend`	`_IntBackend \| None`	Name of the backend to use: `"cypari2"`, `"flint"`, `"sage"`, `"magma"`, or `"pure_python"`. Defaults to the best available.	`None`

Returns:

Type	Description
`SNFResult`	A Pydantic model with fields: `smith_normal_form` The m×n SNF matrix as a `DenseIntMatrix`. The diagonal entries d₁ \| d₂ \| … \| dᵣ are in non-decreasing order; all other entries are zero. `invariant_factors` The sequence `[d₁, …, dᵣ]`.

snforacle.interface.smith_normal_form_with_transforms ¶

smith_normal_form_with_transforms(
    matrix: Any, backend: _IntBackend | None = None
) -> SNFWithTransformsResult

Compute the Smith normal form together with the unimodular transformations.

Parameters:

Name	Type	Description	Default
`matrix`	`Any`	The input matrix (same accepted types as :func:`smith_normal_form`).	required
`backend`	`_IntBackend \| None`	Name of the backend to use.	`None`

Returns:

Type	Description
`SNFWithTransformsResult`	A Pydantic model with fields: `smith_normal_form` The m×n SNF matrix as a `DenseIntMatrix`. `invariant_factors` The sequence `[d₁, …, dᵣ]`. `left_transform` Unimodular m×m integer matrix U. `right_transform` Unimodular n×n integer matrix V. The matrices satisfy `U @ M @ V = smith_normal_form`.

snforacle.interface.hermite_normal_form ¶

hermite_normal_form(
    matrix: Any, backend: _IntBackend | None = None
) -> HNFResult

Compute the row Hermite Normal Form of an integer matrix.

The Hermite Normal Form is the unique upper-triangular matrix H with positive pivots (smallest to largest) satisfying H = U·M for some unimodular integer matrix U.

Parameters:

Name	Type	Description	Default
`matrix`	`Any`	The input matrix as a `DenseIntMatrix`, `SparseIntMatrix`, or a plain `dict` conforming to one of those schemas.	required
`backend`	`_IntBackend \| None`	Name of the backend to use. Default is `"flint"` (cypari2 does not support row HNF and raises `NotImplementedError`).	`None`

Returns:

Type	Description
`HNFResult`	A Pydantic model with field: `hermite_normal_form` The m×n HNF matrix as a `DenseIntMatrix`. Upper triangular with positive pivots in non-decreasing order; entries above pivots satisfy 0 ≤ entry < pivot.

snforacle.interface.hermite_normal_form_with_transform ¶

hermite_normal_form_with_transform(
    matrix: Any, backend: _IntBackend | None = None
) -> HNFWithTransformResult

Compute the row Hermite Normal Form together with the left unimodular transform.

Parameters:

Name	Type	Description	Default
`matrix`	`Any`	The input matrix (same accepted types as :func:`hermite_normal_form`).	required
`backend`	`_IntBackend \| None`	Name of the backend to use. Default is `"sage"` (flint does not support transforms; cypari2 does not support row HNF).	`None`

Returns:

Type	Description
`HNFWithTransformResult`	A Pydantic model with fields: `hermite_normal_form` The m×n HNF matrix as a `DenseIntMatrix`. `left_transform` Unimodular m×m integer matrix U. The matrices satisfy `U @ M = hermite_normal_form`.

snforacle.interface.elementary_divisors ¶

elementary_divisors(
    matrix: Any, backend: _IntBackend | None = None
) -> ElementaryDivisorsResult

Compute the non-zero invariant factors (elementary divisors) of an integer matrix.

These are the diagonal entries of the Smith normal form, returned in non-decreasing order. They may be computed via a potentially faster dedicated path than the full SNF computation.

Parameters:

Name	Type	Description	Default
`matrix`	`Any`	The input matrix (same accepted types as :func:`smith_normal_form`).	required
`backend`	`_IntBackend \| None`	Name of the backend to use. Default is `"cypari2"`.	`None`

Returns:

Type	Description
`ElementaryDivisorsResult`	A Pydantic model with field: `elementary_divisors` Non-zero invariant factors in non-decreasing order.

Input models¶

snforacle.schema.DenseIntMatrix ¶

Bases: BaseModel

An integer matrix stored as a full list of rows.

snforacle.schema.SparseIntMatrix ¶

Bases: BaseModel

An integer matrix stored as a list of (row, col, value) triples.

Entries not listed are implicitly zero. Duplicate (row, col) pairs are not allowed; the last value wins only if allow_duplicates is True (default: False).

snforacle.schema.SparseEntry ¶

Bases: BaseModel

A single nonzero entry in a sparse integer matrix.

Output models¶

snforacle.schema.SNFResult ¶

Bases: BaseModel

The Smith normal form of an integer matrix.

smith_normal_form is always returned as a dense matrix whose diagonal contains the invariant factors d₁ | d₂ | … | dᵣ (in non-decreasing order) and whose off-diagonal entries are zero.

invariant_factors is the same sequence as the diagonal, listed without the surrounding zero rows/columns.

snforacle.schema.SNFWithTransformsResult ¶

Bases: BaseModel

The Smith normal form together with unimodular transformation matrices.

Let M be the input matrix. The matrices satisfy::

left_transform · M · right_transform = smith_normal_form

All three matrices are returned as dense integer matrices.

snforacle.schema.HNFResult ¶

Bases: BaseModel

Row Hermite Normal Form of an integer matrix.

The Hermite Normal Form is the unique upper-triangular matrix H with positive pivots (smallest to largest) satisfying H = U·M for some unimodular integer matrix U.

snforacle.schema.HNFWithTransformResult ¶

Bases: BaseModel

Row Hermite Normal Form together with the left unimodular transform.

Let M be the input matrix. The matrices satisfy::

left_transform · M = hermite_normal_form

Both matrices are returned as dense integer matrices.

snforacle.schema.ElementaryDivisorsResult ¶

Bases: BaseModel

Non-zero invariant factors of an integer matrix.

These are the same values as the diagonal of the Smith normal form, returned in non-decreasing order. They can be computed via a potentially faster dedicated path than the full SNF computation.