derivkit package¶

Subpackages¶

derivkit.adaptive package
- Submodules
- Module contents
derivkit.calculus package
- Submodules
- Module contents
derivkit.forecasting package
- Submodules
  - derivkit.forecasting.expansions module
    - LikelihoodExpansion
    - mixed_partial_path()
  - derivkit.forecasting.likelihoods module
- Module contents
derivkit.local_polynomial_derivative package
- Submodules
- Module contents
derivkit.utils package
- Submodules
- Module contents

Module contents¶

Provides all derivkit methods.

class derivkit.AdaptiveFitDerivative(func, x0: float)¶

Bases: object

Derivative estimation via a single local polynomial fit around x0.

Initialize the estimator.

Parameters:

func – Callable mapping a float to a scalar or 1D array-like output.
x0 – Expansion point about which derivatives are computed.

Compute the derivative of specified order at x0 using an adaptive polynomial fit.

Sampling strategy:

grid=None: symmetric Chebyshev offsets around x0 with half-width from spacing.
grid=(“offsets”, arr): explicit offsets t; samples at x = x0 + t (0 inserted if missing).
grid=(“absolute”, arr): explicit absolute x positions; samples at x = arr.

Parameters:

order – Derivative order (>=1).
n_points – Number of sample points when building the default grid. Default is 10.
spacing –
Scale for the default symmetric grid around x0 (ignored when grid is provided).

Accepted forms:
- float: interpreted as an absolute half-width h; samples in [x0 - h, x0 + h].
- ”<pct>%”: percentage string; h is that fraction of a local scale set by abs(x0) with a floor base_abs near zero.
- ”auto”: choose h adaptively. DerivKit picks a half-width based on the local scale of x0 with a minimum of base_abs; if domain is given, the interval is clipped to stay inside (lo, hi). The default grid uses Chebyshev nodes on that interval and always includes the center point.
base_abs – Absolute spacing floor used by “auto”/percentage near x0≈0. Defaults to 1e-3 if not set.
n_workers – Parallel workers for batched function evals (1 = serial).
grid –
Either (“offsets”, array) or (‘absolute’, array), or None for default.

This lets the user supply their own sampling points instead of using the automatically built Chebyshev grid. With ("offsets", arr), the array gives relative offsets from x0 (samples at x = x0 + t). With ('absolute', arr), the array gives absolute x positions. If None, the method builds a symmetric default grid around x0.
domain – Optional (lo, hi) used to trigger domain-aware transforms in default mode.
ridge –
Ridge regularization for polynomial fit. Defaults to 0.0.

This term adds a small penalty to the fit to keep the coefficients from becoming too large when the Vandermonde matrix is nearly singular. Increasing ridge makes the fit more stable but slightly smoother; setting it to 0 disables the regularization. Default is 0.0.
diagnostics – If True, return (derivative, diagnostics_dict).
meta – Extra metadata to carry in diagnostics.

Returns:

Derivative at x0 (scalar or 1D array). If diagnostics=True, also returns a dict.

Raises:

ValueError – If inputs are invalid or not enough samples are provided.

class derivkit.CalculusKit(function: Callable[[Sequence[float] | ndarray], float | ndarray[tuple[Any, ...], dtype[floating]]], x0: Sequence[float] | ndarray)¶

Bases: object

Provides access to gradient, Jacobian, and Hessian tensors.

Initialises class with function and expansion point.

Parameters:

function – The function to be differentiated. Accepts a 1D array-like. Must return either a scalar (for gradient/Hessian) or a 1D array (for Jacobian).
x0 – Point at which to evaluate derivatives (shape (P,)).

gradient(*args, **kwargs) → ndarray[tuple[Any, ...], dtype[floating]]¶: Returns the gradient of a scalar-valued function.

hessian(*args, **kwargs) → ndarray[tuple[Any, ...], dtype[floating]]¶: Returns the Hessian of a scalar-valued function.

hessian_diag(*args, **kwargs) → ndarray[tuple[Any, ...], dtype[floating]]¶: Returns the diagonal of the Hessian of a scalar-valued function.

jacobian(*args, **kwargs) → ndarray[tuple[Any, ...], dtype[floating]]¶: Returns the Jacobian of a vector-valued function.

class derivkit.DerivativeKit(function: Callable[[float], Any], x0: float)¶

Bases: object

Unified interface for computing numerical derivatives.

The class provides a simple way to evaluate derivatives using any of DerivKit’s available backends (e.g., adaptive fit or finite difference). You only need to supply a function and the point x0 at which to compute the derivative. By default, the adaptive-fit method is used.

Example

>>> import numpy as np
>>> from derivkit.derivative_kit import DerivativeKit
>>> d = DerivativeKit(np.cos, x0=1.0)
>>> d.differentiate(order=1)  # uses the default "adaptive" method

function¶: The callable to differentiate.

x0¶: The point at which the derivative is evaluated.

DEFAULT_METHOD¶: The default backend used when no method is specified.

Initializes the DerivativeKit with a target function and expansion point.

