Skip to content
Symi Docs
Python
On this page

Matrix canonical forms

Canonical and integer forms return structured decompositions when metadata such as transformations, rank, pivots, or invariant factors is part of the result. Every decomposition on this page carries the transformation matrices that certify it, so the defining identity can be replayed exactly.

Ordinary matrix arithmetic, determinants, and spectral data are on linear algebra; the shape of each returned record is listed in structured results and the generated result-type index.

Canonical and integer forms#

rational_canonical_form#

Matrix method

rational_canonical_form(variable: VariableLike) -> RationalCanonicalForm

Returns the certified Frobenius canonical form over the rationals. Its invariant factors are monic and ordered by divisibility, and similarity satisfies matrix⁡ similarity⁡=similarity⁡ canonical_form⁡\operatorname{matrix}\,\operatorname{similarity} = \operatorname{similarity}\,\operatorname{canonical\_form} exactly.

rational_canonical_form (result class)#

Matrix method

rational_canonical_form(variable: VariableLike) -> RationalCanonicalForm

canonical_form#

RationalCanonicalForm property

canonical_form: Matrix

The Frobenius canonical form of the decomposed matrix.

invariant_factors#

The similarity, minimal_polynomial, and characteristic_polynomial getters return the corresponding certified fields documented by their shared headings above.

hermite_normal_form#

Matrix method

hermite_normal_form() -> tuple[Matrix, Matrix, int, list[int]]

Returns the canonical row-oriented Hermite normal form H, a unimodular transformation U satisfying UM=HU M = H, the rank, and the strictly increasing pivot-column indices. Entries must be exact integers. Every result is verified for Hermite shape, the certificate identity, and unimodularity before return. Notes: WASM returns a HermiteNormalFormDecomposition object with the getters documented below.

column_hermite_normal_form#

Matrix method

column_hermite_normal_form() -> tuple[Matrix, Matrix, int, list[int]]

The transpose-dual column form, returning H, a unimodular V satisfying MV=HM V = H, the rank, and pivot metadata. Notes: WASM returns a HermiteNormalFormDecomposition object.

smith_normal_form#

Matrix method

smith_normal_form() -> tuple[Matrix, Matrix, Matrix, int, list[Expression]]

Returns the canonical integer Smith normal form D, unimodular transformations U and V satisfying UMV=DU M V = D, the rank, and the invariant factors including trailing zeros. The nonnegative positive prefix is divisibility-ordered. Every result is verified for diagonal shape, divisibility, the exact certificate, and unimodularity of both transformations before return. Notes: WASM returns a SmithNormalFormDecomposition object with the getters documented below.

integer_cokernel_structure#

Matrix method

integer_cokernel_structure() -> tuple[int, list[Expression]]

Returns the free rank and nontrivial torsion invariant factors of Z^m / M Z^n. Notes: WASM returns an IntegerCokernelData object.

smith#

Not exposed by the Python bindings. Available as UniffiSmithNormalFormDecomposition.smith in Kotlin, UniffiSmithNormalFormDecomposition.smith in Swift, api::results::SmithNormalFormDecomposition::smith in Rust.

row_transformation#

Not exposed by the Python bindings. Available as UniffiSmithNormalFormDecomposition.rowTransformation in Kotlin, UniffiSmithNormalFormDecomposition.rowTransformation in Swift, api::results::SmithNormalFormDecomposition::row_transformation in Rust.

column_transformation#

Not exposed by the Python bindings. Available as UniffiSmithNormalFormDecomposition.columnTransformation in Kotlin, UniffiSmithNormalFormDecomposition.columnTransformation in Swift, api::results::SmithNormalFormDecomposition::column_transformation in Rust.

smith_invariant_factors#

free_rank#

torsion_invariant_factors#

integer_kernel_basis#

Matrix method

integer_kernel_basis() -> list[Matrix]

A canonical basis of the integer kernel {x∈Zn:Mx=0}\{x \in \mathbb{Z}^n : M x = 0\}, returned as column matrices.

integer_row_lattice_basis#

Matrix method

integer_row_lattice_basis() -> list[Matrix]

The nonzero rows of the row Hermite form, returned as row matrices; these form the canonical basis of the integer row lattice.

integer_image_lattice_basis#

Matrix method

integer_image_lattice_basis() -> list[Matrix]

The nonzero columns of the column Hermite form, returned as column matrices; these form the canonical basis of M Z^n.

hermite#

Not exposed by the Python bindings. Available as UniffiHermiteNormalFormDecomposition.hermite in Kotlin, UniffiHermiteNormalFormDecomposition.hermite in Swift, api::results::HermiteNormalFormDecomposition::hermite in Rust.

transformation#

Not exposed by the Python bindings. Available as UniffiHermiteNormalFormDecomposition.transformation in Kotlin, UniffiHermiteNormalFormDecomposition.transformation in Swift, api::results::HermiteNormalFormDecomposition::transformation in Rust.

pivot_columns#

Not exposed by the Python bindings. Available as UniffiHermiteNormalFormDecomposition.pivotColumns in Kotlin, UniffiHermiteNormalFormDecomposition.pivotColumns in Swift, api::results::HermiteNormalFormDecomposition::pivot_columns in Rust.

The rank getter reuses the matrix rank heading above.

Example#

Integer and polynomial canonical forms carry their transforming matrices.

Python
import symi

integer_matrix = symi.Matrix([[2, 4, 4], [-6, 6, 12], [10, 4, 16]])
smith, row_transformation, column_transformation, rank, invariant_factors = (
    integer_matrix.smith_normal_form()
)

print(rank)
print(invariant_factors)
print(integer_matrix.integer_cokernel_structure())

Additional API#

RationalCanonicalForm#

Type

class RationalCanonicalForm

Returns the certified Frobenius canonical form over the rationals. Its invariant factors are monic and ordered by divisibility, and similarity satisfies matrix⁡ similarity⁡=similarity⁡ canonical_form⁡\operatorname{matrix}\,\operatorname{similarity} = \operatorname{similarity}\,\operatorname{canonical\_form} exactly.

RationalCanonicalForm.characteristic_polynomial#

RationalCanonicalForm property

characteristic_polynomial: Expression

det⁡(λI−M)\det(\lambda I - M) as a polynomial in the named variable.

RationalCanonicalForm.invariant_factors#

RationalCanonicalForm property

invariant_factors: list[Expression]

The certified invariant factors, monic and ordered by divisibility.

RationalCanonicalForm.minimal_polynomial#

RationalCanonicalForm property

minimal_polynomial: Expression

The monic minimal polynomial over the rationals. The matrix must have rational entries.

RationalCanonicalForm.similarity#

RationalCanonicalForm property

similarity: Matrix

The certified change of basis S, satisfying matrix * S == S * canonical_form.

Symi documentation · Python