The autodiff sub-package

nitrogen.autodiff.forward

This module implements a simple forward accumulation model for automatic differentiation. Its main object is the adarray class.

Constructing adarray objects

Description

adarray

Class constructor.

sym()

Create a symbol, i.e. an independent variable.

const()

Create a constant.

const_like()

Create a constant.

empty_like()

Create an uninitialized adarray.

Mathematical functions implemented include

Arithmetic and powers

Description

add()

Addition, \(x + y\).

subtract()

Subtraction, \(x - y\).

mul()

Multiplication, \(x * y\).

div()

Division, \(x/y\).

powi()

Integer powers, \(x^i\).

powf()

Real (or complex) powers, \(x^p\).

sqrt()

Square root, \(\sqrt{x}\).

Trigometric and hyperbolic

Description

sin()

Sine, \(\sin(x)\).

cos()

Subtraction, \(\cos(x)\).

asin()

Inverse sine, \(\arcsin(x)\).

acos()

Inverse cosine, \(\arccos(x)\).

sinh()

Hyperbolic sine, \(\sinh(x)\).

cosh()

Hyperbolic cosine, \(\cosh(x)\).

tanh()

Hyperbolic tangent, \(\tanh(x)\).

Exponents and logarithms

Description

exp()

Exponential, \(\exp(x)\).

log()

Natural logarithm, \(\log(x)\).

Linear algebra

Description

chol_sp()

Cholesky decomposition (symmetric, packed).

inv_tp()

Triangular matrix inverse (packed).

llt_tp()

\(L L^T\) for triangular matrix (packed).

ltl_tp()

\(L^T L\) for triangular matrix (packed).

Low-level derivative array routines include

Function

Description

mvleibniz()

Leibniz formula for generalized product rule.

mvchain()

Chain rule via Taylor expansion.

mvrotate()

Linear transformation of independent variables.

mvtranslate()

Shift a truncated Taylor series.

mvexpand()

Expand derivative array to redundant derivative grid.

mvexpand_block()

Expand derivative array to redundant derivative grid.

mvcompress()

Compress redundant derivative grid to derivative array.
nitrogen.autodiff.forward.acos(x, out=None)

Arccosine for adarray objects.

Parameters

  • x (adarray) – Input, \(x \in [-1,1]\)

  • out (adarray, optional) – Output location of result. out must have the same properties as x. If None, a new adarray is allocated and returned.

Returns

Result. The real part lies in \([0,\pi]\).

Return type

adarray

Examples

>>> x = adf.sym(0.35, 0, 3, 1)
>>> adf.acos(x).d
array([ 1.21322522, -1.06752103, -0.21289593, -0.28767379])
class nitrogen.autodiff.forward.adarray(base_shape, k, ni, nck=None, idx=None, dtype=<class 'numpy.float64'>, d=None, zlevel=None, zlevels=None)

Forward-type automatic differentiation object.

k

The maximum derivative order.

Type

int

ni

The number of independent variables.

Type

int

nck

A binomial coefficient table.

Type

ndarray

idx

The multi-index table for derivatives of ni variables to order k.

Type

ndarray

nd

The number of unique derivatives.

Type

int

d

The derivative array, whose first index is the generalized derivative index. (See Notes.)

Type

ndarray

zlevel

The highest non-zero derivative order. If -1, then this adarray is identically zero.

Type

int

zlevels

The zero-levels of individual variables.

Type

ndarray

Notes

The derivative information is stored in the d attribute, an ndarray whose first index is a generalized derivative index. d[0] is the the value of the base array and d[i] with i > 0 are the derivatives stored in lexical order. This ordering sorts derivatives first by their total degree: zeroth derivatives (the value), then first derivatives, then second derivatives, and so on. Within a group of derivatives of a given order, they are sorted by the derivative order with respect to the first independent variable, then by the order of the second, and so on. This ordering is the same as that of idx

The values of higher-order derivatives are stored by convention with a factor equal to the inverse of the multi-index factorial, i.e. a derivative with multi-index [2, 0, 1, 3] would be stored as the corresponding derivative divided by \(2!\times 0!\times 1!\times 3!\)

The zero-level indicators zlevel and zlevels are independent of each other.

The accounting arrays, nck, idx, and zlevels should be considered immutable. They might be shared by multiple adarrays. Even d might be. In general, do not modify adarray attributes directly.

Create a new adarray object.

