`virgil.inference`

Local curvature tools: Hessians, Laplace covariances and Fisher matrices.

The observed information is the Hessian of the negative log likelihood at a point (observed_information for a model and data, hessian_matrix for a flat objective). The expected Fisher matrix is Jᵀ Σ⁻¹ J for a prediction with fixed Gaussian errors (expected_fisher); the two agree at the maximum of a linear-Gaussian problem. The Laplace covariance is the inverse of the observed information: laplace_cov for a model and data, and objective_laplace_covariance for a flat objective.

Objectives are negative log likelihoods of a flat 1D parameter vector, except for expected_fisher, which accepts any parameter pytree. Checks that need concrete values are skipped inside jax.jit.

`laplace_cov(values, params, model, data, *, dtype='float64')`

Compute the full Laplace covariance matrix for all model parameters jointly.

The inverse of the Hessian of the negative log-likelihood with respect to all parameters in params simultaneously, an N x N matrix. A path may be array-valued (e.g. "rim.az_amps"): then values is the flat concatenation of every path's elements (each flattened C-order), N is the total number of elements, and the template must be a SourceModel whose leaves give the sizes. For the uncertainty of one parameter with the others held fixed, use laplace_parameter_uncertainty.

Parameters:

Name	Type	Description	Default
`values`	`array - like`	1D flat parameter vector: the elements of each path in `params`, concatenated in order.	required
`params`	`list`	List of parameter names.	required
`model`	`SourceModel or callable`	Template model whose parameters at the dot-separated paths `params` are replaced by `values`, or a class/callable called as `model(**dict(zip(params, values)))` (see `build_model`); a callable takes scalar parameters only.	required
`data`	`OIData`	Object containing the data to be fitted.	required
`dtype`	`(float64, float32)`	Precision of the calculation, as for `fit`.	`"float64"`

Returns:

Type	Description
`array - like`	`N x N` covariance matrix over the flattened parameter elements.

`laplace_parameter_uncertainty(values, params, model, data, target_param, *, dtype='float64')`

Compute scalar Laplace uncertainty for one parameter with all others fixed.

Parameters:

Name	Type	Description	Default
`values`	`array - like`	Flat parameter vector at which to evaluate the curvature (the elements of every path in `params`, concatenated in order, as for `laplace_cov`).	required
`params`	`list[str]`	Parameter paths corresponding to `values`.	required
`model`	`SourceModel or callable`	Template model or class, as for `loglike`.	required
`data`	`OIData`	Data to fit.	required
`target_param`	`str`	The scalar parameter whose uncertainty is returned (a path whose template leaf has more than one element is rejected).	required
`dtype`	`(float64, float32)`	Precision of the calculation, as for `laplace_cov`.	`"float64"`

Returns:

Type	Description
`float`	`(d² -log L / d target²)^(-1/2)`. It is NaN where the curvature is not positive, i.e. away from a likelihood maximum along `target_param`.

`observed_information(values, params, model, data, ridge=0.0, *, dtype='float64')`

Observed information (Hessian of -log L) at a parameter point.

At the maximum-likelihood point this approximates the Fisher matrix (for the expected Fisher matrix of a fixed-error prediction, see expected_fisher).

Parameters:

Name	Type	Description	Default
`values`	`array - like`	Flat parameter vector at which to evaluate the local curvature (the elements of every path in `params`, concatenated in order, as for `laplace_cov`).	required
`params`	`list[str]`	Parameter paths corresponding to `values`.	required
`model`	`SourceModel or callable`	Template model whose parameters at the dot-separated paths `params` are replaced by `values`, or a class/callable called as `model(**dict(zip(params, values)))` (see `build_model`).	required
`data`	`OIData`	Observational data object.	required
`ridge`	`float`	Diagonal regularization term.	`0.0`
`dtype`	`(float64, float32)`	Precision of the calculation, as for `laplace_cov`.	`"float64"`

Returns:

Type	Description
`array - like`	Observed information matrix, `N x N` for `N` the total number of parameter elements.

`hessian_matrix(objective, x)`

Return the Hessian matrix of objective evaluated at x.

x must be a flat 1D parameter vector; use jax.flatten_util.ravel_pytree to flatten a pytree first.

`regularized_inverse(matrix, ridge=1e-10)`

Return the inverse of matrix, regularized only if it is not positive definite.

A positive-definite matrix (a Hessian at a likelihood maximum) is inverted as it is, whatever the scales of its parameters. Otherwise ridge * |matrix_ii| is added to each diagonal entry first (the largest |matrix_ii| for a zero one, 1 if all are zero): a ridge relative to each parameter's own curvature, so it does not depend on the units of the parameters. A parameter the data do not constrain then has a large variance set by the ridge, not the data. A RuntimeWarning is raised (outside jax.jit) when the ridge was needed, and when even the regularized matrix is not positive definite, since its inverse is then not a covariance.

`objective_laplace_covariance(objective, x, ridge=1e-10)`

Return the Laplace covariance, the inverse Hessian of objective.

For a model and data use laplace_cov. objective is a negative log likelihood of the flat vector x, which should be at (or near) its minimum. A relative ridge (default 1e-10 of each diagonal entry) is added to the diagonal only if the Hessian is not positive definite; see regularized_inverse.

`expected_fisher(prediction_fn, params, errors, ridge=0.0)`

Return expected Fisher information for fixed independent Gaussian errors.

Not the Hessian of a likelihood: for that, see observed_information.

Parameters:

Name	Type	Description	Default
`prediction_fn`	`callable`	Function mapping the parameter pytree to a one-dimensional prediction.	required
`params`	`pytree`	Parameter values at which to evaluate the local model sensitivity.	required
`errors`	`array - like`	Standard deviations corresponding to the prediction vector.	required
`ridge`	`float`	Diagonal regularization term.	`0.0`

Returns:

Type	Description
`tuple[array - like, callable]`	Expected Fisher matrix `Jᵀ Σ⁻¹ J` and a function restoring a flat parameter vector to the structure of `params`.

`fisher_projection(fmat, eps=1e-12)`

Return projection matrix mapping unit-normal latent vectors to parameter steps.

If u ~ N(0, I), then x = x0 + P @ u has local covariance approximately F^{-1} for Fisher matrix F.

Parameters:

Name	Type	Description	Default
`fmat`	`array - like`	Symmetric Fisher (or observed information) matrix.	required
`eps`	`float`	Eigenvalues below `eps` times the largest eigenvalue (or below `eps` itself, if every eigenvalue is zero) are raised to that floor, with a `RuntimeWarning` (outside `jax.jit`), so that flat directions get large but finite steps.	`1e-12`

Returns:

Type	Description
`array - like`	`P = V diag(λ^-1/2)`, so that `P Pᵀ = F⁻¹`.