derivkit.forecasting.sampling_utils module#

Gaussian sampling-kernel helpers derived from a Fisher matrix.

This module implements a Fisher-based Gaussian sampling distribution q centered at theta0 with covariance:

(kernel_scale**2) * pinv(F)

where F is the Fisher information matrix evaluated at theta0. In this approximation, F is the Hessian of -log L at theta0 and acts as the local inverse covariance.

This kernel is used to generate candidate points and, for importance sampling, to evaluate log(q) when sampling posteriors approximated with Fisher or DALI.

For importance sampling, log(q) is subtracted from the target log-posterior to form log-weights.

It provides:

  • construction of Fisher-based sampling covariances,

  • stabilized Cholesky factorization for near-singular kernels,

  • sampling and log-density evaluation of the kernel,

  • fast bounds rejection masks,

  • MCMC walker initialization under sampler bounds.

These utilities do not depend on a specific sampler implementation. They provide kernel draws, log-densities, and bounds filtering that are called by the GetDist importance-sampling wrappers and by the emcee walker initialization routine.

derivkit.forecasting.sampling_utils.apply_parameter_bounds(samples: ndarray[tuple[Any, ...], dtype[floating]], parameter_bounds: Sequence[tuple[float | None, float | None]] | None) → ndarray[tuple[Any, ...], dtype[float64]]#

Applies per-parameter bounds to a set of samples.

This function performs a fast, axis-aligned rejection step: any sample with at least one parameter value outside the specified bounds is discarded. It does not evaluate priors or compute weights.

Parameters:

  • samples – Sample array with shape (n_samples, p) with p parameters.

  • parameter_bounds – Optional sequence of (lower, upper) bounds, one per parameter. Use None to indicate an unbounded side (e.g. (0.0, None)). If None, no filtering is applied.

Returns:

Samples satisfying all bounds, with shape (n_kept, p). n_kept may be zero.

Raises:

ValueError – If parameter_bounds is provided but does not have length p.

derivkit.forecasting.sampling_utils.fisher_to_cov(fisher: ndarray[tuple[Any, ...], dtype[floating]], *, rcond: float | None = None) → ndarray[tuple[Any, ...], dtype[float64]]#

Converts a Fisher matrix to a covariance matrix using pseudoinverse.

Parameters:

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

  • rcond – Cutoff ratio for small singular values in pseudoinverse. If None, the default from np.linalg.pinv is used.

Returns:

Covariance matrix with shape (p, p) given by pinv(fisher).

Raises:

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

derivkit.forecasting.sampling_utils.init_walkers_from_fisher(theta0: ndarray[tuple[Any, ...], dtype[floating]], fisher: ndarray[tuple[Any, ...], dtype[floating]], *, n_walkers: int, init_scale: float, seed: int | None, sampler_bounds: Sequence[tuple[float | None, float | None]] | None) → ndarray[tuple[Any, ...], dtype[float64]]#

Returns initial MCMC walker positions from a Fisher-based Gaussian sampling kernel.

Returns an array of walker positions centered at theta0 with scatter set by a Fisher-derived covariance (init_scale^2) * pinv(F). If sampler_bounds are provided, positions outside the bounds are rejected and additional candidates are generated until n_walkers positions are collected or a retry limit is reached.

Parameters:

  • theta0 – Kernel mean with shape (p,) with p parameters.

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

  • n_walkers – Number of walker positions to return.

  • init_scale – Multiplicative scale applied to the kernel covariance.

  • seed – Optional random seed for reproducible initialization.

  • sampler_bounds – Optional per-parameter (lower, upper) bounds. Use None for an unbounded side.

Returns:

Array of initial positions with shape (n_walkers, p).

Raises:

  • ValueError – If theta0 and fisher have incompatible shapes.

  • ValueError – If sampler_bounds is provided and does not have length p.

  • RuntimeError – If sufficient in-bounds positions cannot be generated within the retry limit.