Parameters

  • base_shape (tuple of int) – Shape of base array. adarray.d will have shape (nd,) + base_shape. Shape may be ().

  • k (int) – Maximum derivative degree. k must be greater or equal to 0.

  • ni (int) – Number of independent variables. n must be greater than or equal to 1.

  • nck (ndarray, optional) – Return value of ncktab(nmax,kmax) with nmax >= k + ni and kmax >= min(k, ni). If None, this will be calculated.

  • idx (ndarray, optional) – Return value of idxtab(k,ni). If None, this will be calculated.

  • dtype (data-type, optional) – Data-type of initialized derivative array

  • d (ndarray, optional) – A pre-allocated derivative array. If provided, dtype will be ignored and d must have a shape equal to (nd,) + base_shape

  • zlevel (int, optional) – The zero level indicator. If None, this will be set to k. The default is None.

  • zlevels (array_like of int, optional) – The zero-levels of each variables. If None, each will be set to k. The default is None.

See also

ncktab

Binomial coefficient table

idxtab

Multi-index table

copy(out=None)

Copy an adarray object.

Parameters

out (adarray) – Output location. If None, this will be created if None. The default is None.

Returns

An adarray object, with d attribute copied via d.copy().

Return type

adarray

Notes

The d and zlevels attributes are hard-copied. The nck and idx attributes still share references.

moveaxis_base(source, destination)

Move axes of base array

Parameters

  • source (int or sequence of int) – Original positions of axes

  • destination (int or sequence of int) – Destination positions of axes

Returns

A view adarray with the derivative array referencing the return value of np.moveaxis

Return type

adarray

reshape_base(new_shape)

Reshape base array

Parameters

newshape (tuple of ints) –

Returns

A view adarray with the deriative array referencing the return value of np.reshape

Return type

adarray

transpose_base(axes=None)

Transpose base array

Parameters

axes (tuple or list of ints, optional) – The same as ndarray transpose. The axis indices reference the base shape of the derivative array. If None, the default is to reverse base axes.

Returns

A view ndarray with the derivative array referencing the return value of np.transpose

Return type

adarray

view()

Creat an adarray object whose derivative array is a view of this one.

Returns

An adarray object, with d attribute viewed via d.view().

Return type

adarray

Notes

The d attribute is a view of the original. The zlevels attribute is just a reference assignment.

nitrogen.autodiff.forward.adchain(df, x, out=None)

Calculate f(x) via chain rule.

Parameters

  • df (ndarray) – Single-variable derivatives of f(x) w.r.t to its argument up to order x.k

  • x (adarray) – Argument of f(x)

  • out (adarray, optional) – Output location of result. out must have the same properties as x. If None, a new adarray is allocated and returned.

Returns

The result f(x).

Return type

adarray

nitrogen.autodiff.forward.add(x, y, out=None)

Add x + y

Parameters

  • x (adarray) – Input argument

  • y (adarray) – Input argument

  • out (adarray, optional) – Output location. If None, this will be created. The default is None.

Returns

Result.

Return type

adarray

Examples

>>> x = adf.sym(1.0, 0, 2, 2)
>>> y = adf.sym(3.0, 1, 2, 2)
>>> adf.add(x,y).d
array([4., 1., 1., 0., 0., 0.])
nitrogen.autodiff.forward.array(d, k, ni, copyd=False, zlevel=None, zlevels=None, nck=None, idx=None)

Create an adarray object from a raw derivative array.

Parameters

  • d (ndarray) – The derivative array with shape (nd,…)

  • k (int) – The maximum derivative order.

  • ni (int) – The number of independent variables.

  • copyd (boolean, optional) – If True, a copy of d will be made for returned adarray. If False, the adarray will use the same reference. The default is False.

  • zlevel (int, optional) – The zero-level of d. If None, this will be set safely to k. The default is None.

  • zlevels (array_like of int, optional) – The zero-level of each variable. If None, this will be set safely to k for each. The default is None.

  • nck (ndarray, optional) – See adarray constructor.

  • idx (ndarray, optional) – See adarray constructor.

Returns

Return type

adarray

nitrogen.autodiff.forward.asin(x, out=None)

Arcsine for adarray objects.

Parameters

  • x (adarray) – Input, \(x \in [-1,1]\)

  • out (adarray, optional) – Output location of result. out must have the same properties as x. If None, a new adarray is allocated and returned.

Returns

Result. The real part lies in \([-\pi/2, \pi/2]\).

Return type

adarray

Examples

>>> x = adf.sym(0.35, 0, 3, 1)
>>> adf.asin(x).d
array([0.3575711 , 1.06752103, 0.21289593, 0.28767379])
nitrogen.autodiff.forward.block2(arrays)

Assemble an array from 2-D nested list of sub-arrays

Parameters

arrays (list of list of adarray) – The blocks

Returns

The assembled array

Return type

adarray

Notes