Parameters:

function – The function to be differentiated. Must accept a single float and return a scalar or array-like output.
x0 – Point at which to evaluate the derivative.

differentiate(*, method: str = None, **kwargs: Any) → Any¶

Compute derivatives using the chosen method.

Forwards all keyword arguments to the engine’s .differentiate().

Parameters:

method – Method name or alias (e.g., “adaptive”, “finite”, “fd”). Default is “adaptive”.
**kwargs – Passed through to the chosen engine.

Returns:

The derivative result from the underlying engine.

Raises:

ValueError – If method is not recognized.

class derivkit.FiniteDifferenceDerivative(function: Callable, x0: float)¶

Bases: object

Computes numerical derivatives using central finite difference stencils.

This class supports the calculation of first to fourth-order derivatives for scalar or vector-valued functions. It uses high-accuracy central difference formulas with configurable stencil sizes (3-, 5-, 7-, or 9-point).

For scalar-valued functions, a single float is returned. For vector-valued functions, the derivative is computed component-wise and returned as a NumPy array.

function¶: The function to differentiate. Must accept a single float and return either a float or a 1D array-like object.

x0¶: The point at which the derivative is evaluated.

Supported Stencil and Derivative Combinations¶

3-point: first-order only
5-point: first to fourth-order
7-point: first and second-order
9-point: first and second-order

Examples:¶

>>> f = lambda x: x**3
>>> d = FiniteDifferenceDerivative(function=f, x0=2.0)
>>> d.differentiate(order=2)

Initialises the class based on function and central value.

param function:: The function to differentiate. Must accept a single float and return either a float or a 1D array-like object.
param x0:: The point at which the derivative is evaluated.

differentiate(order: int = 1, stepsize: float = 0.01, num_points: int = 5, n_workers: int = 1, extrapolation: str | None = None, levels: int | None = None, return_error: bool = False) → ndarray[float] | float¶

Computes the derivative using a central finite difference scheme.

Supports 3-, 5-, 7-, or 9-point central difference stencils for derivative orders 1 through 4 (depending on the stencil size). Derivatives are computed for scalar or vector-valued functions. Allows for optional extrapolation (Richardson or Ridders) to improve accuracy. It also returns an error estimate if requested.

Parameters:

order – The order of the derivative to compute. Must be supported by the chosen stencil size. Default is 1.
stepsize – Step size (h) used to evaluate the function around the central value. Default is 0.01.
num_points – Number of points in the finite difference stencil. Must be one of [3, 5, 7, 9]. Default is 5.
n_workers – Number of workers to use in multiprocessing. Default is 1 (no multiprocessing).
extrapolation –
Extrapolation scheme to use for improving accuracy. Supported options are:
- None: no extrapolation (single finite difference).
- "richardson":
  
  fixed-level if levels is not None
  
  adaptive if levels is None
- "ridders":
  
  fixed-level if levels is not None
  
  adaptive if levels is None
levels – Number of extrapolation levels for fixed schemes. If None, the chosen extrapolation method runs in adaptive mode where supported.
return_error – If True, also return an error estimate from the extrapolation (or two-step) routine.

Returns:

The estimated derivative. Returns a float for scalar-valued functions, or a NumPy array for vector-valued functions.

Raises:

ValueError – If the combination of num_points and order is not supported or if an unknown extrapolation scheme is given.

Notes

The available (num_points, order) combinations are:

3: order 1
5: orders 1, 2, 3, 4
7: orders 1, 2
9: orders 1, 2

class derivkit.ForecastKit(function: Callable[[Sequence[float] | ndarray], ndarray], theta0: Sequence[float] | ndarray, cov: ndarray)¶

Bases: object

Provides access to Fisher and DALI likelihood-expansion tensors.

Initialises the forecaster with model, fiducials, and covariance.

Parameters:

function – Model mapping parameters to observables (1D array-like in, 1D array out).
theta0 – Fiducial parameter values (shape (P,)). Here, P is the number of model parameters (P = len(theta0))
cov – Observables covariance (shape (N, N)). N is the number of observables (N = cov.shape[0])

dali(*, method: str | None = None, n_workers: int = 1, dk_kwargs: dict | None = None) → tuple[ndarray, ndarray]¶

Return the doublet-DALI tensors (G, H).

Shapes are (P,P,P) and (P,P,P,P), where P is the number of model parameters.

delta_nu(data_with: ndarray, data_without: ndarray)¶: Return the delta_nu vector with shape (N,) with N being the number of observables.

fisher(*, method: str | None = None, n_workers: int = 1, dk_kwargs: dict | None = None) → ndarray¶: Return the Fisher information matrix with shape (P, P) with P being the number of model parameters.

fisher_bias(*, fisher_matrix: ndarray, delta_nu: ndarray, method: str | None = None, n_workers: int = 1, dk_kwargs: dict | None = None, rcond: float = 1e-12) → tuple[ndarray, ndarray]¶: Return the Fisher bias vector with shape (P,) with P being the number of model parameters.

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.

