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.as_1d_data_vector(y: ndarray[tuple[Any, ...], dtype[float64]] | float) → ndarray[tuple[Any, ...], dtype[float64]]#

Converts a model output into a 1D data vector.

This function standardizes model outputs so downstream code can treat them as a single data vector. Scalars are converted to length-1 arrays. Array outputs are returned as 1D arrays, flattening higher-rank inputs in row-major (“C”) order.

Parameters:

y – Model output to convert. May be a scalar or an array-like object of any shape.

Returns:

A 1D float64 NumPy array representing the model output as a single data vector.

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.split_xy_covariance(cov: ndarray[tuple[Any, ...], dtype[float64]] | Mapping[str, Any], *, nx: int, atol_sym: float = 1e-12, rtol_sym: float = 1e-08) → tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]]#

Validates and splits a stacked covariance for the concatenated vector [x, y].

This function enforces the convention that the full covariance corresponds to a stacked data vector ordered as [x, y], where x has length nx and y has length n - nx. It returns the covariance blocks (Cxx, Cxy, Cyy) and raises informative errors if the input is not consistent with this convention.

The input may be provided directly as a 2D covariance matrix or as a dict-like object that includes the covariance and optional metadata for enforcing or reordering the [x, y] convention.

Parameters:

  • cov –

    Full covariance for the stacked vector [x, y]. Supported forms are:

    • A 2D covariance matrix with shape (nx+ny, nx+ny) acting on the stacked measurement vector [x, y], where x (length nx) denotes the input components and y (length ny) denotes the output components. The covariance is assumed to be ordered with x first, followed by y.

    • A dict-like object with key "cov" containing the 2D array. The dict may include:

      • "x_idx" and "y_idx": integer index arrays used to reorder an arbitrary covariance into [x, y] order before splitting.

  • nx – Number of input components in x (length of x in the stacked vector).

  • atol_sym – Absolute tolerance used for symmetry and cross-block consistency checks.

  • rtol_sym – Relative tolerance used for symmetry and cross-block consistency checks.

Returns:

  • cxx has shape (nx, nx).

  • cxy has shape (nx, ny).

  • cyy has shape (ny, ny).

Here ny = n - nx.

Return type:

A tuple (cxx, cxy, cyy) where

Raises:

ValueError – If cov is not a valid square covariance matrix, contains non-finite values, is not symmetric within tolerance, cannot be split using nx, or if the cross-blocks are inconsistent with the [x, y] stacking convention. Also raised if a dict-like object is missing required keys or uses an unsupported order value.

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.