This performs numpy.block on the base arrays of the adarray objects

nitrogen.autodiff.forward.block4(arrays)

Assemble an array from 4-D nested list of sub-arrays

Parameters

arrays (nested list of adarray) – The blocks

Returns

The assembled array

Return type

adarray

Notes

This performs numpy.block on the base arrays of the adarray objects

nitrogen.autodiff.forward.broadcast_shape(sX, sY, mode='normal')

Calculate the broadcasted shape for different multiplication modes.

Parameters

  • sX (tuple of int) – The base shapes

  • sY (tuple of int) – The base shapes

  • mode ({'normal','matmul'}) – The multiplication mode.

Returns

shape – The base shape of the broadcasted result

Return type

tuple

nitrogen.autodiff.forward.calc_product_table(k, ni)

Calculate the sorted direct product table for derivative array product.

Parameters

  • k (integer) – The maximum derivative order.

  • ni (integer) – The number of variables.

Returns

table – The sorted direct product table. The elements equal 1-D indices of standard derivative array lexical ordering.

Return type

(3,tablesize) ndarray

Notes

The generalized Leibniz product for scaled derivative arrays is

\[Z^{(\gamma)} = \sum_{\alpha \leq \gamma} X^{(\alpha)} Y^{(\beta = \gamma - \alpha)}\]

The direct product table pre-computes all multi-index triplets \((\gamma, \alpha, \beta = \gamma - \alpha)\) in terms of their one-dimensional derivative array index:

Z[table[0,i]] <-- X[table[1,i]] * Y[table[2,i]]

This function returns a sorted table. A sorted table satisfies these conditions:

  1. The one-dimensional indices are ordered such that if \(\alpha < \beta\), then \(idx(\alpha) < idx(\beta)\). (The standard derivative array lexical ordering is sorted by \(\vert \alpha \vert\), which guarantees it is also sorted in this formal sense.)

  2. table is sorted by ascending order of table[0].

  3. For equal elements of table[0], the table is sorted by table[1].

This ordering of the direct product table is useful for derivative array routines that construct derivative arrays recursively.

nitrogen.autodiff.forward.chol_sp(H, out=None)

Cholesky decomposition of a symmetric matrix in packed format. If real symmetric, then H should be positive definite. If complex symmetric (not Hermitian), then H should have non-zero pivots.

Parameters

  • H (ndarray of adarray) – H is stored in 1D packed format (see nitrogen.linalg.packed)

  • out (ndarray of adarray) – Output buffer. If None, this will be created. If out = H, then in-place decomposition is performed

Returns

out – The lower triangle Cholesky decomposition L in packed storage. H = L @ L.T

Return type

ndarray of adarray

nitrogen.autodiff.forward.const(value, k, ni, nck=None, idx=None)

Create an adarray object for a constant scalar or array.

Parameters

  • value (array_like) – The constant value. If this is not an ndarray already, it will try to be converted.

  • k (int) – The maximum derivative degree.

  • ni (int) – The number of independent variables

  • nck (ndarray, optional) – See adarray constructor.

  • idx (ndarray, optional) – See adarray constructor.

Returns

A constant adarray object.

Return type

adarray

Examples

>>> adf.const(1., 2, 2).d
array([1., 0., 0., 0., 0., 0.])

>>> adf.const(42j, 1, 3).d
array([0.+42.j, 0. +0.j, 0. +0.j, 0. +0.j])

>>> adf.const([2.0, 3.0], 2, 2).d
array([[2., 3.],
       [0., 0.],
       [0., 0.],
       [0., 0.],
       [0., 0.],
       [0., 0.]])
nitrogen.autodiff.forward.const_like(value, x, dtype=None)

Create a constant adarray initialized to value with similar properties to x.

Parameters

  • value (scalar or array_like) – Value.

  • x (adarray) – Prototype.

  • dtype (dtype, optional) – Data-type. If None, then x.d.dtype is used.

Returns

Return type

adarray

nitrogen.autodiff.forward.cos(x, out=None)

Cosine for adarray objects.

Parameters

  • x (adarray) – Input in radians.

  • out (adarray, optional) – Output location of result. out must have the same properties as x. If None, a new adarray is allocated and returned.

Returns

Result.

Return type

adarray

Examples

>>> x = adf.sym(2.0, 0, 3, 1)
>>> adf.cos(x).d
array([-0.41614684, -0.90929743,  0.20807342,  0.15154957])
nitrogen.autodiff.forward.cosh(x, out=None)

Hyperbolic cosine for adarray objects.

Parameters

  • x (adarray) – Input argument.

  • out (adarray, optional) – Output location of result. out must have the same properties as x. If None, a new adarray is allocated and returned.

