API

Uncertainty Wrapper

Uncertainty wrapper calculates uncertainties of wrapped functions using central finite difference approximation of the Jacobian matrix.

\[\frac{\partial f_i}{\partial x_{j,k}}\]

Uncertainty of the output is propagated using first order terms of a Taylor series expansion around \(x\).

\[dF_{ij} = J_{ij} * S_{x_i, x_j} * J_{ij}^{T}\]

Diagonals of \(dF_{ij}\) are standard deviations squared.

SunPower Corp. (c) 2016

Step Size

uncertainty_wrapper.core.DELTA = 3.0277272261966714e-06

Partial Derivative

uncertainty_wrapper.core.partial_derivative(f, x, n, nargs, delta=3.0277272261966714e-06)[source]

Calculate partial derivative using central finite difference approximation.

Parameters:
  • f – function
  • x – sequence of arguments
  • n – index of argument derivateve is with respect to
  • nargs – number of arguments
  • delta – optional step size, default is \(\epsilon^{1/3}\) where \(\epsilon\) is machine precision

Jacobian

uncertainty_wrapper.core.jacobian(func, x, nf, nobs, *args, **kwargs)[source]

Estimate Jacobian matrices \(\frac{\partial f_i}{\partial x_{j,k}}\) where \(k\) are independent observations of \(x\).

The independent variable, \(x\), must be a numpy array with exactly 2 dimensions. The first dimension is the number of independent arguments, and the second dimensions is the number of observations.

The function must return a Numpy array with exactly 2 dimensions. The first is the number of returns and the second dimension corresponds to the number of observations. If the input argument is 2-D then the output should also be 2-D

Constant arguments can be passed as additional positional arguments or keyword arguments. If any constant argument increases the number of observations of the return value, tile the input arguments to match.

Use numpy.atleast_2d() or numpy.reshape() to get the correct dimensions for scalars.

Parameters:
  • func – function
  • x – independent variables grouped by observation
  • nf – number of return in output (1st dimension)
  • nobs – number of observations in output (2nd dimension)
Returns:

Jacobian matrices for each observation

Flatten Jacobian

uncertainty_wrapper.core.jflatten(j)[source]

Flatten 3_D Jacobian into 2-D.

Wrapper

uncertainty_wrapper.core.unc_wrapper_args(*covariance_keys)[source]

Wrap function, calculate its Jacobian and calculate the covariance of the outputs given the covariance of the specified inputs.

Parameters:covariance_keys – indices and names of arguments corresponding to covariance
Returns:wrapped function bound to specified covariance keys

This is the outer uncertainty wrapper that allows you to specify the arguments in the original function that correspond to the covariance. The inner wrapper takes the original function to be wrapped.

def f(a, b, c, d, kw1='foo', *args, **kwargs):
    pass

# arguments a, c, d and kw1 correspond to the covariance matrix
f_wrapped = unc_wrapper_args(0, 2, 3, 'kw1')(f)

cov = np.array([[0.0001, 0., 0., 0.], [0., 0.0001, 0., 0.],
                [0., 0., 0.0001, 0.], [0., 0., 0., 0.0001])
y, cov, jac = f_wrapped(a, b, c, d, kw1='bar', __covariance__=cov)

The covariance keys can be indices of positional arguments or the names of keywords argument used in calling the function. If no covariance keys are specified then the arguments that correspond to the covariance shoud be grouped into a sequence. If None is anywhere in covariance_keys then all of the arguments will be used to calculate the Jacobian.

The covariance matrix must be a symmetrical matrix with positive numbers on the diagonal that correspond to the square of the standard deviation, second moment around the mean or root-mean-square(RMS) of the function with respect to the arguments specified as covariance keys. The other elements are the covariances corresponding to the arguments intersecting at that element. Pass the covariance matrix with the keyword __covariance__ and it will be popped from the dictionary of keyword arguments provided to the wrapped function.

The wrapped function will return the evaluation of the original function, its Jacobian, which is the sensitivity of the return output to each argument specified as a covariance key and the covariance propagated using the first order terms of a Taylor series expansion around the arguments.

An optional keyword argument __method__ can also be passed to the wrapped function (not the wrapper) that specifies the method used to calculate the dot product. The default method is 'loop'. The other methods are 'dense', 'sparse' and 'pool'.

If the arguments specified as covariance keys are arrays, they should all be the same size. These dimensions will be considered as separate observations. Another argument, not in the covariance keys, may also create observations. The resulting Jacobian will have dimensions of number of observations (nobs) by number of return output (nf) by number of covariance keys (nargs). The resulting covariance will be nobs x nf x nf.

Wrapper Shortcut

uncertainty_wrapper.core.unc_wrapper()

This is basically unc_wrapper_args() with no argument which assumes that all independent arguments are already grouped together.

Tests

Tests for unc_wrapper() and unc_wrapper_args()

Test Uncertainty Wrapper

uncertainty_wrapper.tests.test_uncertainty_wrapper.test_unc_wrapper()[source]

Test uncertainty wrapper with grouped arguments.

Test simple exponential function with known derivative. Assert derivative is correct and that uncertainty is propagated correctly.

Test IV curve

uncertainty_wrapper.tests.test_uncertainty_wrapper.test_IV(method='sparse')[source]

Test calculation of photovoltaic cell IV curve using 2-diode model and and compare Jacobian estimated by finite central difference to AlgoPy automatic differentiation.

Test complex function with several operations, including \(exp\), \(log\) and powers, with several input arguments and with several return values. Check Jacobian calculated with central finite difference approximation with automatic differentiation using AlgoPy.

Test Solar Position

uncertainty_wrapper.tests.test_uncertainty_wrapper.test_solpos(method='loop')[source]

Test solar position calculation using NREL’s SOLPOS.

Test function from a Python C/C++ extension. Check calcuated Jacobian with John D’Errico’s numdifftools Python package (MATLAB derivest).