Skip to content
Symi Docs
Rust

The Rust manual covers the recommended facade. The complete native crate is documented in the native Rust API reference.

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#

api::matrix_operations::Matrix method

pub fn rational_canonical_form<'a, VariableType>(
    &self,
    variable: VariableType,
) -> Result<RationalCanonicalForm, ApiError>
where
    VariableType: Into<VariableLike<'a>>,

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)#

api::matrix_operations::Matrix method

pub fn rational_canonical_form<'a, VariableType>(
    &self,
    variable: VariableType,
) -> Result<RationalCanonicalForm, ApiError>
where
    VariableType: Into<VariableLike<'a>>,

canonical_form#

api::results::RationalCanonicalForm method

pub fn canonical_form(&self) -> Matrix

The canonical form itself.

invariant_factors#

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

hermite_normal_form#

api::matrix_operations::Matrix method

pub fn hermite_normal_form(
    &self,
) -> Result<HermiteNormalFormDecomposition, ApiError>

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#

api::matrix_operations::Matrix method

pub fn column_hermite_normal_form(
    &self,
) -> Result<HermiteNormalFormDecomposition, ApiError>

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#

api::matrix_operations::Matrix method

pub fn smith_normal_form(
    &self,
) -> Result<SmithNormalFormDecomposition, ApiError>

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#

api::matrix_operations::Matrix method

pub fn integer_cokernel_structure(
    &self,
) -> Result<IntegerCokernelData, ApiError>

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

smith#

api::results::SmithNormalFormDecomposition method

pub fn smith(&self) -> Matrix

The Smith normal form itself.

row_transformation#

api::results::SmithNormalFormDecomposition method

pub fn row_transformation(&self) -> Matrix

The unimodular row transform.

column_transformation#

api::results::SmithNormalFormDecomposition method

pub fn column_transformation(&self) -> Matrix

The unimodular column transform.

smith_invariant_factors#

free_rank#

torsion_invariant_factors#

integer_kernel_basis#

api::matrix_operations::Matrix method

pub fn integer_kernel_basis(&self) -> Result<Vec<Matrix>, ApiError>

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#

api::matrix_operations::Matrix method

pub fn integer_row_lattice_basis(&self) -> Result<Vec<Matrix>, ApiError>

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#

api::matrix_operations::Matrix method

pub fn integer_image_lattice_basis(
    &self,
) -> Result<Vec<Matrix>, ApiError>

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

hermite#

api::results::HermiteNormalFormDecomposition method

pub fn hermite(&self) -> Matrix

The Hermite normal form itself.

transformation#

api::results::HermiteNormalFormDecomposition method

pub fn transformation(&self) -> Matrix

pivot_columns#

The rank getter reuses the matrix rank heading above.

api::results::HermiteNormalFormDecomposition method

pub fn pivot_columns(&self) -> Vec<usize>

The pivot column indices.

Example#

This family is not part of the recommended symi::api facade in this release. Call it through the native modules in the native Rust API reference.

Additional API#

HermiteNormalFormDecomposition#

api re_export

pub use results::HermiteNormalFormDecomposition;

A Hermite normal form together with its unimodular transform.

Calling forms

Type: api::results::HermiteNormalFormDecomposition

pub struct HermiteNormalFormDecomposition

HermiteNormalFormDecomposition.rank#

api::results::HermiteNormalFormDecomposition method

pub fn rank(&self) -> usize

The rank of the source matrix.

RationalCanonicalForm#

api re_export

pub use results::RationalCanonicalForm;

A rational canonical form together with its similarity and invariants.

Calling forms

Type: api::results::RationalCanonicalForm

pub struct RationalCanonicalForm

RationalCanonicalForm.characteristic_polynomial#

api::results::RationalCanonicalForm method

pub fn characteristic_polynomial(&self) -> Expression

The characteristic polynomial of the source matrix.

RationalCanonicalForm.invariant_factors#

api::results::RationalCanonicalForm method

pub fn invariant_factors(&self) -> Vec<Expression>

The invariant factors of the companion decomposition.

RationalCanonicalForm.minimal_polynomial#

api::results::RationalCanonicalForm method

pub fn minimal_polynomial(&self) -> Expression

The minimal polynomial of the source matrix.

RationalCanonicalForm.similarity#

api::results::RationalCanonicalForm method

pub fn similarity(&self) -> Matrix

The similarity transform.

SmithNormalFormDecomposition#

api re_export

pub use results::SmithNormalFormDecomposition;

A Smith normal form together with its unimodular transforms.

Calling forms

Type: api::results::SmithNormalFormDecomposition

pub struct SmithNormalFormDecomposition

SmithNormalFormDecomposition.invariant_factors#

api::results::SmithNormalFormDecomposition method

pub fn invariant_factors(&self) -> Vec<Expression>

The invariant factors on the diagonal.

SmithNormalFormDecomposition.rank#

api::results::SmithNormalFormDecomposition method

pub fn rank(&self) -> usize

The rank of the source matrix.