Returns

Result.

Return type

adarray

Examples

>>> x = adf.sym(1.5, 0, 3, 1)
>>> adf.cosh(x).d
array([2.35240962, 2.12927946, 1.17620481, 0.35487991])
nitrogen.autodiff.forward.cost(k, ni, quiet=False)

Estimate the cost of adarray operations.

Parameters

  • k (int) – The total degree, \(k \geq 0\)

  • ni (int) – The number of variables, \(n_i \geq 1\)

  • quiet (bool, optional) – Suppress printed output. The default is False.

Returns

Return type

None

nitrogen.autodiff.forward.div(x, y, out=None)

Divide x / y

Parameters

  • x (adarray) – Input argument

  • y (adarray) – Input argument

  • out (adarray, optional) – Output buffer. If None, this will be created. The default is None.

Returns

Result.

Return type

adarray

Examples

>>> x = adf.sym(1.0, 0, 2, 2)
>>> y = adf.sym(3.0, 1, 2, 2)
>>> adf.div(x,y).d
array([ 0.33333333,  0.33333333, -0.11111111,  0.        , -0.11111111,
        0.03703704])
nitrogen.autodiff.forward.empty_like(x, dtype=None, baseshape=None)

Create an uninitialized adarray with the same properties as x, including base array data-type. The zlevel will be maximum.

Parameters

  • x (adarray) – Prototype object

  • dtype (dtype, optional) – Base data-type. If None, then x.d.dtype is used.

  • baseshape (tuple, optional) –

    The base shape. If None, then the base shape of

    x is used.

Returns

  • adarray – A new adarray with the same properties as x

  • >>> empty_like(const([3.3, 2.1], 2, 2)).d.shape

  • (6, 2)

nitrogen.autodiff.forward.exp(x, out=None)

Exponential for adarray objects.

Parameters

  • x (adarray) – Input argument.

  • out (adarray, optional) – Output location of result. out must have the same properties as x. If None, a new adarray is allocated and returned.

Returns

Result.

Return type

adarray

Examples

>>> x = adf.sym(1.5, 0, 3, 1)
>>> adf.exp(x).d
array([4.48168907, 4.48168907, 2.24084454, 0.74694818])
nitrogen.autodiff.forward.idxpos(a, nck)

Calculate the absolute lexical position of multi-index a.

Parameters

  • a (ndarray) – 1D multi-index

  • nck (ndarray) – A binomial coefficient table as returned by ncktab(nmax,kmax), with nmax >= ni + k - 1 and kmax >= min(ni, k - 1), where ni = a.size and k = sum(a).

Returns

pos – The absolute lexical position of multi-index a

Return type

np.uint64

Examples

>>> adf.idxpos(np.array([0,0,0]),adf.ncktab(3,3))
0

>>> adf.idxpos(np.array([2,0,1,3]),adf.ncktab(9,4))
159

See also

ncktab

Binomial coefficient table

nitrogen.autodiff.forward.idxposk(a, nck)

Calculate the relative lexical position of multi-index a within the block of its degree k = sum(a).

Parameters

  • a (ndarray) – 1D multi-index

  • nck (ndarray) – A binomial coefficent table as returned by ncktab(nmax,kmax) with nmax >= ni - 3 + k - a[0] and kmax >= min(ni - 2, k - a[0] - 1). Simpler requirements that satisfy these are nmax >= ni + k - 1 and kmax >= min(ni, k - 1).

Returns

posk – Relative position of multi-index in its block of degree k = sum(a).

Return type

np.uint64

Examples

>>> adf.idxposk(np.array([0,0,0]),adf.ncktab(3,3))
0

>>> adf.idxposk(np.array([2,0,1,3]),adf.ncktab(5,2))
33

See also

ncktab

Binomial coefficient table

nitrogen.autodiff.forward.idxtab(k, ni)

Multi-index table for derivatives up to order k of ni variables.

The number of multi-indices (i.e. the number of unique derivatives) is nd = nck(k + ni, ni)

Parameters

  • k (int) – Maximum derivative order.

  • ni (int) – Number of variables.

Returns

Multi-index table with shape (nd, ni) and data-type np.uint32.

Return type

ndarray

Examples

>>> adf.idxtab(2,3)
array([[0, 0, 0],
       [1, 0, 0],
       [0, 1, 0],
       [0, 0, 1],
       [2, 0, 0],
       [1, 1, 0],
       [1, 0, 1],
       [0, 2, 0],
       [0, 1, 1],
       [0, 0, 2]], dtype=uint32)
nitrogen.autodiff.forward.inv_tp(L, out=None)

