Reference

jacobi.jacobi(fn: Callable, x: float | Indexable[float], *args, diagonal: bool = False, method: int | None = None, mask: ndarray | None = None, rtol: float = 0, maxiter: int = 10, maxgrad: int = 3, step: Tuple[float, float] | None = None, diagnostic: dict | None = None) → Tuple[ndarray, ndarray]

Return first derivative and its error estimate.

Parameters:

  • fn (Callable) – Function with the signature fn(x, *args), where x is a number or a sequence of numbers and *args are optional auxiliary arguments. The function must return a number or a regular shape of numbers (ideally as a numpy array). The length of x can differ from the output sequence. Derivatives are only computed with respect to x, the auxiliary arguments are ignored.

  • x (Number or array of numbers) – The derivative is computed with respect to x. If x is an array, the Jacobi matrix is computed with respect to each element of x.

  • *args (tuple) – Additional arguments passed to the function.

  • diagonal (boolean, optional) – If it is known that the Jacobian computed from the function contains has off-diagonal entries that are all zero, the calculation can be speed up significantly. Set this to true to only compute the diagonal entries of the Jacobi matrix, which are returned as a 1D array. This is faster and uses much less memory if the vector x is very large. Default is False.

  • method ({-1, 0, 1} or None, optional) – Whether to compute central (0), forward (1) or backward derivatives (-1). The default (None) uses auto-detection.

  • mask (array or None, optional) – If x is an array and mask is not None, compute the Jacobi matrix only for the part of the array selected by the mask.

  • rtol (float, optional) – Relative tolerance for the derivative. The algorithm stops when this relative tolerance is reached. If 0 (the default), the algorithm iterates until the error estimate of the derivative does not improve further.

  • maxiter (int, optional) – Maximum number of iterations of the algorithm.

  • maxgrad (int, optional) – Maximum grad of the extrapolation polynomial.

  • step (tuple of float or None, optional) – Factors that reduce the step size in each iteration relative to the previous step.

  • diagnostic (dict or None, optional) – If an empty dict is passed to this keyword, it is filled with diagnostic information produced by the algorithm. This reduces performance and is only intended for debugging.

Returns:

Derivative and its error estimate.

Return type:

array, array

jacobi.propagate(fn: Callable, x: float | Indexable[float], cov: float | Indexable[float] | Indexable[Indexable[float]], *args, **kwargs) → Tuple[ndarray, ndarray]

Numerically propagates the covariance of function inputs to function outputs.

The function computes C’ = J C J^T, where C is the covariance matrix of the input, C’ the matrix of the output, and J is the Jacobi matrix of first derivatives of the mapping function fn. The Jacobi matrix is computed numerically.

Parameters:

  • fn (callable) – Function with the signature fn(x, [y, …]), where x is a number or a sequence of numbers, likewise if other arguments are present they must have the same format. The function must return a number or a sequence of numbers (ideally as a numpy array). The length of x can differ from the output sequence. The function should accept more than one argument only if there are no correlations between these arguments. See example below for use cases.

  • x (float or array-like with shape (N,)) – Input vector. An array-like is converted before passing it to the callable.

  • cov (float or array-like with shape (N,) or shape(N, N)) – Covariance matrix of input vector. If the array is one-dimensional, it is interpreted as the diagonal of a covariance matrix with zero off-diagonal elements.

  • *args – If the function accepts several arguments that are mutually independent, these is possible to pass those values and covariance matrices pairwise, see examples.

  • **kwargs – Extra arguments are passed to jacobi().

Returns:

y is the result of fn(x). ycov is the propagated covariance matrix. If ycov is a matrix, unless y is a number. In that case, ycov is also reduced to a number.

Return type:

y, ycov

Notes

For callables fn which perform only element-wise computation, the jacobian is a diagonal matrix. This special case is detected and the computation optimised, although can further speed up the computation by passing the argument diagonal=True.

In this special case, error propagation works correctly even if the output of fn is NaN for some inputs.

Examples

General error propagation maps input vectors to output vectors.

>>> def fn(x):
...     return x ** 2 + 1
>>> x = [1, 2]
>>> xcov = [[3, 1],
...         [1, 4]]
>>> y, ycov = propagate(fn, x, xcov)

In the previous example, the function y = fn(x) treats all x values independently and the Jacobian computed from fn(x) has zero off-diagonal entries. In this case, one can speed up the calculation significantly with a special keyword.

>>> y, ycov = propagate(fn, x, xcov, diagonal=True)

This produces the same result, but is faster and uses less memory. If the function accepts several arguments, their uncertainties are treated as uncorrelated.

>>> def fn(x, y):
...    return x + y
>>> x = 1
>>> y = 2
>>> xcov = 2
>>> ycov = 3
>>> z, zcov = propagate(fn, x, xcov, y, ycov)

Functions that accept several correlated arguments must be wrapped.

>>> def fn(x, y):
...     return x + y
>>> rho_xy = 0.5
>>> cov_xy = rho_xy * (xcov * ycov) ** 0.5
>>> r = [x, y]
>>> rcov = [[xcov, cov_xy], [cov_xy, ycov]]
>>> z, zcov = propagate(lambda r: fn(r[0], r[1]), r, rcov)

See also

jacobi