derivkit.forecast_kit module

Provides tools for facilitating experimental forecasts.

The user must specify the observables, fiducial values and covariance matrix at which the derivative should be evaluated. Derivatives of the first order are Fisher derivatives. Derivatives of second order are evaluated using the derivative approximation for likelihoods (DALI) technique as described in https://doi.org/10.1103/PhysRevD.107.103506.

More details about available options can be found in the documentation of the methods.

Typical usage example:

>>>    forecaster = ForecastKit(observables, fiducial_values, covariance_matrix)
>>>    fisher = forecaster.get_derivatives(derivative_order = 1)
>>>    dali = forecaster.get_derivatives(derivative_order = 2)

class derivkit.forecast_kit.ForecastKit(function, central_values, covariance_matrix)

Bases: object

Provides tools for facilitating experimental forecasts.

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.

Type:

callable

central_values (class

np.ndarray): The point(s) at which the derivative is evaluated. A 1D array or list of parameter values matching the expected input of the function.

covariance_matrix (class

np.ndarray): 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.

n_parameters

The number of elements of central_values.

Type:

int

n_observables

The number of cosmic observables. Determined from the dimension of covariance_matrix.

Type:

int

Initialises the class.

Parameters:

• function (callable) – 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.

• (class (covariance_matrix) – np.ndarray): The points at which the derivative is evaluated. A 1D array or list of parameter values matching the expected input of the function.

• (class – np.ndarray): 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.

Raises:

ValueError – raised if covariance_matrix is not a square numpy array.

get_derivatives(derivative_order, n_workers=1)

Returns derivatives of the observables of the requested order.

Parameters:

• derivative_order (int) –

  The requested order d of the derivatives:

  • d = 1 returns first-order derivatives.

  • d = 2 returns second-order derivatives.

  Currently only d = 1, 2 are supported.

• n_workers (int, optional) – Number of worker to use in multiprocessing. Default is 1 (no multiprocessing).

Returns:

An array of derivative values:

• d = 1 returns an array with shape (n_parameters, n_observables) containing first-order derivatives.

• d = 2 returns an array with shape n_parameters, n_parameters, n_observables) containing second-order derivatives.

Return type:

np.ndarray

Raises:

• ValueError – An error occurred if a derivative was requested of higher order than 2.

• RuntimeError – An error occurred if a ValueError was not raised after calling the function.

get_forecast_tensors(forecast_order=1, n_workers=1)

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

Parameters:

• forecast_order (int) –

  The requested order D of the forecast:

  • D = 1 returns a Fisher matrix.

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

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

  Currently only D = 1, 2 are supported.

• n_workers (int, optional) – Number of worker to use in multiprocessing. Default is 1 (no multiprocessing).

Returns:

A list of numpy arrays:

• D = 1 returns a square matrix of size n_parameters, where n_parameters is the number of parameters included in the forecast.

• D = 2 returns one array of shapes (n_parameters, n_parameters, n_parameters) and one array of shape (n_parameters, n_parameters, n_parameters, n_parameters), where n_parameters is the number of parameters included in the forecast.

Return type:

np.ndarray

Raises:

• ValueError – A ValueError occurs when a forecase order greater than 2 is requested.

• Exception – An exception occurs if the covariance matrix cannot be inverted.

• RunTimeError – A RunTimeError occurs if the ValueError was not raised when calling this function.