jordan_form package

class jordan_form.AlgebraicMultiplicity(*, eigvals: ndarray[tuple[int], dtype[number]])[source]

Bases: AlgebraicMultiplicityProtocol

property algebraic_multiplicity: int

The algebraic multiplicity of the eigenvalue.

The number of times the eigenvalue appears as a root of the characteristic polynomial.

The number of generalized eigenvectors in a canonical system of Jordan chains.

property eigval: float

The main eigenvalue.

eigvals: ndarray[tuple[int], dtype[number]]

The eigenvalues of shape (algebraic_multiplicity,).

class jordan_form.CanonicalJordanChains(*, eigval: float, chains: list[ndarray[tuple[int, int], dtype[number]]])[source]

Bases: MultiplicityProtocol

Canonical system of Jordan chains.

property algebraic_multiplicity: int

The algebraic multiplicity of the eigenvalue.

The number of times the eigenvalue appears as a root of the characteristic polynomial.

The number of generalized eigenvectors in a canonical system of Jordan chains.

property chain_lengths: ndarray[tuple[int], dtype[int64]]

The length of the Jordan chains.

Known as Segre number.

References

大竹 剛, 古賀 雅伸 and 三平 満司. 2002. 行列のジョルダン標準形の数値計算法. システム制御情報学会論文誌 15, 7 (2002), 320–326. https://doi.org/10.5687/iscie.15.320

chains: list[ndarray[tuple[int, int], dtype[number]]]

The Jordan chains of shape (l_chain, n).

property dim_generalized_eigenspace: ndarray[tuple[int], dtype[int64]]

The dimension of the generalized eigenspaces for oridinary eigenvalue problem.

Known as Kågström number.

In general, the element of Jordan chains is not orthogonal and this property should not be used.

References

Bo Kågström and Axel Ruhe. 1980. An Algorithm for Numerical Computation of the Jordan Normal Form of a Complex Matrix. ACM Trans. Math. Softw. 6, 3 (Sept. 1980), 398–419. https://doi.org/10.1145/355900.355912

大竹 剛, 古賀 雅伸 and 三平 満司. 2002. 行列のジョルダン標準形の数値計算法. システム制御情報学会論文誌 15, 7 (2002), 320–326. https://doi.org/10.5687/iscie.15.320

property dim_ith_generalized_eigenvectors: ndarray[tuple[int], dtype[int64]]

The dimension of the space generated by the i-th generalized eigenvectors for oridinary eigenvalue problem.

The dimension of the quotient space (i-th generalized eigenspace) / (i-1-th generalized eigenspace).

Known as Weyr number.

References

大竹 剛, 古賀 雅伸 and 三平 満司. 2002. 行列のジョルダン標準形の数値計算法. システム制御情報学会論文誌 15, 7 (2002), 320–326. https://doi.org/10.5687/iscie.15.320

eigval: float
property eigvec_orthogonal: ndarray[tuple[int, int], dtype[number]]

The orthogonal eigenvectors of shape (n, geometric_multiplicity).

property geometric_multiplicity: int

The geometric multiplicity of the eigenvalue.

The dimension of the eigenspace of the eigenvalue. Less than or equal to the algebraic multiplicity.

property num_chains: int

The number of Jordan chains.

class jordan_form.Multiplicity(*, eigvals: ndarray[tuple[int], dtype[number]], eigvecs: ndarray[tuple[int, int], dtype[number]], eigvec_orthogonal: ndarray[tuple[int, int], dtype[number]])[source]

Bases: AlgebraicMultiplicity, MultiplicityProtocol

eigvec_orthogonal: ndarray[tuple[int, int], dtype[number]]
eigvecs: ndarray[tuple[int, int], dtype[number]]

The eigenvectors of shape (n, algebraic_multiplicity).

property geometric_multiplicity: int

The geometric multiplicity of the eigenvalue.

The dimension of the eigenspace of the eigenvalue. Less than or equal to the algebraic multiplicity.

jordan_form.canonical_jordan_chains(A_func: MatrixFuncProtocol, eigval: float, /, atol_rank: float | None = None, rtol_rank: float | None = None, atol_norm: float | None = None, rtol_norm: float | None = None, algebraic_multiplicity: int | None = None) → CanonicalJordanChains[source]

