API Reference¶

class eigensystems.EigenResult(eigenvalues, eigenvectors=None, converged=True, n_iter=0, message='')¶

Bases: object

Container for eigenvalue/eigenvector computation results.

Parameters:

eigenvalues (ndarray)
eigenvectors (ndarray | None)
converged (bool)
n_iter (int)
message (str)

eigenvalues¶

Array of computed eigenvalues.

Type:: np.ndarray

eigenvectors¶

Matrix of eigenvectors as columns, or None when only eigenvalues were requested.

Type:: Optional[np.ndarray]

converged¶

Whether the computation converged successfully.

Type:: bool

n_iter¶

Number of iterations performed (0 for direct methods).

Type:: int

message¶

Human-readable status message.

Type:: str

Real General Eigenvalue Functions¶

eigensystems.evlrg(a)¶

Compute eigenvalues of a real general matrix.

Wraps numpy.linalg.eigvals(). Corresponds to IMSL routine EVLRG.

Parameters:

a (array-like) – Square real matrix of shape (n, n).

Returns:

Result with eigenvalues set; eigenvectors is None.

Return type:

EigenResult

Raises:

TypeError – If a cannot be converted to a numeric array.
ValueError – If a is not square.

eigensystems.evcrg(a)¶

Compute eigenvalues and right eigenvectors of a real general matrix.

Wraps numpy.linalg.eig(). Corresponds to IMSL routine EVCRG.

Parameters:

a (array-like) – Square real matrix of shape (n, n).

Returns:

Result with eigenvalues and eigenvectors set.: Each column of eigenvectors is the right eigenvector corresponding to the eigenvalue at the same index.

Return type:

EigenResult

Raises:

TypeError – If a cannot be converted to a numeric array.
ValueError – If a is not square.

eigensystems.evlrh(a)¶

Compute eigenvalues of a real upper Hessenberg matrix.

Uses scipy.linalg.eigvals() with homogeneous_eigvals=False. Corresponds to IMSL routine EVLRH. The matrix is assumed to be in upper Hessenberg form; no reduction is performed.

Parameters:

a (array-like) – Square real upper Hessenberg matrix of shape (n, n).

Returns:

Result with eigenvalues set; eigenvectors is None.

Return type:

EigenResult

Raises:

TypeError – If a cannot be converted to a numeric array.
ValueError – If a is not square.

Real Symmetric Eigenvalue Functions¶

eigensystems.evlsf(a)¶

Compute eigenvalues of a real symmetric matrix.

Wraps numpy.linalg.eigvalsh(). Eigenvalues are returned in ascending order. Corresponds to IMSL routine EVLSF.

Parameters:

a (array-like) – Square real symmetric matrix of shape (n, n).

Returns:

Result with eigenvalues set (real, ascending);: eigenvectors is None.

Return type:

EigenResult

Raises:

TypeError – If a cannot be converted to a numeric array.
ValueError – If a is not square.

eigensystems.evcsf(a)¶

Compute eigenvalues and eigenvectors of a real symmetric matrix.

Wraps numpy.linalg.eigh(). Eigenvalues are returned in ascending order; eigenvectors are orthonormal. Corresponds to IMSL routine EVCSF.

Parameters:

a (array-like) – Square real symmetric matrix of shape (n, n).

Returns:

Result with eigenvalues (real, ascending) and: eigenvectors (orthonormal columns) set.

Return type:

EigenResult

Raises:

TypeError – If a cannot be converted to a numeric array.
ValueError – If a is not square.

Complex General Eigenvalue Functions¶

eigensystems.evlcg(a)¶

Compute eigenvalues of a complex general matrix.

Wraps numpy.linalg.eigvals(). Corresponds to IMSL routine EVLCG.

Parameters:

a (array-like) – Square complex matrix of shape (n, n).

Returns:

Result with eigenvalues set (complex array);: eigenvectors is None.

Return type:

EigenResult

Raises:

TypeError – If a cannot be converted to a numeric array.
ValueError – If a is not square.

eigensystems.evccg(a)¶

Compute eigenvalues and right eigenvectors of a complex general matrix.

Wraps numpy.linalg.eig(). Corresponds to IMSL routine EVCCG.

Parameters:

a (array-like) – Square complex matrix of shape (n, n).

Returns:

