derivkit.utils.diagnostics module#

Numerical diagnostics for Fisher and DALI forecasts.

These utilities inspect supplied matrices and model derivatives. They do not re-evaluate the model or compute additional derivatives.

derivkit.utils.diagnostics.dali_diagnostics(derivatives: dict[int, NDArray[float64]], cov: ArrayLike, displacement: ArrayLike, *, covariance_rcond: float = 1e-12) → dict[str, Any]#

Measure directional nonlinear model response from DALI derivatives.

Parameters:

  • derivatives – Model derivative tensors keyed by orders 1 up to 4. Order 1 is required. An order k tensor has shape (n_observables, p, ..., p) with k parameter axes.

  • cov – Symmetric positive semidefinite observational covariance of shape (n_observables, n_observables).

  • displacement – Parameter displacement from the expansion point, with shape (p,).

  • covariance_rcond – Relative cutoff used for the covariance pseudoinverse square root. Defaults to 1e-12.

Returns:

Dictionary with response_norms (covariance weighted norm of each Taylor response contribution), relative_response_strength (higher order norms divided by the linear norm), linear_response_norm, and total_response_norm (norm of the sum of available Taylor contributions).

If the linear norm is zero, a positive higher order norm produces an infinite ratio, while zero divided by zero produces NaN.

Raises:

ValueError – If the derivative dictionary is missing order 1, includes unsupported orders, or contains invalid tensor shapes or values; if the displacement is invalid; or if the covariance is not positive semidefinite within tolerance.

Notes

At displacement \(\Delta\theta\), the order k model response contribution is

\[r_k = \frac{1}{k!}\nu_{,i_1\ldots i_k} \Delta\theta_{i_1}\cdots\Delta\theta_{i_k}.\]

Its noise-weighted norm is

\[\|r_k\|_{C^+} = \sqrt{r_k^{\mathsf T}C^+r_k},\]

and the relative nonlinear response strength is

\[R_k = \frac{\|r_k\|_{C^+}}{\|r_1\|_{C^+}}.\]

These are directional diagnostics of the model response, not diagnostics of the assembled DALI likelihood tensors and not guarantees of convergence or posterior accuracy. They depend on the chosen displacement.

derivkit.utils.diagnostics.fisher_diagnostics(fisher: ArrayLike, *, jacobian: ArrayLike | None = None, cov: ArrayLike | None = None, rtol: float | None = None, covariance_rcond: float = 1e-12) → dict[str, Any]#

Compute Fisher matrix and optional noise-weighted sensitivity diagnostics.

Parameters:

  • fisher – Symmetric Fisher information matrix of shape (p, p).

  • jacobian – Optional model Jacobian of shape (n_observables, p). Must be provided together with cov, or both omitted.

  • cov – Optional positive semidefinite observational covariance of shape (n_observables, n_observables). Must be provided together with jacobian, or both omitted.

  • rtol – Relative cutoff for matrix and Jacobian numerical ranks. The default is dimension dependent for each calculation.

  • covariance_rcond – Relative eigenvalue cutoff used when forming the covariance pseudoinverse square root. Defaults to 1e-12.

Returns:

The dictionary from matrix_diagnostics(). If jacobian and cov are provided, also includes jacobian_singular_values, jacobian_rank, and jacobian_condition_number.

Raises:

ValueError – If inputs have invalid shapes or values, only one of jacobian and cov is supplied, or the covariance has a significantly negative eigenvalue.

Notes

For a parameter independent covariance, the Fisher matrix is

\[F = J^{\mathsf T} C^{+} J,\]

where + denotes a pseudoinverse when necessary. The whitened Jacobian is W = C^{+/2} J. Its singular values satisfy W.T @ W = J.T @ C^+ @ J. When the covariance is strictly positive definite, this agrees with the usual Fisher expression.

Numerical ranks of F and W can differ because forming F squares singular values. The supplied fisher is not checked against J.T @ C^+ @ J.

derivkit.utils.diagnostics.matrix_diagnostics(matrix: ArrayLike, *, rtol: float | None = None) → dict[str, Any]#

Compute eigenvalue diagnostics for a symmetric matrix.

Parameters:

  • matrix – Nonempty symmetric matrix of shape (p, p).

  • rtol – Relative eigenvalue cutoff for numerical rank and positive semidefiniteness. Defaults to p * eps for float64 precision.

Returns:

Dictionary with eigenvalues (ascending), eigenvectors (columns corresponding to eigenvalues), condition_number (ratio of largest to smallest absolute eigenvalue, or infinity if numerically rank deficient), rank, and is_positive_semidefinite.

Raises:

ValueError – If the matrix is empty, nonsquare, nonfinite, or nonsymmetric, or if rtol is invalid.

Notes

Rank and conditioning depend on parameter scaling and tolerance. An eigenvalue is counted as nonzero only if its absolute value exceeds rtol * max(abs(eigenvalues)). A zero matrix has rank zero and infinite condition number.