Get the canonical Jordan chains of the matrix function.

Parameters:

  • A_func (MatrixFuncProtocol) – The matrix function which takes (λ, d) as input and returns the d-th derivative of the matrix function evaluated at the eigenvalue λ.

  • eigval (float) – The eigenvalue to evaluate the matrix function.

  • atol_rank (float, optional) – Threshold below which SVD values are considered zero. Defaults to np.finfo(A.dtype).eps.

  • rtol_rank (float, optional) – Threshold below which SVD values are considered zero. Defaults to np.finfo(A.dtype).eps.

  • atol_norm (float, optional) – Threshold below which norm values are considered zero. Defaults to np.finfo(A.dtype).eps.

  • rtol_norm (float, optional) – Threshold below which norm values are considered zero. Defaults to np.finfo(A.dtype).eps.

  • algebraic_multiplicity (int, optional) – The algebraic multiplicity of the eigenvalue. If provided, a warning is issued if the number of generalized eigenvectors found does not match the algebraic multiplicity.

Returns:

The canonical Jordan chains of the matrix function.

Return type:

JordanChains

jordan_form.canonoical_jordan_chains_from_unrestricted(unrestricted_chains: list[ndarray[tuple[int, int, int], dtype[number]]], /, *, hermitian: bool | None = None, atol_rank: float | None = None, rtol_rank: float | None = None, atol_norm: float | None = None, rtol_norm: float | None = None, flatten: Literal[False] = True) → list[ndarray[tuple[int, int, int], dtype[number]]][source]
jordan_form.canonoical_jordan_chains_from_unrestricted(unrestricted_chains: list[ndarray[tuple[int, int, int], dtype[number]]], /, *, hermitian: bool | None = None, atol_rank: float | None = None, rtol_rank: float | None = None, atol_norm: float | None = None, rtol_norm: float | None = None, flatten: Literal[True] = True) → list[ndarray[tuple[int, int], dtype[number]]]

Get the Jordan chains of the matrix.

Parameters:

  • unrestricted_chains (np.ndarray[tuple[int, int, int], np.dtype[np.number]]) – The list of unrestricted Jordan chains of shape (n_chain, l_chain, n).

  • hermitian (bool, optional) – If True, A is assumed to be Hermitian (symmetric if real-valued), enabling a more efficient method for finding singular values. Defaults to False.

  • atol_rank (float, optional) – Threshold below which SVD values are considered zero. Defaults to np.finfo(A.dtype).eps.

  • rtol_rank (float, optional) – Threshold below which SVD values are considered zero. Defaults to np.finfo(A.dtype).eps.

  • atol_norm (float, optional) – Threshold below which norm values are considered zero. Defaults to np.finfo(A.dtype).eps.

  • rtol_norm (float, optional) – Threshold below which norm values are considered zero. Defaults to np.finfo(A.dtype).eps.

  • flatten (bool, optional) – If True, flatten the chains. Defaults to True.

Returns:

The Jordan chains. If flatten is True, each chain is of shape (l_chain, n). If flatten is False, each chain is of shape (n_chain_l, l_chain, n).

Return type:

list[NDArray[np.number]]

jordan_form.geig_func(A: ndarray[tuple[int, int], dtype[number]], B: ndarray[tuple[int, int], dtype[number]] | None = None, /) → MatrixFuncProtocol[source]

Create a generalized eigenvalue function.

Parameters:

  • A (NDArray[np.number]) – The matrix A of shape (n, n).

  • B (NDArray[np.number], optional) – The matrix B of shape (n, n), by default None. If None, the identity matrix is used. (oridanary eigenvalue problem)

Returns:

The matrix function λ→(A-Bλ) where (A-Bλ) is of shape (n, n).

Return type:

MatrixFuncProtocol

jordan_form.group_close_eigvals(eigvals: Sequence[float], /, *, atol: float | None = None, rtol: float | None = None) → list[list[int]][source]

Group the eigenvalues that are close to each other.

Parameters:

  • eigvals (Sequence[float]) – The eigenvalues.

  • atol (float | None, optional) – The threshold to treat eigenvalues as the same. Defaults to np.finfo(eigval.dtype).eps.

  • rtol (float | None, optional) – The threshold to treat eigenvalues as the same. Defaults to np.finfo(eigval.dtype).eps.