Invert a triangular matrix in lower row-packed (or upper column-packed) storage.

Parameters

  • L (ndarray of adarray) – L is stored in 1D packed format (see nitrogen.linalg.packed)

  • out (ndarray of adarray) – Output buffer. If None, this will be created. If out = L, then in-place inversion is performed

Returns

out – The inverse of the triangular matrix in packed storage.

Return type

ndarray of adarray

nitrogen.autodiff.forward.llt_tp(L, out=None)

L @ L.T of a lower triangular matrix.

Parameters

  • L (ndarray of adarray) – Lower triangular matrix in packed storage.

  • out (ndarray of adarray) – Output buffer. If None, this will be created. If out = L, then in-place multiplication is performed

Returns

out – The result in packed storage.

Return type

ndarray of adarray

nitrogen.autodiff.forward.log(x, out=None)

Natural logarithm for adarray objects.

Parameters

  • x (adarray) – Input argument.

  • out (adarray, optional) – Output location of result. out must have the same properties as x. If None, a new adarray is allocated and returned.

Returns

Result.

Return type

adarray

Examples

>>> x = adf.sym(3.0, 0, 3, 1)
>>> adf.log(x).d
array([ 1.09861229,  0.33333333, -0.05555556,  0.01234568])
nitrogen.autodiff.forward.ltl_tp(L, out=None)

L.T @ L with a lower triangular matrix.

Parameters

  • L (ndarray of adarray) – Lower triangular matrix in packed storage.

  • out (ndarray of adarray) – Output buffer. If None, this will be created. If out = L, then in-place multiplication is performed

Returns

out – The symmetric result in packed storage.

Return type

ndarray of adarray

nitrogen.autodiff.forward.matmul(x, y, out=None)

Matrix multiply x @ y

Parameters

  • x (adarray) – Input argument

  • y (adarray) – Input argument

  • out (adarray, optional) – Output buffer. If None, this will be created. The default is None.

Returns

Result.

Return type

adarray

Notes

The usual NumPy matmul broadcasting rules apply to the base shapes of the derivative arrays.

nitrogen.autodiff.forward.mul(x, y, out=None)

Multiply x * y

Parameters

  • x (adarray) – Input argument

  • y (adarray) – Input argument

  • out (adarray, optional) – Output buffer. If None, this will be created. The default is None.

Returns

Result.

Return type

adarray

Examples

>>> x = adf.sym(1.0, 0, 2, 2)
>>> y = adf.sym(3.0, 1, 2, 2)
>>> adf.mul(x,y).d
array([3., 3., 1., 0., 1., 0.])
nitrogen.autodiff.forward.mvchain(df, X, k, ni, nck, idx, out=None, Xzlevel=None, Xzlevels=None)

Multivariate chain rule Z = f(X) via Taylor series.

Parameters

  • df (ndarray) – An array containing the derivatives of single-argument function f through order k. The shape of df is (k+1,) + X.shape[1:]

  • X (ndarray) – Derivative array in adarray.d format

  • k (int) – Maximum derivative order

  • ni (int) – Number of independent variables

  • nck (ndarray) – Binomial coefficient table for X satisfying requirements for mvleibniz().

  • idx (ndarray) – Multi-index table for X satisfying requirements for mvleibniz().

  • out (ndarray, optional) – Output location. If None, a new ndarray is created with the same data-type as X.

  • Xzlevel (int, optional) – The zlevel of the X derivative array. If None, this is assumed to be k.

  • Xzlevels (ndarray, optional) – The zlevels of each variable. If None, this is assumed to be k for each.

Returns

out – The derivative array for f(X)

Return type

ndarray

See also

ncktab

Binomial coefficient table

idxtab

Multi-index table

mvleibniz

Generalized Leibniz product rule

adchain

Chain rule for adarray objects

Notes

mvchain() is a low-level function that acts directly on derivative arrays (usually adarray.d). In most cases, the high-level function adchain() should be used directly with adarray objects.

nitrogen.autodiff.forward.mvcompress(partials, ni, idx)

Repack partial derivative arrays to derivative array format

partialslist

The derivative tensors for separated by degree

niint

The number of variables

idxndarray

The multi-index table

nitrogen.autodiff.forward.mvexpand(X, k, ni, nck)

Expand a packed derivative array to full symmetric tensors for each derivative degree.

Parameters

  • X (ndarray) – A derivative array

  • k (int) – Maximum derivative order

  • ni (int) – Number of variables

  • nck (ndarray) – Binomial table

Returns

partials – A list of arrays for the zeroth, first, second, etc. derivatives in full symmetric form.

Return type

list