Result with eigenvalues and eigenvectors set.: Each column of eigenvectors is the right eigenvector corresponding to the eigenvalue at the same index.

Return type:

EigenResult

Raises:

TypeError – If a cannot be converted to a numeric array.
ValueError – If a is not square.

Complex Hermitian Eigenvalue Functions¶

eigensystems.evlch(a)¶

Compute eigenvalues of a complex Hermitian matrix.

Wraps numpy.linalg.eigvalsh(). Eigenvalues are real and returned in ascending order. Corresponds to IMSL routine EVLCH.

Parameters:

a (array-like) – Square complex Hermitian matrix of shape (n, n).

Returns:

Result with eigenvalues (real, ascending) set;: eigenvectors is None.

Return type:

EigenResult

Raises:

TypeError – If a cannot be converted to a numeric array.
ValueError – If a is not square.

eigensystems.evcch(a)¶

Compute eigenvalues and eigenvectors of a complex Hermitian matrix.

Wraps numpy.linalg.eigh(). Eigenvalues are real and ascending; eigenvectors are unitary. Corresponds to IMSL routine EVCCH.

Parameters:

a (array-like) – Square complex Hermitian matrix of shape (n, n).

Returns:

Result with eigenvalues (real, ascending) and: eigenvectors (unitary columns) set.

Return type:

EigenResult

Raises:

TypeError – If a cannot be converted to a numeric array.
ValueError – If a is not square.

Generalized Eigenvalue Functions¶

eigensystems.gvlrg(a, b)¶

Compute generalized eigenvalues of a real general matrix pair (A, B).

Solves the generalized eigenvalue problem A @ v = lambda * B @ v. Wraps scipy.linalg.eigvals() with the b argument. Corresponds to IMSL routine GVLRG.

Parameters:

a (array-like) – Square real matrix of shape (n, n).
b (array-like) – Square real matrix of shape (n, n).

Returns:

Result with eigenvalues set (may be complex);: eigenvectors is None.

Return type:

EigenResult

Raises:

TypeError – If a or b cannot be converted to a numeric array.
ValueError – If a or b are not square or not the same size.

eigensystems.gvcrg(a, b)¶

Compute generalized eigenvalues and right eigenvectors for (A, B).

Solves A @ v = lambda * B @ v. Wraps scipy.linalg.eig() with the b argument. Corresponds to IMSL routine GVCRG.

Parameters:

a (array-like) – Square real matrix of shape (n, n).
b (array-like) – Square real matrix of shape (n, n).

Returns:

Result with eigenvalues and eigenvectors set.

Return type:

EigenResult

Raises:

TypeError – If a or b cannot be converted to a numeric array.
ValueError – If a or b are not square or not the same size.

eigensystems.gvlsf(a, b)¶

Compute generalized eigenvalues of a real symmetric-definite pair (A, B).

Solves A @ v = lambda * B @ v where A is symmetric and B is symmetric positive-definite. Wraps scipy.linalg.eigh() with the b argument. Eigenvalues are real and ascending. Corresponds to IMSL routine GVLSF.

Parameters:

a (array-like) – Square real symmetric matrix of shape (n, n).
b (array-like) – Square real symmetric positive-definite matrix of shape (n, n).

Returns:

Result with eigenvalues (real, ascending) set;: eigenvectors is None.

Return type:

EigenResult

Raises:

TypeError – If a or b cannot be converted to a numeric array.
ValueError – If a or b are not square or not the same size.

eigensystems.gvcsf(a, b)¶

Compute generalized eigenvalues and eigenvectors of a symmetric-definite pair.

Solves A @ v = lambda * B @ v where A is symmetric and B is symmetric positive-definite. Wraps scipy.linalg.eigh() with the b argument. Eigenvalues are real and ascending; eigenvectors are B-orthonormal. Corresponds to IMSL routine GVCSF.

Parameters:

a (array-like) – Square real symmetric matrix of shape (n, n).
b (array-like) – Square real symmetric positive-definite matrix of shape (n, n).

Returns:

Result with eigenvalues (real, ascending) and: eigenvectors (B-orthonormal columns) set.

Return type:

EigenResult

Raises:

TypeError – If a or b cannot be converted to a numeric array.
ValueError – If a or b are not square or not the same size.

Matrix Decomposition Functions¶

