Implementation Details¶

Data Structures¶

spacejam uses 1D numpy.ndarrays to return partial derivatives, where the \(j\) th entry contains \(\frac{\partial f_i}{\partial x_j}\) for \(i = 1, ... m\) and \(j = 1, ... k\). In general, this is for \(m\) different functions that are a function of \(k\) different variables.
The internal convenience function spacejam.autodiff.AutoDiff._matrix stacks these 1D arrays into an \(m\times k\) numpy.ndarray Jacobian matrix for ease of viewing, as described in Demo III: Vector function with vector input.

API¶

`spacejam.autodiff`¶

class spacejam.autodiff.AutoDiff(func, p, kwargs=None)[source]¶

Performs automatic differentiation (AD) on functions input by user.

AD if performed by transforming f(x1, x2, …) to f(p_x1, p_x2, …), where p_xi is returned from spacejam.dual.Dual . The final result is then returned in a series of 1D numpy.ndarray or formatted matrices depending on if the user specified functions F are multivariable or not.

r¶: numpy.ndarray – User defined function(s) F evaluated at p.

d¶: numpy.ndarray – Corresponding derivative, gradient, or Jacobian of user defined functions(s).

__init__(func, p, kwargs=None)[source]¶

Parameters:	func (numpy.ndarray) – user defined function(s). p (numpy.ndarray) – user defined point(s) to evaluate derivative/gradient/Jacobian at.

_ad(func, p, kwargs=None)[source]¶

Internally computes func(p) and its derivative(s).

Notes

_ad returns a nested 1D numpy.ndarray to be formatted internally accordingly in spacejam.autodiff.AutoDiff.__init__ .

Parameters:	func (numpy.ndarray) – function(s) specified by user. p (numpy.ndarray) – point(s) specified by user.

_matrix(F, p, result)[source]¶

Internally formats result returned by spacejam.autodiff.AutoDiff._ad into matrices.

Parameters:

F (numpy.ndarray) – functionss specified by user.
p (numpy.ndarray) – point(s) specified by user.
result (numpy.ndarray) – Nested 1D numpy.ndarray to be formatted into matrices.

Returns:

Fs (numpy.ndarray) – Column matrix of functions evaluated at points(s).
jac (numpy.ndarray) – Corresponding Jacobian matrix.

`spacejam.dual`¶

class spacejam.dual.Dual(real, dual=None, idx=None, x=array(1))[source]¶

Creates dual numbers and defines dual number math.

A real number a is taken in and its dual counterpart a + eps [1.00] is returned to facilitate automatic differentiation in spacejam.autodiff .

Notes

The dual part can optionally be returned as a “dual basis vector” [0 1 0] if the user function f is multivariable and the partial derivative \(\partial f / \partial x_2\) is desired, for example.

r¶: float – real part of spacejam.dual.Dual .

d¶: numpy.ndarray – dual part of spacejam.dual.Dual .

__add__(other)[source]¶

Returns the addition of self and other

Parameters:	self (Dual object) – other (Dual object, float, or int) –
Returns:	z
Return type:	Dual object that is the sum of self and other

Examples

>>> z = Dual(1, 2) + Dual(3, 4)
>>> print(z)
4.00 + eps 6.00
>>> z = 2 + Dual(1, 2)
>>> print(z)
3.00 + eps 2.00

__init__(real, dual=None, idx=None, x=array(1))[source]¶

Parameters:	real (int/float) – real part of `spacejam.dual.Dual` . dual (float) – dual part of `spacejam.dual.Dual` (default 1.00) . idx (int (default None)) – index in dual part of dual basis vector. x (numpy.ndarray (default [1])) – set size of pre-allocated array for dual basis vector.

__mul__(other)[source]¶

Returns the product of self and other

Parameters:	self (Dual object) – other (Dual object, float, or int) –
Returns:	z
Return type:	Dual object that is the product of self and other

Examples

>>> z = Dual(1, 2) * Dual(3, 4)
>>> print(z)
3.00 + eps 10.00
>>> z = 2 * Dual(1, 2)
>>> print(z)
2.00 + eps 4.00

__neg__()[source]¶

Returns negation of self

Examples

>>> z = Dual(1, 2)
>>> print(-z)
-1.00 - eps 2.00

__pos__()[source]¶

Returns self

Examples

>>> z = Dual(1, 2)
>>> print(+z)
1.00 + eps 2.00

__pow__(other)[source]¶

Performs (self.r + eps self.d) ** (other.r + eps other.d)

Parameters:	self (Dual object) – other (Dual object, float, or int) –
Returns:	z
Return type:	Dual object that is self raised to the other power

Examples

>>> z = Dual(1, 2) ** Dual(3, 4)
>>> print(z)
1.00 + eps 6.00

__radd__(other)¶

Returns the addition of self and other

Parameters:	self (Dual object) – other (Dual object, float, or int) –
Returns:	z
Return type:	Dual object that is the sum of self and other

Examples

>>> z = Dual(1, 2) + Dual(3, 4)
>>> print(z)
4.00 + eps 6.00
>>> z = 2 + Dual(1, 2)
>>> print(z)
3.00 + eps 2.00

__repr__()[source]¶

Prints self in the form a_r + eps a_d, where self = Dual(a_r, a_d), a_r and a_d are the real and dual part of self, respectively, and both terms are automatically rounded to two decimal places

Returns:	z
Return type:	Dual object that is the product of self and other

Examples

>>> z = Dual(1, 2)
>>> print(z)
1.00 + eps 2.00