derivkit.forecasting.sampling_utils.kernel_cov_from_fisher(fisher: ndarray[tuple[Any, ...], dtype[floating]], *, kernel_scale: float) → ndarray[tuple[Any, ...], dtype[float64]]#

Returns the covariance of the Fisher-based Gaussian sampling kernel.

This is a thin wrapper around derivkit.forecasting.integrations.sampling_utils.fisher_to_cov() that converts fisher to a covariance via pseudoinverse and applies the scaling kernel_scale^2.

The Fisher matrix is treated as the Hessian of -log L at theta0. In this local approximation it acts as an inverse covariance, and kernel_scale controls the overall kernel width. A pseudoinverse is used so the covariance is defined even if fisher is singular.

Parameters:

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

  • kernel_scale – Multiplicative scale factor applied to the covariance. Increasing values widen the kernel; decreasing values narrow it.

Returns:

Kernel covariance matrix with shape (p, p), equal to (kernel_scale^2) * fisher_to_cov(fisher).

Raises:

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

derivkit.forecasting.sampling_utils.kernel_samples_from_fisher(theta0: ndarray[tuple[Any, ...], dtype[floating]], fisher: ndarray[tuple[Any, ...], dtype[floating]], *, n_samples: int, kernel_scale: float, seed: int | None) → ndarray[tuple[Any, ...], dtype[float64]]#

Draws samples from a Fisher-based Gaussian sampling kernel.

Samples are drawn from the Gaussian kernel density q(theta) with mean theta0 and covariance (kernel_scale^2) * pinv(F):

q(theta) = Normal(mean=theta0, cov=(kernel_scale^2) * pinv(F))

F is the Fisher information matrix evaluated at theta0. In this approximation, F acts as an inverse covariance and Normal represents the multivariate normal distribution. A pseudoinverse is used so the covariance is defined even if F is singular or ill-conditioned.

Parameters:

  • theta0 – Kernel mean with shape (p,) with p parameters.

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

  • n_samples – Number of samples to draw.

  • kernel_scale – Multiplicative scale applied to the covariance. Increasing values widen the kernel; decreasing values narrow it.

  • seed – Optional random seed for reproducible draws.

Returns:

Array of samples with shape (n_samples, p).

derivkit.forecasting.sampling_utils.log_gaussian_kernel(samples: ndarray[tuple[Any, ...], dtype[floating]], theta0: ndarray[tuple[Any, ...], dtype[floating]], fisher: ndarray[tuple[Any, ...], dtype[floating]], *, kernel_scale: float) → ndarray[tuple[Any, ...], dtype[float64]]#

Log-density of a Fisher-based Gaussian sampling kernel.

Defines a Gaussian kernel q with mean theta0 and covariance

(kernel_scale^2) * pinv(F)

where F is the Fisher information matrix. The covariance is formed with a pseudoinverse (allowing singular or ill-conditioned F). A small diagonal jitter is added before evaluating the log-density so the calculation remains well-defined for near-singular covariances.

Parameters:

  • samples – Sample locations with shape (n_samples, p).

  • theta0 – Kernel mean with shape (p,).

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

  • kernel_scale – Multiplicative scale applied to the covariance.

Returns:

Log of the kernel probability density log(q(theta)), evaluated at each sample point, with shape (n_samples,).

Raises:

  • ValueError – If input shapes are incompatible.

  • RuntimeError – If the jittered covariance is not positive-definite.

derivkit.forecasting.sampling_utils.stabilized_cholesky(cov: ndarray[tuple[Any, ...], dtype[floating]]) → ndarray[tuple[Any, ...], dtype[float64]]#

Returns a Cholesky factor of a covariance matrix.

This function computes a lower-triangular matrix L such that cov is approximately L @ L.T, even when cov is nearly singular or only positive semi-definite.

Parameters:

cov – Covariance matrix with shape (p, p) with p parameters.

Returns:

A lower-triangular Cholesky factor L of the regularized covariance.

Raises:

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