Returns:

The indices of the eigenvalues that are close to each other.

Return type:

list[list[int]]

jordan_form.multiplicity(eigvals: ndarray[tuple[Any, ...], dtype[number]], eigvecs: ndarray[tuple[Any, ...], dtype[number]] = None, /, *, atol_algebraic: float | None = None, rtol_algebraic: float | None = None, atol_geometric: float | None = None, rtol_geometric: float | None = None) → list[Multiplicity][source]
jordan_form.multiplicity(eigvals: ndarray[tuple[Any, ...], dtype[number]], eigvecs: None = None, /, *, atol_algebraic: float | None = None, rtol_algebraic: float | None = None, atol_geometric: float | None = None, rtol_geometric: float | None = None) → list[AlgebraicMultiplicity]

Get the multiplicity of the eigenvalue.

Does not support batched eigenvalues.

Parameters:

  • eigvals (Array | NativeArray) – The eigenvalues of shape (n_eig,).

  • eigvecs (Array | NativeArray | None, optional) – The eigenvectors of shape (n, n_eig), by default None.

  • atol_algebraic (float | None, optional) – The threshold to treat eigenvalues as the same. Defaults to np.finfo(eigval.dtype).eps.

  • rtol_algebraic (float | None, optional) – The threshold to treat eigenvalues as the same. Defaults to np.finfo(eigval.dtype).eps.

  • atol_geometric (float, optional) – Threshold below which SVD values are considered zero. Defaults to np.finfo(A.dtype).eps.

  • rtol_geometric (float, optional) – Threshold below which SVD values are considered zero. Defaults to np.finfo(A.dtype).eps.

Returns:

The multiplicity of the eigenvalue.

Return type:

int

jordan_form.sympy_func(A: Any) → MatrixFuncProtocol[source]

Create a sympy matrix function.

Parameters:

A (Any) – The sympy matrix.

Returns:

The matrix function λ→A(λ).

Return type:

MatrixFuncProtocol

Submodules

jordan_form.cli module

jordan_form.cli.main(expr: str, eigval: float, rtol: float = 0.001, atol: float = 0.001) → None[source]

Main function to run the script.

Parameters:

  • expr (str) – The input function.

  • eigval (float) – The eigenvalue.

  • rtol (float) – The relative tolerance.

  • atol (float) – The absolute tolerance.

jordan_form.plot module

jordan_form.plot.plot_eigval_with_multiplicity(multiplicities: Sequence[TMultiplicity], /, *, ax: Axes | None = None, text_filter: Callable[[TMultiplicity], bool] | None = None, text_additionial: Callable[[TMultiplicity], str] | None = None, text_add_clue: bool = False, text_format_string: str = '{:.3g}', text_kwargs: dict[str, Any] | None = None, scatter_kwargs: dict[str, Any] | None = None) → None[source]

Plot eigenvalues with annotation of the multiplicity.

Does not support batched eigenvalues.

Parameters:

  • multiplicities (Sequence[Tultiplicity]) – The multiplicities to plot.

  • ax (plt.Axes | None, optional) – The axes to plot, by default None.

  • text_filter (Callable[[TMultiplicity], bool] | None, optional) – A function to filter the text to be plotted, by default None. If None, all multiplicities will be plotted. If a function is provided, only the multiplicities that return True will be plotted.

  • text_additionial (Callable[[TMultiplicity], str] | None, optional) – A function to add additional text to the plot, by default None. If None, no additional text will be plotted.

  • text_add_clue (bool, optional) – Whether to add maximum distance between eigenvalues and singular values of the eigenvectors (if provided), by default False.

  • text_format_string (str, optional) – The format string for the text, by default “{:.3g}”. This is used to format the maximum distance between eigenvalues and singular values of the eigenvectors (if provided).

  • text_kwargs (dict[str, Any] | None, optional) – The keyword arguments to pass to the text function, by default None. If None, no additional keyword arguments will be passed.

  • scatter_kwargs (dict[str, Any] | None, optional) – The keyword arguments to pass to the scatter function, by default None. If None, no additional keyword arguments will be passed.