derivkit.forecasting.forecast_core module#

Core utilities for likelihoods-based forecasts.

This module provides functional helpers to

  • compute first- and second-order derivatives of a model with respect to its parameters, and

  • build Fisher and doublet-DALI forecast tensors from those derivatives and a covariance matrix.

These functions are the low-level building blocks used by higher-level forecasting interfaces in DerivKit. For details on the DALI expansion, see e.g. https://doi.org/10.1103/PhysRevD.107.103506.

derivkit.forecasting.forecast_core.get_forecast_tensors(function: Callable[[ArrayLike], float | ndarray[tuple[Any, ...], dtype[floating]]], theta0: ArrayLike, cov: ArrayLike, *, forecast_order: int = 1, method: str | None = None, n_workers: int = 1, **dk_kwargs: Any) → ndarray[tuple[Any, ...], dtype[float64]] | tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]]#

Returns a set of tensors according to the requested order of the forecast.

Parameters:

  • function – The scalar or vector-valued function to differentiate. It should accept a list or array of parameter values as input and return either a scalar or a np.ndarray of observable values.

  • theta0 – The points at which the derivative is evaluated. A 1D array or list of parameter values matching the expected input of the function.

  • cov – The covariance matrix of the observables. Should be a square matrix with shape (n_observables, n_observables), where n_observables is the number of observables returned by the function.

  • forecast_order –

    The requested order D of the forecast:

    • D = 1 returns a Fisher matrix.

    • D = 2 returns the 3D and 4D tensors required for the doublet-DALI approximation.

    • D = 3 would be the triplet-DALI approximation.

    Currently only D = 1, 2 are supported.

  • method – Method name or alias (e.g., "adaptive", "finite"). If None, the derivkit.derivative_kit.DerivativeKit default ("adaptive") is used.

  • n_workers – Number of workers for per-parameter parallelization/threads. Default 1 (serial). Inner batch evaluation is kept serial to avoid nested pools.

  • **dk_kwargs – Additional keyword arguments passed to derivkit.derivative_kit.DerivativeKit.differentiate.

Returns:

Fisher matrix of shape (P, P). If D = 2: tuple (G, H) with shapes (P, P, P) and (P, P, P, P).

Return type:

If D = 1

Raises:

ValueError – If forecast_order is not 1 or 2.

Warns:

RuntimeWarning – If cov is not symmetric (proceeds as-is, no symmetrization), is ill-conditioned (large condition number), or inversion falls back to the pseudoinverse.