eigensystems.svd(a)¶

Compute the full Singular Value Decomposition of a matrix.

Returns (U, s, Vh) such that a ≈ U @ np.diag(s) @ Vh. Wraps numpy.linalg.svd().

Parameters:

a (array-like) – Real or complex matrix of shape (m, n).

Returns:

A tuple (U, s, Vh): where U has shape (m, m), s has shape (min(m, n),), and Vh has shape (n, n).

Return type:

Tuple[np.ndarray, np.ndarray, np.ndarray]

Raises:

TypeError – If a cannot be converted to a numeric array.

eigensystems.svd_values(a)¶

Compute only the singular values of a matrix.

Wraps numpy.linalg.svd() with compute_uv=False.

Parameters:: a (array-like) – Real or complex matrix of shape (m, n).
Returns:: Singular values in descending order, shape (min(m, n),).
Return type:: np.ndarray
Raises:: TypeError – If a cannot be converted to a numeric array.

eigensystems.qr_decomp(a)¶

Compute the QR decomposition of a matrix.

Returns (Q, R) such that a = Q @ R. Wraps numpy.linalg.qr().

Parameters:

a (array-like) – Real or complex matrix of shape (m, n).

Returns:

A tuple (Q, R) where Q is: orthogonal/unitary with shape (m, m) and R is upper triangular with shape (m, n).

Return type:

Tuple[np.ndarray, np.ndarray]

Raises:

TypeError – If a cannot be converted to a numeric array.

eigensystems.cholesky(a)¶

Compute the Cholesky decomposition of a positive-definite matrix.

Returns lower-triangular L such that a = L @ L.T.conj(). Wraps numpy.linalg.cholesky().

Parameters:

a (array-like) – Square positive-definite real or complex matrix of shape (n, n).

Returns:

Lower-triangular Cholesky factor L, shape (n, n).

Return type:

np.ndarray

Raises:

TypeError – If a cannot be converted to a numeric array.
ValueError – If a is not square.
np.linalg.LinAlgError – If a is not positive-definite.

eigensystems.lu_decomp(a)¶

Compute the LU decomposition of a matrix with partial pivoting.

Returns (P, L, U) such that A = P @ L @ U. Wraps scipy.linalg.lu().

Parameters:

a (array-like) – Real or complex matrix of shape (m, n).

Returns:

A tuple (P, L, U): where P is a permutation matrix (m, m), L is lower-triangular (m, k) with unit diagonal, and U is upper-triangular (k, n), k = min(m, n).

Return type:

Tuple[np.ndarray, np.ndarray, np.ndarray]

Raises:

TypeError – If a cannot be converted to a numeric array.

eigensystems.schur_decomp(a)¶

Compute the Schur decomposition of a square matrix.

Returns (T, Z) such that a = Z @ T @ Z.T.conj() where T is quasi-upper-triangular (real Schur) or upper-triangular (complex Schur) and Z is orthogonal/unitary. Wraps scipy.linalg.schur().

Parameters:

a (array-like) – Square real or complex matrix of shape (n, n).

Returns:

A tuple (T, Z) where T is: the Schur form (n, n) and Z is the Schur vectors matrix (n, n).

Return type:

Tuple[np.ndarray, np.ndarray]

Raises:

TypeError – If a cannot be converted to a numeric array.
ValueError – If a is not square.

Matrix Analysis Functions¶

eigensystems.matrix_norm(a, ord=None)¶

Compute a matrix or vector norm.

Wraps numpy.linalg.norm().

Parameters:

a (array-like) – Real or complex matrix or vector.
ord (int, float, str, or None) – Order of the norm. See numpy.linalg.norm() for valid values. Default is the Frobenius norm for matrices and the 2-norm for vectors.

Returns:

The computed norm value.

Return type:

float

Raises:

TypeError – If a cannot be converted to a numeric array.

eigensystems.condition_number(a, ord=None)¶

Compute the condition number of a matrix.

Wraps numpy.linalg.cond().

Parameters:

a (array-like) – Square real or complex matrix of shape (n, n).
ord (int, float, str, or None) – Order of the norm used for the condition number computation. Default uses the 2-norm (largest singular value / smallest singular value).

Returns:

The condition number of a. Values >> 1 indicate: near-singularity.

Return type:

