derivkit.forecasting.forecast_core module#

Core utilities for likelihoods-based forecasts.

This module provides functional helpers to

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

  • build Fisher, doublet-DALI, and triplet-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.SUPPORTED_FORECAST_ORDERS = (1, 2, 3)#

The supported orders of the DALI expansion.

A value of 1 corresponds to the Fisher matrix. A value of 2 corresponds to the DALI doublet. A value of 3 corresponds to the DALI triplet.

derivkit.forecasting.forecast_core.get_forecast_tensors(function: Callable[[Sequence[float] | ndarray[tuple[Any, ...], dtype[floating]]], float | ndarray[tuple[Any, ...], dtype[floating]]], theta0: Sequence[float] | ndarray[tuple[Any, ...], dtype[floating]], cov: Sequence[Sequence[float]] | ndarray[tuple[Any, ...], dtype[floating]], *, forecast_order: int = 1, method: str | None = None, n_workers: int = 1, **dk_kwargs: Any) → dict[int, tuple[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 of the forecast. Currently supported values and their meaning are given in SUPPORTED_FORECAST_ORDERS.

  • 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:

A dict mapping order -> tensors for all order = 1..forecast_order.

The tensors are grouped by the forecast order at which they first appear:

  • order 1: (F,)

  • order 2: (D_{(2,1)}, D_{(2,2)})

  • order 3: (T_{(3,1)}, T_{(3,2)}, T_{(3,3)})

Here D_{(k,l)} and T_{(k,l)} denote tensors obtained by contracting the k-th order derivative with the l-th order derivative via the inverse covariance.

Each tensor axis has length p = len(theta0). Shapes are:

  • F: (p, p)

  • D_{(2,1)}: (p, p, p)

  • D_{(2,2)}: (p, p, p, p)

  • T_{(3,1)}: (p, p, p, p)

  • T_{(3,2)}: (p, p, p, p, p)

  • T_{(3,3)}: (p, p, p, p, p, p)

Raises:

ValueError – If forecast_order is not in SUPPORTED_FORECAST_ORDERS.

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.