cvx-linalg 0.9.1

Linear algebra utilities for portfolio optimization

cvx-linalg

Linear algebra utilities for portfolio optimization, part of the jebel-quant ecosystem.

Installation

pip install cvx-linalg

The ewm_covariance function requires the optional Polars dependency:

pip install 'cvx-linalg[ewm]'

Usage

from cvx.linalg import (
    a_norm, cholesky, cholesky_solve,
    inv, inv_a_norm, is_positive_definite, lstsq, pca, rand_cov, solve, valid,
)
from cvx.linalg.covariance.ewm_cov import ewm_covariance  # requires the 'ewm' extra (polars)

Functions

• a_norm(vector, matrix=None) — Euclidean norm or NaN-aware matrix norm
• cholesky(cov) — Upper triangular Cholesky factor R such that R.T @ R = cov
• cholesky_solve(cov, rhs) — Solve cov @ x = rhs via Cholesky decomposition (falls back to LU for non-positive-definite matrices)
• cond(matrix, p=None) — Condition number of a matrix (NaN-aware); accepts the same p norm values as numpy.linalg.cond
• det(matrix, cond_threshold=1e12) — Determinant of a square matrix with NaN-aware submatrix handling; emits IllConditionedMatrixWarning when near-singular
• eigvals(matrix) — Eigenvalues of a general square matrix (supports complex output for non-symmetric matrices)
• eigh(matrix) — Eigenvalues/eigenvectors of the valid symmetric/Hermitian submatrix in ascending eigenvalue order
• eigvalsh(matrix) — Eigenvalues-only convenience wrapper around eigh
• ewm_covariance(data, assets, index_col, window, is_halflife, warmup) — Exponentially weighted covariance matrices from a Polars DataFrame
• inv(matrix, cond_threshold=1e12) — Invert a matrix restricted to valid rows/columns; NaN rows/columns are returned for invalid positions
• inv_a_norm(vector, matrix=None) — Euclidean norm or inverse NaN-aware matrix norm
• lstsq(matrix, rhs, cond_threshold=1e12) — Solve a least-squares system with NaN-aware row filtering; returns (x, residuals, rank, sv) consistent with numpy.linalg.lstsq
• is_positive_definite(matrix) — Return True if the matrix is symmetric positive-definite
• pca(returns, n_components) — Principal Component Analysis via SVD
• power_iteration(matrix, n_iter=1000, tol=1e-9, seed=None) — Estimate the dominant (largest-magnitude) eigenpair of a symmetric matrix via power iteration
• qr(matrix) — Reduced QR decomposition, matching np.linalg.qr(mode='reduced')
• rand_cov(n, seed) — Random positive semi-definite covariance matrix
• solve(matrix, rhs, cond_threshold=1e12) — Solve a linear system (vector or matrix rhs) restricted to valid rows/columns; NaN entries are returned for invalid positions
• svd(matrix) — Raw compact singular value decomposition via np.linalg.svd(full_matrices=False)
• svd_k(matrix, k) — Exact truncated rank-k SVD (the best rank-k approximation; leading triplets of the compact SVD)
• valid(matrix) — Return a boolean mask and valid submatrix by removing rows/columns with non-finite diagonal entries

Exceptions & Warnings

All exceptions and warnings live in exceptions.py:

• DimensionMismatchError — Raised when vector length does not match matrix dimension
• IllConditionedMatrixWarning — Emitted when the condition number exceeds a configurable threshold
• InvalidComponentsError — Raised when pca is asked for fewer than 1 or more components than the data supports
• NegativeWarmupError — Raised when a negative warmup period is passed to ewm_covariance
• NonIntegerWarmupError — Raised when a non-integer warmup is passed to ewm_covariance
• NonSquareMatrixError — Raised when a square matrix is required but the input is not square
• NotAMatrixError — Raised when a 2-D matrix is required but the input has different dimensionality
• SingularMatrixError — Raised when a matrix is numerically singular
• check_and_warn_condition(matrix, threshold) — Emit IllConditionedMatrixWarning when the condition number exceeds the threshold

Types

• Matrix — Type alias for a 2-D numpy.ndarray with float64 dtype
• Vector — Type alias for a 1-D numpy.ndarray with float64 dtype

The package ships a py.typed marker; all public signatures are precisely annotated and verified with ty in CI.

Stability policy

This package follows semantic versioning. The public API is everything importable from cvx.linalg (plus cvx.linalg.covariance.ewm_cov):

• Breaking changes only occur in major releases.
• Deprecations are announced at least one minor release before removal and emit a DeprecationWarning in the meantime (currently: the two-argument cholesky(cov, rhs) form — use cholesky_solve — slated for removal in 1.0).
• Supported environments: Python 3.11–3.14, NumPy ≥ 2.0. The optional ewm extra requires Polars ≥ 1.40.

Numerical conventions (NaN handling, condition-number warnings, dtype contract) are documented in Numerical Behavior.