float

Raises:

TypeError – If a cannot be converted to a numeric array.
ValueError – If a is not square.

eigensystems.matrix_rank(a, tol=None)¶

Compute the rank of a matrix using the SVD.

Wraps numpy.linalg.matrix_rank().

Parameters:

a (array-like) – Real or complex matrix of shape (m, n).
tol (float or None) – Threshold below which singular values are considered zero. If None, a default tolerance is used.

Returns:

Estimated rank of the matrix.

Return type:

int

Raises:

TypeError – If a cannot be converted to a numeric array.

eigensystems.determinant(a)¶

Compute the determinant of a square matrix.

Wraps numpy.linalg.det().

Parameters:

a (array-like) – Square real or complex matrix of shape (n, n).

Returns:

The determinant of a. For real matrices the result is: real; the return type is always numeric.

Return type:

complex

Raises:

TypeError – If a cannot be converted to a numeric array.
ValueError – If a is not square.

eigensystems.trace(a)¶

Compute the trace (sum of diagonal elements) of a square matrix.

Wraps numpy.trace().

Parameters:

a (array-like) – Square real or complex matrix of shape (n, n).

Returns:

The trace of a. For real matrices the result is real.

Return type:

complex

Raises:

TypeError – If a cannot be converted to a numeric array.
ValueError – If a is not square.

eigensystems.frobenius_norm(a)¶

Compute the Frobenius norm of a matrix.

The Frobenius norm is the square root of the sum of squared absolute values of all elements. Equivalent to matrix_norm(a, ord='fro').

Parameters:: a (array-like) – Real or complex matrix of shape (m, n).
Returns:: Frobenius norm of a.
Return type:: float
Raises:: TypeError – If a cannot be converted to a numeric array.

Utility Functions¶

eigensystems.is_symmetric(a, tol=1e-10)¶

Check whether a matrix is symmetric (or Hermitian for complex input).

Tests max|A - A.T.conj()| < tol.

Parameters:

a (array-like) – Square real or complex matrix of shape (n, n).
tol (float) – Absolute tolerance for the element-wise comparison. Defaults to 1e-10.

Returns:

True if a is symmetric/Hermitian within tol, else False.

Return type:

bool

Raises:

TypeError – If a cannot be converted to a numeric array.
ValueError – If a is not square.

eigensystems.is_positive_definite(a)¶

Check whether a matrix is symmetric positive-definite.

Attempts a Cholesky decomposition via numpy.linalg.cholesky(). Returns False if the decomposition fails (matrix is not SPD).

Parameters:

a (array-like) – Square real matrix of shape (n, n).

Returns:

True if a is symmetric positive-definite, else False.

Return type:

bool

Raises:

TypeError – If a cannot be converted to a numeric array.
ValueError – If a is not square.

eigensystems.symmetrize(a)¶

Return the symmetric part of a matrix, (A + A.T) / 2.

For complex matrices returns the Hermitian part (A + A.T.conj()) / 2.

Parameters:

a (array-like) – Square real or complex matrix of shape (n, n).

Returns:

Symmetrized/Hermitian matrix of shape (n, n).

Return type:

np.ndarray

Raises:

TypeError – If a cannot be converted to a numeric array.
ValueError – If a is not square.

eigensystems.orthogonalize(a)¶

Return an orthogonal basis for the column space of a via QR.

Computes the economy QR decomposition and returns Q.

Parameters:

a (array-like) – Real or complex matrix of shape (m, n) with m >= n.

Returns:

Orthonormal matrix Q of shape (m, n) whose columns: span the column space of a.

Return type:

np.ndarray

Raises:

TypeError – If a cannot be converted to a numeric array.
ValueError – If a has fewer rows than columns (m < n).

eigensystems.pseudo_inverse(a, rcond=None)¶

Compute the Moore-Penrose pseudo-inverse of a matrix.

Wraps numpy.linalg.pinv().

Parameters:

a (array-like) – Real or complex matrix of shape (m, n).
rcond (float or None) – Cutoff ratio for small singular values. Singular values smaller than rcond * max(s) are treated as zero. If None a machine-precision-based default is used.

Returns:

Pseudo-inverse of a with shape (n, m).

Return type:

np.ndarray

Raises:

TypeError – If a cannot be converted to a numeric array.