derivkit.utils.linalg module#

This module provides small linear-algebra helpers.

The main features are:

  1. Diagnostics: warn about non-symmetric inputs, ill-conditioning, and rank issues, and choose a safe fallback when a fast path fails.

  2. Canonicalization: accept covariance inputs in multiple forms (scalar, 1D diagonal vector, or 2D matrix) and convert them into a consistent 2D array with validated shape and finite values. In other words, we normalize the input representation so downstream code always receives a well-formed (k x k) array.

derivkit.utils.linalg.invert_covariance(cov: ndarray, *, rcond: float = 1e-12, warn_prefix: str = '') → ndarray#

Return the inverse covariance with diagnostics; fall back to pseudoinverse when needed.

This helper accepts a scalar (0D), a diagonal variance vector (1D), or a full covariance matrix (2D). Inputs are canonicalized to a 2D array before inversion. The function warns (but does not modify data) if the matrix is non-symmetric, warns on ill-conditioning, and uses a pseudoinverse when inversion is not viable.

Parameters:

  • cov – Covariance (scalar, diagonal vector, or full 2D matrix).

  • rcond – Cutoff for small singular values used by np.linalg.pinv.

  • warn_prefix – Optional prefix included in warnings (e.g., a class or function name).

Returns:

A 2D NumPy array containing the inverse covariance.

Raises:

ValueError – If cov has more than 2 dimensions or is not square when 2D.

derivkit.utils.linalg.make_spd_by_jitter(matrix: Any, *, max_tries: int = 12, jitter_scale: float = 1e-10, jitter_floor: float = 1e-12) → tuple[ndarray[tuple[Any, ...], dtype[float64]], float]#

Makes a symmetric matrix SPD by adding diagonal jitter if necessary.

Parameters:

  • matrix – Array-like square matrix.

  • max_tries – Maximum number of jitter attempts (powers of 10).

  • jitter_scale – Scale factor for jitter based on mean diagonal.

  • jitter_floor – Minimum jitter to add.

Returns:

A tuple (spd_matrix, jitter_added), where spd_matrix is the SPD matrix and jitter_added is the amount of jitter added to the diagonal.

Raises:

np.linalg.LinAlgError – If the matrix cannot be made SPD within max_tries

derivkit.utils.linalg.normalize_covariance(cov: Any, n_parameters: int, *, asym_atol: float = 1e-12) → ndarray[tuple[Any, ...], dtype[float64]]#

Return a canonicalized covariance matrix.

Accepts a scalar (0D), a diagonal variance vector (1D), or a full covariance matrix (2D). Validates shapes and finiteness, symmetrizes full matrices, and returns a 2D array of shape (k, k).

Parameters:

  • cov – Covariance (scalar, diagonal vector, or full 2D matrix).

  • n_parameters – Expected size of the covariance (number of parameters).

  • asym_atol – Absolute tolerance for symmetry check of full matrices.

Returns:

A 2D NumPy array containing the canonicalized covariance matrix.

Raises:

ValueError – If cov has invalid shape, contains non-finite values, or is too asymmetric.

derivkit.utils.linalg.solve_or_pinv(matrix: ndarray, vector: ndarray, *, rcond: float = 1e-12, assume_symmetric: bool = True, warn_context: str = 'linear solve') → ndarray#

Solve matrix @ x = vector with pseudoinverse fallback.

If assume_symmetric is True (e.g., Fisher matrices), attempt a Cholesky-based solve. If the matrix is not symmetric positive definite or is singular, emit a warning and fall back to np.linalg.pinv(matrix, rcond) @ vector.

Parameters:

  • matrix – Coefficient matrix of shape (n, n).

  • vector – Right-hand side vector or matrix of shape (n,) or (n, k).

  • rcond – Cutoff for small singular values used by np.linalg.pinv.

  • assume_symmetric – If True, prefer a Cholesky solve (fast path for symmetric positive definite (SPD)/Hermitian).

  • warn_context – Short label included in the warning message.

Returns:

Solution array x with shape matching vector ((n,) or (n, k)).

Raises:

ValueError – If shapes of matrix and vector are incompatible.

derivkit.utils.linalg.symmetrize_matrix(a: Any) → ndarray[tuple[Any, ...], dtype[float64]]#

Symmetrizes a square matrix.

Parameters:

a – Array-like square matrix.

Returns:

Symmetric 2D float64 NumPy array.

Raises:

ValueError – If input is not a square 2D array.