nitrogen.dfun¶

This module implements the class DFun, which is used to interface general differentiable, multi-variate functions. See Differentiable functions and the DFun class for an in-depth tutorial.

Create DFun objects from functions
`DFun`	The `DFun` constructor
`FiniteDFun`	Finite-difference derivatives
Simple DFun objects
`ConstantDFun`	Constant-valued function.
`IdentityDFun`	\(\mathbb{R}^n\rightarrow\mathbb{R}^n\) identity map.
Modify single DFun objects
`FixedInputDFun`	Fix input value(s).
`PermutedDFun`	Permute input and output ordering.
`ArrangedDFun`	Rearrange and duplicate outputs.
Combine multiple DFun objects
`CompositeDFun`	Function composition.
`MergedDFun`	Concatenate outputs.
`SimpleProduct`	Separable direct product.
`SelectedProduct`	Separable non-direct product.

class nitrogen.dfun.ArrangedDFun(df, select)¶

Bases: nitrogen.dfun.DFun

Select a subset or duplicates of output functions.

df¶

The original DFun

Type: DFun

select¶

The output functions in terms of the indices of the original output functions.

Type: ndarray

Parameters

df (DFun) – A DFun object.
select (array_like of int) – The new output functions. Repetitions are allowed.

class nitrogen.dfun.CompositeDFun(A, B, force_general=False)¶

Bases: nitrogen.dfun.DFun

A composite DFun for C(x) = A(B(x))

A¶

The outer function.

Type: DFun

B¶

The inner function.

Type: DFun

force_general¶

If True, overrides hand-coded low-order expressions.

Type: bool

Composite function A(B(x))

Parameters

A (DFun) – The outer function.
B (DFun) – The inner function.
force_general (bool, optional) – If True, force evaluation using a general Taylor series expansion, overriding hand-coded expressions for small deriv.

class nitrogen.dfun.ConstantDFun(nx, value)¶

Bases: nitrogen.dfun.DFun

A constant-valued DFun object

Create a ConstantDFun object

Parameters

nx (integer) – The number of input variables.
value ((nf,) array_like) – The constant function value(s). The length determines nf. If scalar, nf = 1 is assumed.

class nitrogen.dfun.DFun(fx, nf=1, nx=1, maxderiv=None, zlevel=None)¶

Bases: object

A differentiable multi-variate function wrapper.

nf¶

The number of output variables.

Type: int

nx¶

The number of input variables.

Type: int

maxderiv¶

The maximum supported derivative order. A value of None indicates arbitrary derivatives are supported.

Type: int

zlevel¶

The zero-level of the function. All derivatives with total order greater than zlevel are zero. A value of None indicates all derivatves may be non-zero.

Type: int

Create a new DFun object.

Parameters

fx (function) – An instance method implementing the differentiable function with signature fx(X, deriv = 0, out = None, var = None). See DFun.f() for more details.
nf (int, optional) – The number of output variables of fx. The default is 1.
nx (int, optional) – The number of input variables of fx. The default is 1.
maxderiv (int, optional) – The maximum supported derivative of fx(). maxderiv = None indicates that arbitrary order derivatives are supported. The default is None.
zlevel (int, optional) – The zero-level of the differentiable function. All derivatives with total order greater than zlevel are zero. A value of None indicates all derivatives may be non-zero, while -1 indicates an identically zero function and 0 a constant function. The default is None.

f(X, deriv=0, out=None, var=None)¶

Evaluate the differentiable function.

Parameters

X (array_like) – An array of input values. X has shape (nx, …).
deriv (int, optional) – All derivatives up through order deriv are requested. The default is 0.
out (ndarray, optional) – The buffer to store the output. This is an ndarray with shape (nd, nf, …), where nd is the number of derivatives requested sorted in autodiff lexical order. (See Notes.) The default is None. If None, then a new output ndarray is created. The data-type of out is user-determined and -checked.
var (list of int) – Calculate derivatives only for those input variables whose index is included in var. Variables are referred to by their 0-index: 0, …, nx - 1. Each index may appear at most once. The returned derivative array will provide derivatives in lexical order based on the ordering in var, not the ordering expected in X. A value of None is equivalent to var = [0, 1, …, nx - 1].