theta0¶: The point(s) 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.

n_parameters¶: The number of elements of theta0.

n_observables¶: The number of cosmic observables. Determined from the dimension of cov.

Initialises the class.

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.

Raises:

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

build_delta_nu(data_with: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]], data_without: ~numpy.ndarray[tuple[~typing.Any, ...], ~numpy.dtype[~numpy.floating]], *, dtype: type | ~numpy.dtype = <class 'float'>) → ndarray[tuple[Any, ...], dtype[floating]]¶

Compute the difference between two data vectors.

This function is typically used for Fisher-bias estimates, taking two data vectors— one with a systematic included and one without—and returning their difference as a 1D array that matches the expected number of observables in this instance. It works with both 1D inputs and 2D arrays (for example, correlation × ell) and flattens 2D arrays using NumPy’s row-major (“C”) order, our standard convention throughout the package.

We standardize on row-major (“C”) flattening of 2D arrays, where the last axis varies fastest. The user must ensure that any data vectors and associated covariances are constructed with the same convention for consistent results.

Parameters:

data_with – Data vector that includes the systematic effect. Can be 1D or 2D. If 1D, it must follow the NumPy’s row-major (“C”) flattening convention used throughout the package.
data_without – Reference data vector without the systematic. Can be 1D or 2D. If 1D, it must follow the NumPy’s row-major (“C”) flattening convention used throughout the package.
dtype – Data type of the output array (defaults to float).

Returns:

A 1D NumPy array of length self.n_observables representing the data mismatch (delta_nu = data_with − data_without).

Raises:

ValueError – If input shapes differ, inputs are not 1D/2D, or the flattened length does not match self.n_observables.
FloatingPointError – If non-finite values are detected in the result.

build_fisher_bias(fisher_matrix: ndarray[tuple[Any, ...], dtype[floating]], delta_nu: ndarray[tuple[Any, ...], dtype[floating]], n_workers: int = 1, method: str | None = None, dk_kwargs: dict | None = None, rcond: float = 1e-12) → tuple[ndarray[tuple[Any, ...], dtype[floating]], ndarray[tuple[Any, ...], dtype[floating]]]¶

Estimate parameter bias using the stored model, expansion point, and covariance.

This method quantifies how differences between two data sets (for example, a fiducial prediction and one affected by a systematic) propagate into parameter biases when interpreted through a Fisher forecast. It evaluates the model response internally and uses it, together with the stored covariance and provided Fisher matrix, to estimate both the bias vector and the resulting shift in parameter values. For more information, see https://arxiv.org/abs/0710.5171.

Parameters:

fisher_matrix – Square matrix describing information about the parameters. Its shape must be (p, p), where p is the number of parameters.
delta_nu – Difference between two data vectors (for example, with and without a systematic). Accepts a 1D array of length n or a 2D array that will be flattened in row-major order (“C”) to length n, where n is the number of observables. If supplied as a 1D array, it must already follow the same row-major (“C”) flattening convention used throughout the package.
n_workers – Number of workers used by the internal derivative routine when forming the Jacobian.
method – Method name or alias (e.g., “adaptive”, “finite”). If None, the DerivativeKit default (“adaptive”) is used.
dk_kwargs – Additional keyword arguments passed to DerivativeKit.differentiate.
rcond – Regularization cutoff for pseudoinverse. Default is 1e-12.

Returns:

bias_vec: parameter-space bias vector.
delta_theta: estimated parameter shifts.

Return type:

A tuple (bias_vec, delta_theta) where both entries are 1D arrays of length p

Raises:

ValueError – If input shapes are inconsistent with the stored model, covariance, or the Fisher matrix dimensions.
FloatingPointError – If the difference vector contains NaNs.

get_forecast_tensors(forecast_order: int = 1, method: str | None = None, n_workers: int = 1, dk_kwargs: dict | None = None) → 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:

forecast_order –
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.
method – Method name or alias (e.g., “adaptive”, “finite”). If None, the 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 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.

derivkit.register_method(name: str, cls: Type[DerivativeEngine], *, aliases: Iterable[str] = ()) → None¶

Adds a new derivative engine that can be referenced by name in DerivativeKit. This function can be called from anywhere in the package (for example, inside a submodule’s __init__.py) and is safe regardless of import order. The internal cache is automatically cleared and rebuilt on the next lookup.

Parameters:

name – Canonical public name of the method (e.g., “gp”).
cls – Engine class implementing the DerivativeEngine protocol.
aliases – Additional accepted spellings (e.g., “gaussian-process”).

Example

>>> from derivkit.derivative_api import register_method
>>> from derivkit.gp.gp_derivative import GPDerivative
>>> register_method(
...     name="gp",
...     cls=GPDerivative,
...     aliases=("gaussian-process", "gaussproc"),
... )
>>> # After registration, it can be used via:
>>> # DerivativeKit(f, x0).differentiate(method="gp")

derivkit package¶

Subpackages¶

Submodules¶

Module contents¶

Supported Stencil and Derivative Combinations¶

Examples:¶