nitrogen.autodiff.forward.mvexpand_block(Xk, k, ni, nck)

Expand the derivative array block of a single total degree

Parameters

  • Xk (ndarray) – The block of the derivative array for a single degree

  • k (int) – The degree

  • ni (int) – The number of variables.

  • nck (ndarray) – Binomial table.

Returns

out – The full derivative tensor. The first k indices have length ni. The remaining shape matches the base shape of Xk.

Return type

ndarray

nitrogen.autodiff.forward.mvleibniz(X, Y, k, ni, nck, idx, out=None, Xzlevel=None, Yzlevel=None, Xzlevels=None, Yzlevels=None, mode='normal', customfun=None)

Multivariate Leibniz formula for derivative arrays.

Parameters

  • X (ndarray) – Derivative array factors (e.g. adarray.d). These must have broadcastable base-shapes.

  • Y (ndarray) – Derivative array factors (e.g. adarray.d). These must have broadcastable base-shapes.

  • k (int) – Maximum derivative order of X and Y

  • ni (int) – Number of independent variables for X and Y

  • nck (ndarray) – Binomial coefficient table, as returned by ncktab(nmax,kmax) with nmax >= k + ni - 1 and kmax >= min(ni, k - 1)

  • idx (ndarray) – Multi-index table, as returned by idxtab(k, ni)

  • out (ndarray, optional) – Output location. If None, a new ndarray is created with the result type of X and Y’s data-types

  • Xzlevel (int, optional) – Zero-level for input. If None, this is assumed to be k. The default is None.

  • Yzlevel (int, optional) – Zero-level for input. If None, this is assumed to be k. The default is None.

  • Xzlevels (ndarray, optional) – The zero-levels for each variable. If None, this is assumed to be k for all. The default is None.

  • Yzlevels (ndarray, optional) – The zero-levels for each variable. If None, this is assumed to be k for all. The default is None.

  • mode ({'normal','matmul','custom'}, optional) – The multiplication mode.

  • customfun (function) – A function of two arguments.

Returns

out – The derivative array for X * Y

Return type

ndarray

See also

adarray

ncktab

Binomial coefficient table

idxtab

Multi-index table

Notes

mvleibniz() is low-level function applied directly to derivative arrays (usually adarray.d). Typically, multiplication should be applied at high-level with the * operator directly with adarray objects.

Xzlevel and Xzlevels are used independently to determine whether certain derivatives are to be skipped.

nitrogen.autodiff.forward.mvrotate(X, iT, k, nck, idxnew)

Rotate the derivative array via a linear transformation. The new coordinates are defined by a matrix \(\mathbf{T}\), i.e. \(y_i = T_{ij} x_j\).

Parameters

  • X (ndarray) – The derivative array with respect to the original coordinates.

  • iT (ndarray) – The inverse of the linear transformation matrix. The second dimension of iT is allowed to be less than ni.

  • k (int) – The maximum derivative degree.

  • nck (ndarray) – Binominal coefficient table for the original number of coordinates.

  • idxnew (ndarray) – The multi-index table for the new number of coordinates.

Returns

Y – The derivative array with respect to the new coordinates.

Return type

ndarray

nitrogen.autodiff.forward.mvtranslate(X, D, k, ni, nck, idx, out=None, Xzlevel=None, Xzlevels=None)

Evaluate a shifted multivariate Taylor series.

Parameters

  • X (ndarray) – The derivative array about the initial expansion point.

  • D (ndarray) – The expansion point displacement.

  • k (int) – Maximum derivative order

  • ni (int) – Number of independent variables

  • nck (ndarray) – Binomial coefficient table for X satisfying requirements for mvleibniz().

  • idx (ndarray) – Multi-index table for X satisfying requirements for mvleibniz().

  • out (ndarray, optional) – Output location. If None, a new ndarray is created with the same data-type as X.

  • Xzlevel (int, optional) – The zlevel of the X derivative array. If None, this is assumed to be k.

  • Xzlevels (ndarray, optional) – The zlevels of each variable. If None, this is assumed to be k for each.

Returns

out – The derivative array about the new expansion point.

Return type

ndarray

nitrogen.autodiff.forward.n2N(n)

Calculate the square matrix rank N for a packed storage size n

Parameters

n (int) – The packed length.

Returns

N – The matrix rank.

Return type

np.uint64

Examples

>>> adf.n2N(21)
6
nitrogen.autodiff.forward.nck(n, k)

Calculate the binomial coefficient (n choose k).

This function uses a simple recursive algorithm. Use of ncktab() may be significantly faster (i.e. ncktab(n,k)[n,k].)