Returns

out – The result array in autodiff format with shape (nd, nf, …)

Return type

ndarray

Notes

The number of derivatives nd equals the binomial coefficient (deriv + nvar, nvar), where nvar = len(var).

hes(X, out=None, var=None)¶

Wrapper for diff. function Hessian (second derivatives)

Parameters

X (ndarray) – An (nx, …) array of input values.
out (ndarray, optional) – The (nf, nvar,`nvar`, …) buffer to store the output. If None, then a new output ndarray is created. The default is None.
var (list of int) – Variable list (see var in DFun.f()).

Returns

ndarray – out[k,i,j] is the second derivative of output value k with respect to variables var[i] and var[j].

Return type

out

hesderiv(X, deriv=0, out=None, var=None)¶

Calculate the Hessian and its derivatives

Parameters

X (ndarray) – An (nx, …) array of input values.
deriv (int) – The derivative order of the Hessian function.
out (ndarray, optional) – Output buffer. If None, this will be created.
var (list of int) – Variable list (see var in DFun.f()).

Returns

An array of shape (nd, nvar, nvar, `nf, …) where nvar is the number of variables requested by var.

Return type

ndarray

jac(X, out=None, var=None)¶

Wrapper for diff. function Jacobian (first derivatives)

Parameters

X (ndarray) – An (nx, …) array of input values.
out (ndarray, optional) – The (nf, nvar, …) buffer to store the output. If None, then a new output ndarray is created. The default is None.
var (list of int) – Variable list (see var in DFun.f()).

Returns

ndarray – out[i,j] is the derivative of output value i with respsect to variable var[j]

Return type

out

jacderiv(X, deriv=0, out=None, var=None)¶

Calculate the Jacobian and its derivatives

Parameters

X (ndarray) – An (nx, …) array of input values.
deriv (int) – The derivative order of the Jacobian function.
out (ndarray, optional) – Output buffer. If None, this will be created.
var (list of int) – Variable list (see var in DFun.f()).

Returns

An array of shape (nd, nvar, nf, …) where nvar is the number of variables requested by var.

Return type

ndarray

optimize(X0, fidx=0, var=None, mode='min', disp=False)¶

Optimize an output value of a diff. function.

Parameters

X0 (array_like) – (nx,) array containing the initial guess
fidx (int) – The DFun function index to optimize. The default is 0.
var (list of int, optional) – The input variables to optimize. If None, all variables will be optimized. The default is None.
mode ({'min'}, optional) – The optimization mode. ‘min’ determines the function minimum. The default is ‘min’.
disp (bool) – If True, messages will be displayed.

Returns

Xopt (ndarray) – The optimized input values.
fopt (float) – The optimized function value.

val(X, out=None)¶

Wrapper for diff. function value (zeroth derivative)

Parameters

X (ndarray) – An (nx, …) array of input values.
out (ndarray, optional) – The (nf, …) buffer to store the output. If None, then a new output ndarray is created. The default is None.

Returns

ndarray

Return type

out

vj(X, var=None)¶

Wrapper for diff. function value and Jacobian

Parameters

X (ndarray) – An (nx, …) array of input values.
var (list of int) – Variable list (see var in DFun.f()).

Returns

val (ndarray) – The (nf,…) value.
jac (ndarray) – The (nf,nv,…) Jacobian

vjh(X, var=None)¶

Wrapper for diff. function value, Jacobian, and Hessian

Parameters

X (ndarray) – An (nx, …) array of input values.
var (list of int) – Variable list (see var in DFun.f()).

Returns

val (ndarray) – The (nf,…) value.
jac (ndarray) – The (nf,nv,…) Jacobian
hes (ndarray) – The (nf,nv,nv,…) Hessian

classmethod zerofun(nf=1, nx=1)¶

Construct a DFun object for a zero function.

Parameters

nf (int, optional) – The number of output values. The default is 1.
nx (int, optional) – The number of input values. The default is 1.

Returns

A DFun object for the zero function of nx variables returning nf values.

Return type

DFun

class nitrogen.dfun.FiniteDFun(fval, nx, steps=0.001, isvector=False, nf=1)¶

Bases: nitrogen.dfun.DFun

Finite difference derivatives

steps¶

Finite difference step sizes for each argument.

Type: (nx,) ndarray

Initialize a FiniteDFun instance.

Parameters

fval (function) – A function fval(X) that accepts an an (nx, …) ndarray input and returns an (…) ndarray output (if isvector is False) or an (nf, …) ndarray output (if isvector is True).
nx (integer) – The number of input values.
steps (scalar or array_like of float) – Finite difference step size. If a single scalar, then a uniform step size is used for all input arguments. An array_like list of length nx can be used to specify different step sizes for each input argument. The default is 1e-3.
isvector (bool) – Indicates fval is vector-valued.
nf (integer) – The number of output values. The default is 1. If isvector is False, nf is ignored.

class nitrogen.dfun.FixedInputDFun(dfunction, values)¶

Bases: nitrogen.dfun.DFun

Fixed-input differential function

Parameters

dfunction (DFun) – Requested inputs to DFun will be held fixed.
values (list) – A list of length dfunction.nX with the fixed input values. A list element of None keeps the corresponding input active.

class nitrogen.dfun.FourierSeries(coeff, period=None)¶

Bases: nitrogen.dfun.DFun

A simple Fourier series

coeff¶

The expansion coefficients

Type: (nf,n) ndarray

period¶

The period.

Type: float

maxfreq¶

The maximum harmonic.

Type: integer

Notes

The expansion is

\[c_0 + c_1 \sin(x) + c_2 \cos(x) + c_3 \sin(2x) + c_4 \cos(2x) + \cdots\]

Parameters

coeff ((n,) or (nf,n) array_like) – The n expansion coefficients for one or nf functions.
period (float, optional) – The period of the argument. If None (default), it is assumed to be \(2\pi\).

class nitrogen.dfun.IdentityDFun(nx)¶

Bases: nitrogen.dfun.DFun

A 1-to-1 identity function, \(f_i = x_i\).

Create an IdentityDFun object

Parameters: nx (integer) – The number of input variables.

class nitrogen.dfun.MergedDFun(dfuns)¶

Bases: nitrogen.dfun.DFun

Concatenate the outputs of multiple DFuns into a single, merged DFun.

Create a merged DFun with the outputs of multiples DFuns.

Parameters: dfuns (list of DFun) – The component DFun’s.

class nitrogen.dfun.PermutedDFun(df, in_order=None, out_order=None)¶

Bases: nitrogen.dfun.DFun

Permute the input or output order of a DFun

df¶

The original DFun

Type: DFun

in_order¶

The new input order

Type: ndarray

out_order¶

The new output order

Type: ndarray

Parameters

df (DFun) – A DFun object.
in_order (array_like of int, optional) – The new input order. If None (default), the original input order is used. For example, [2, 0, 1] moves the third input first, the first input second, and the second input last.
out_order (array_like of int, optional) – The new output order. If None (default), the original output order is used.

class nitrogen.dfun.PolyFactor(terms, nx=None)¶

Bases: nitrogen.dfun.DFun

Parameters

terms (list of lists) – Each element of terms is a list corresponding to one term in a summation. Each term is itself a list of 2 elements. The first element is a list of factors and the second is a scalar coefficient. For example, the term element [[0,0,1], 0.5] corresponds to x0*x0*x1 * 0.5.
nx (int, optional) – The number of coordinates. If None (default), nx is assumed to the be maximum

class nitrogen.dfun.PolyPower(terms)¶

Bases: nitrogen.dfun.DFun

Parameters: terms (list of lists) – Each element of terms is a list corresponding to one term in a summation. Each term is itself a list of 2 elements. The first element is a list of integer powers and the second is a scalar coefficient. For example, the term element [[0,3,1], 0.5] corresponds to x0**0 * x1**3 * x2**1 * 0.5.

class nitrogen.dfun.PowerExpansion(d, x0)¶

Bases: nitrogen.dfun.DFun

Power series expansion about a given point. This is usually more efficient than similar functions PolyPower and PolyFactor because it uses derivative array translation instead of an explicit sum over terms.

d¶

The defining derivative array about the expansion point

Type: (nd,nf) ndarray

x0¶

The expansion point.

Type: (nx,) ndarray

nitrogen.dfun¶

Previous topic

Next topic

This Page