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.

derivkit.utils.linalg.normalize_covariance(cov: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str], 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.