Parameters

  • n (int) – Arguments of the binomial coefficient.

  • k (int) – Arguments of the binomial coefficient.

Returns

The binomial coefficient (n choose k).

Return type

np.uint64

Examples

>>> adf.nck(4,2)
6

>>> adf.nck(4,0)
1

See also

ncktab

Binomial coefficient table

nitrogen.autodiff.forward.nckmulti(a, b, nck)

Calculate multi-index binomial coefficient (a, b)

Parameters

  • a (ndarray) – 1D multi-indices

  • b (ndarray) – 1D multi-indices

  • nck (ndarray) – Binomial coefficient table as returned by ncktab(nmax,kmax), with nmax >= max(a) and kmax >= max(b)

Returns

Multi-index binomial coefficient.

Return type

np.float64

See also

ncktab

Binomial coefficient table

Examples

>>> adf.nckmulti(np.array([4,2,3]), np.array([2,1,2]), adf.ncktab(4))
36.0
nitrogen.autodiff.forward.ncktab(nmax, kmax=None)

Binomial coefficient table

Parameters

  • nmax (int) – Maximum value of n (first argument of coeff).

  • kmax (int, optional) – Maximum value of k. If None, its value is set to nmax. The default is None.

Returns

tab – 2D array of shape (nmax + 1, kmax + 1) containing the binomial coefficients, tab[n,k] = (n choose k). The values of invalid elements (i.e. k > n) are undefined. The data-type is np.uint64.

Return type

ndarray

Examples

>>> adf.ncktab(3)
array([[1, 0, 0, 0],
       [1, 1, 0, 0],
       [1, 2, 1, 0],
       [1, 3, 3, 1]], dtype=uint64)
nitrogen.autodiff.forward.nderiv(deriv, nvar)

The number of derivatives up to order deriv, inclusively, in nvar variables. This equals the binomial coefficient (deriv + nvar, nvar).

Parameters

  • deriv (int) – The maximum derivative order.

  • nvar (int) – The number of independent variables.

Returns

The number of derivatives.

Return type

np.uint64

Examples

>>> adf.nderiv(3,2)
10

>>> adf.nderiv(2,6)
28
nitrogen.autodiff.forward.ndize1(x)

Create a 1D ndarray of adarray objects from a single adarray by promoting the first index of the base shape.

Parameters

x (adarray) – The original adarray.

Returns

The 1D array of adarrays.

Return type

ndarray

Notes

The derivative arrays of the new adarray objects are views of x.d.

nitrogen.autodiff.forward.powf(x, p, out=None)

x**p for general p

Parameters

  • x (adarray) – Base argument.

  • p (float or complex) – Exponent.

  • out (adarray, optional) – Output location of result.

Returns

Result.

Return type

adarray

Notes

powf uses the NumPy float_power() function to compute the value array. It inherits the branch-cut convention of this function.

Examples

>>> x = adf.sym(1.5, 0, 3, 1)
>>> adf.powf(x, -2.5).d
array([ 0.36288737, -0.60481228,  0.70561433, -0.70561433])
nitrogen.autodiff.forward.powi(x, i, out=None)

x**i for integer i

Parameters

  • x (adarray) – Base argument.

  • i (integer) – Integer exponent.

  • out (adarray, optional) – Output location of result.

Returns

Result.

Return type

adarray

Notes

If i == 0, then powi returns a constant 1 for any value of x. For negative i, x is inverted and then the positive power is applied to 1/x.

Examples

>>> x = adf.sym(1.5, 0, 3, 1)
>>> adf.powf(x, 3).d
array([3.375, 6.75 , 4.5  , 1.   ])
nitrogen.autodiff.forward.reduceOrder(F, i, k, ni, idx, out=None)

Reduce the derivative array for F with respect to variable i. The returned derivative array is that for the function \(\partial_i F\).

Parameters

  • F (ndarray) – The derivative array up to degree k in ni variables.

  • i (int) – The variable index (0, …, ni - 1) to reduce.

  • k (int) – The initial derivative order of F.

  • ni (int) – The number of independent variables.

  • idx (ndarray) – The return value of idxtab with suitable parameters.

  • out (ndarray, optional) – Output buffer. If None, this will be created. The default is None.

Returns

out – The derivative array with shape (nd_reduced, …) corresponding to the new function \(\partial_i F\)

Return type

ndarray

nitrogen.autodiff.forward.reduceOrderTwice(F, i, j, k, ni, idx, out=None)

Reduce the derivative array for F with respect to variables i and j. The returned derivative array is that for the function \(\partial_i \partial_j F\). (Note that this function is an unscaled derivative.)