__rmul__(other)¶

Returns the product of self and other

Parameters:	self (Dual object) – other (Dual object, float, or int) –
Returns:	z
Return type:	Dual object that is the product of self and other

Examples

>>> z = Dual(1, 2) * Dual(3, 4)
>>> print(z)
3.00 + eps 10.00
>>> z = 2 * Dual(1, 2)
>>> print(z)
2.00 + eps 4.00

__rsub__(other)[source]¶

Returns the subtraction of other from self

Parameters:	self (Dual object) – other (Dual object, float, or int) –
Returns:	z – difference of other and self
Return type:	Dual object

Examples

>>> z = 2 - Dual(1, 2)
>>> print(z)
1.00 - eps 2.00

__rtruediv__(other)[source]¶

Returns the quotient of other and self

Parameters:	self (Dual object) – other (Dual object, float, or int) –
Returns:	z
Return type:	Dual object that is the product of self and other

Examples

>>> z = 2 / Dual(1, 2)
>>> print(z)
2.00 - eps 4.00

__sub__(other)[source]¶

Returns the subtraction of self and other

Parameters:	self (Dual object) – other (Dual object, float, or int) –
Returns:	z – difference of self and other
Return type:	Dual object

Notes

Subtraction does not commute in general. A specialized __rsub__ is required.

Examples

>>> z = Dual(1, 2) - Dual(3, 4)
>>> print(z)
-2.00 - eps 2.00
>>> z = Dual(1, 2) - 2
>>> print(z)
-1.00 + eps 2.00

__truediv__(other)[source]¶

Returns the quotient of self and other

Parameters:	self (Dual object) – other (Dual object, float, or int) –
Returns:	z
Return type:	Dual object that is the quotient of self and other

Examples

>>> z = Dual(1, 2) / 2
>>> print(z)
0.50 + eps 1.00
>>> z = Dual(3, 4) / Dual(1, 2)
>>> print(z)
3.00 - eps 2.00

cos()[source]¶

Returns the cosine of a

Parameters:	self (Dual object) –
Returns:	z
Return type:	cosine of self

Examples

>>> z = np.cos(Dual(0, 1))
>>> print(z)
1.00 + eps -0.00

exp()[source]¶

Returns e**self

Parameters:	self (Dual object) –
Returns:	z
Return type:	e**self

Examples

>>> z = np.exp(Dual(1, 2))
>>> print(z)
2.72 + eps 5.44

sin()[source]¶

Returns the sine of a

Parameters:	self (Dual object) –
Returns:	z
Return type:	sine of self

Examples

>>> z = np.sin(Dual(0, 1))
>>> print(z)
0.00 + eps 1.00

tan()[source]¶

Returns the tangent of a

Parameters:	self (Dual object) –
Returns:	z
Return type:	tangent of self

Examples

>>> z = np.tan(Dual(0,1))
>>> print(z)
0.00 + eps 1.00

`spacejam.integrators`¶

spacejam.integrators.amsi(func, X_old, h=0.001, X_tol=0.1, i_tol=100.0, kwargs=None)[source]¶

First order Adams-Moulton method (AKA Trapezoid)

Parameters:	func (function) – User defined function to be integrated. X_old (numpy.ndarray) – Initial input to user function h (float (default 1E-3)) – Timestep X_tol (float (default 1E-1)) – Minimum difference between Newton-Raphson iterates to terminate on. i_tol (int (default 1E2)) – Maximum number of Newton-Raphson iterations. Entire simulation terminates if this number is exceeded. kwargs (dict (default None)) – optional arguments to be supplied to user defined function.
Returns:	X_new – Final X_n+1 found from root finding of implicit method
Return type:	numpy.ndarray

spacejam.integrators.amsii(func, X_n, X_nn, h=0.001, X_tol=0.1, i_tol=100.0, kwargs=None)[source]¶

Second order Adams-Moulton method

Parameters:	func (function) – User defined function to be integrated. X_n (numpy.ndarray) – X_n X_nn (numpy.ndarray) – X_n-1 h (float (default 1E-3)) – Timestep X_tol (float (default 1E-1)) – Minimum difference between Newton-Raphson iterates to terminate on. i_tol (int (default 1E2)) – Maximum number of Newton-Raphson iterations. Entire simulation terminates if this number is exceeded. kwargs (dict (default None)) – optional arguments to be supplied to user defined function.
Returns:	X_new – Final X_n+1 found from root finding of implicit method
Return type:	numpy.ndarray

spacejam.integrators.amso(func, X_old, h=0.001, X_tol=0.1, i_tol=100.0, kwargs=None)[source]¶

Zeroth order Adams-Moulton method (AKA Backward Euler)

Parameters:	func (function) – User defined function to be integrated. X_old (numpy.ndarray) – Initial input to user function h (float (default 1E-3)) – Timestep X_tol (float (default 1E-1)) – Minimum difference between Newton-Raphson iterates to terminate on. i_tol (int (default 1E2)) – Maximum number of Newton-Raphson iterations. Entire simulation terminates if this number is exceeded. kwargs (dict (default None)) – optional arguments to be supplied to user defined function.
Returns:	X_new – Final X_n+1 found from root finding of implicit method
Return type:	numpy.ndarray

Examples

>>>

Implementation Details¶

Data Structures¶

API¶

spacejam.autodiff¶

spacejam.dual¶

spacejam.integrators¶

`spacejam.autodiff`¶

`spacejam.dual`¶

`spacejam.integrators`¶