Parameters

  • F (ndarray) – The derivative array up to degree k in ni variables.

  • i (int) – The variable index (0, …, ni - 1) to reduce. i may equal j.

  • j (int) – The variable index (0, …, ni - 1) to reduce. i may equal j.

  • k (int) – The initial derivative order of F.

  • ni (int) – The number of independent variables.

  • idx (ndarray) – The return value of idxtab with suitable parameters.

  • out (ndarray, optional) – Output buffer. If None, this will be created. The default is None.

Returns

out – The derivative array with shape (nd_reduced, …) corresponding to the new function \(\partial_i \partial_j F\)

Return type

ndarray

nitrogen.autodiff.forward.sin(x, out=None)

Sine for adarray objects.

Parameters

  • x (adarray) – Input in radians.

  • out (adarray, optional) – Output location of result. out must have the same properties as x. If None, a new adarray is allocated and returned.

Returns

Result.

Return type

adarray

Examples

>>> x = adf.sym(1.0, 0, 3, 1)
>>> adf.sin(x).d
array([ 0.84147098,  0.54030231, -0.42073549, -0.09005038])
nitrogen.autodiff.forward.sinh(x, out=None)

Hyperbolic sine for adarray objects.

Parameters

  • x (adarray) – Input argument.

  • out (adarray, optional) – Output location of result. out must have the same properties as x. If None, a new adarray is allocated and returned.

Returns

Result.

Return type

adarray

Examples

>>> x = adf.sym(1.5, 0, 3, 1)
>>> adf.sinh(x).d
array([2.12927946, 2.35240962, 1.06463973, 0.39206827])
nitrogen.autodiff.forward.sqrt(x)
Parameters

  • x (adarray) – Input argument

  • out (adarray, optional) – Output buffer. If None, this will be created. The default is None.

Returns

Result.

Return type

adarray

Notes

The adarray sqrt function uses the NumPy sqrt() function as its underlying routine. Its branch-cut convention is inherited.

Examples

>>> x = adf.sym(2.5, 0, 3, 1)
>>> adf.sqrt(x).d
array([ 1.58113883,  0.31622777, -0.03162278,  0.00632456])
nitrogen.autodiff.forward.subtract(x, y, out=None)

Subtract x - y

Parameters

  • x (adarray) – Input argument

  • y (adarray) – Input argument

  • out (adarray, optional) – Output location. If None, this will be created. The default is None.

Returns

Result.

Return type

adarray

Examples

>>> x = adf.sym(1.0, 0, 2, 2)
>>> y = adf.sym(3.0, 1, 2, 2)
>>> adf.subtract(x,y).d
array([-2.,  1., -1.,  0.,  0.,  0.])
nitrogen.autodiff.forward.sym(value, i, k, ni, nck=None, idx=None)

Create an adarray for a symbol (i.e. one the independent variables with respect to which derivatives are being taken).

Parameters

  • value (array_like) – The value of the variable.

  • i (int) – The variable index, i = 0, … , ni - 1

  • k (int) – See adarray constructor.

  • ni (int) – See adarray constructor.

  • nck (ndarray, optional) – See adarray constructor.

  • idx (ndarray, optional) – See adarray constructor.

Returns

An adarray object for variable i and value value.

Return type

adarray

Examples

>>> adf.sym(2.0, 0, 2, 2).d
array([2., 1., 0., 0., 0., 0.])

>>> adf.sym(3.0, 1, 2, 2).d
array([3., 0., 1., 0., 0., 0.])

>>> adf.sym([3.0, 4.0j], 1, 2, 2).d
array([[3.+0.j, 0.+4.j],
       [0.+0.j, 0.+0.j],
       [1.+0.j, 1.+0.j],
       [0.+0.j, 0.+0.j],
       [0.+0.j, 0.+0.j],
       [0.+0.j, 0.+0.j]])
nitrogen.autodiff.forward.tanh(x, out=None)

Hyperbolic tangent for adarray objects.

Parameters

  • x (adarray) – Input argument.

  • out (adarray, optional) – Output location of result. out must have the same properties as x. If None, a new adarray is allocated and returned.

Returns

Result.

Return type

adarray

Examples

>>> x = adf.sym(1.5, 0, 3, 1)
>>> adf.tanh(x).d
array([ 0.90514825,  0.18070664, -0.1635663 ,  0.0878162 ])
nitrogen.autodiff.forward.tensordot(A, B, axes=2)

Perform a tensor dot product of base axes

Parameters

  • A (adarray) – Tensors to contract

  • B (adarray) – Tensors to contract

  • axes (int or (2,) array_like) – The contraction axes. See numpy.tensordot

Returns

The tensor dot result

Return type

adarray