function¶

class nutils.function.Lowerable¶

Bases: object

Protocol for lowering to nutils.evaluable.Array.

prepare_eval(self, *, ndims, opposite=False, npoints=nutils.evaluable.NPoints<>)¶

Lower this object to a nutils.evaluable.Array.

Parameters

ndims (int) – The dimension of the Sample on which the resulting nutils.evaluable.Array will be evaluated.
opposite (bool) – Indicates which transform chain to use when evaluating the resulting Array. This has no effect when there is only one transform chain.
npoints (int or nutils.evaluable.Array or None) – The length of the points axis or None if the result should not have a points axis.

__weakref__¶: list of weak references to the object (if defined)

class nutils.function.Array(shape, dtype)¶

Bases: nutils.function.Lowerable

Base class for array valued functions.

Parameters

shape (tuple of int or Array) – The shape of the array function.
dtype (bool, int or float) – The dtype of the array elements.

shape¶

The shape of this array function.

Type: tuple of int or class:Array

ndim¶

The dimension of this array function.

Type: int

dtype¶

The dtype of the array elements.

Type: bool, int or float

classmethod cast(_Array__value, dtype=None, ndim=None)¶

Cast a value to an Array.

Parameters: value (Array, or a numpy.ndarray or similar) – The value to cast.

__len__(self)¶: Length of the first axis.

__iter__(self)¶: Iterator over the first axis.

property size¶: The total number of elements in this array.

property T¶: The transposed array.

__add__(self, _Array__other)¶: See add().

__radd__(self, _Array__other)¶: See add().

__sub__(self, _Array__other)¶: See subtract().

__rsub__(self, _Array__other)¶: See subtract().

__mul__(self, _Array__other)¶: See multiply().

__rmul__(self, _Array__other)¶: See multiply().

__truediv__(self, _Array__other)¶: See divide().

__rtruediv__(self, _Array__other)¶: See divide().

__floordiv__(self, _Array__other)¶: See floor_divide().

__rfloordiv__(self, _Array__other)¶: See floor_divide().

__pow__(self, _Array__other)¶: See power().

__rpow__(self, _Array__other)¶: See power().

__mod__(self, _Array__other)¶: See mod().

__rmod__(self, _Array__other)¶: See mod().

__pos__(self)¶: Return self.

__neg__(self)¶: See negative().

__abs__(self)¶: See abs().

sum(self, axis=None)¶: See sum().

prod(self, _Array__axis)¶: See prod().

dot(self, _Array__other, axes=None)¶: See dot().

normalized(self, _Array__axis=- 1)¶: See normalized().

normal(self, exterior=False)¶: See normal().

curvature(self, ndims=- 1)¶: See curvature().

swapaxes(self, _Array__axis1, _Array__axis2)¶: See swapaxes().

transpose(self, _Array__axes)¶: See transpose().

add_T(self, axes)¶: See add_T().

grad(self, _Array__geom, ndims=0)¶: See grad().

laplace(self, _Array__geom, ndims=0)¶: See laplace().

symgrad(self, _Array__geom, ndims=0)¶: See symgrad().

div(self, _Array__geom, ndims=0)¶: See div().

dotnorm(self, _Array__geom, axis=- 1)¶: See dotnorm().

tangent(self, _Array__vec)¶: See tangent().

ngrad(self, _Array__geom, ndims=0)¶: See ngrad().

nsymgrad(self, _Array__geom, ndims=0)¶: See nsymgrad().

choose(self, _Array__choices)¶: See choose().

class nutils.function.Argument(name, shape, *, dtype=<class 'float'>)¶

Bases: nutils.function.Array

Array valued function argument.

Parameters

name (str) – The name of this argument.
shape (tuple of int or Array) – The shape of this argument.
dtype (bool, int or float) – The dtype of the array elements.

name¶

The name of this argument.

Type: str

nutils.function.asarray(__arg)¶

Cast a value to an Array.

Parameters: value (Array, or a numpy.ndarray or similar) – The value to cast.
Returns
Return type: Array

nutils.function.zeros(shape, dtype=<class 'float'>)¶

Create a new Array of given shape and dtype, filled with zeros.

Parameters

shape (tuple of int or Array) – The shape of the new array.
dtype (bool, int or float) – The dtype of the array elements.

Returns

Return type

Array

nutils.function.ones(shape, dtype=<class 'float'>)¶

Create a new Array of given shape and dtype, filled with ones.

Parameters

shape (tuple of int or Array) – The shape of the new array.
dtype (bool, int or float) – The dtype of the array elements.

Returns

Return type

Array

nutils.function.eye(__n, dtype=<class 'float'>)¶

Create a 2-D Array with ones on the diagonal and zeros elsewhere.

Parameters

n (int) – The number of rows and columns.
dtype (bool, int or float) – The dtype of the array elements.

Returns

Return type

Array

nutils.function.levicivita(__n, dtype=<class 'float'>)¶

Create an n-D Levi-Civita symbol.

Parameters

n (int) – The dimension of the Levi-Civita symbol.
dtype (bool, int or float) – The dtype of the array elements.

Returns

Return type

Array

nutils.function.add(__left, __right)¶

Return the sum of the arguments, elementwise.

Parameters

left (Array or something that can be cast() into one) –
right (Array or something that can be cast() into one) –

Returns

Return type

Array

nutils.function.subtract(__left, __right)¶

Return the difference of the arguments, elementwise.

Parameters

left (Array or something that can be cast() into one) –
right (Array or something that can be cast() into one) –

Returns

Return type

Array

nutils.function.negative(__arg)¶

Return the negation of the argument, elementwise.

Parameters: arg (Array or something that can be cast() into one) –
Returns
Return type: Array

nutils.function.multiply(__left, __right)¶

Return the product of the arguments, elementwise.

Parameters

left (Array or something that can be cast() into one) –
right (Array or something that can be cast() into one) –

Returns

Return type

Array

nutils.function.divide(__dividend, __divisor)¶

Return the true-division of the arguments, elementwise.

Parameters

dividend (Array or something that can be cast() into one) –
divisor (Array or something that can be cast() into one) –

Returns

Return type

Array

nutils.function.floor_divide(__dividend, __divisor)¶

Return the floor-division of the arguments, elementwise.

Parameters

dividend (Array or something that can be cast() into one) –
divisor (Array or something that can be cast() into one) –

Returns

Return type

Array

nutils.function.reciprocal(__arg)¶

Return the reciprocal of the argument, elementwise.

Parameters: arg (Array or something that can be cast() into one) –
Returns
Return type: Array

nutils.function.power(__base, __exponent)¶

Return the exponentiation of the arguments, elementwise.

Parameters

base (Array or something that can be cast() into one) –
exponent (Array or something that can be cast() into one) –

Returns

Return type

Array

nutils.function.sqrt(__arg)¶

Return the square root of the argument, elementwise.

Parameters: arg (Array or something that can be cast() into one) –
Returns
Return type: Array

nutils.function.abs(__arg)¶

Return the absolute value of the argument, elementwise.

Parameters: arg (Array or something that can be cast() into one) –
Returns
Return type: Array

nutils.function.sign(__arg)¶

Return the sign of the argument, elementwise.

Parameters: arg (Array or something that can be cast() into one) –
Returns
Return type: Array

nutils.function.mod(__dividend, __divisor)¶

Return the remainder of the floored division, elementwise.

Parameters

dividend (Array or something that can be cast() into one) –
divisor (Array or something that can be cast() into one) –

Returns

Return type

Array

nutils.function.cos(__arg)¶

Return the trigonometric cosine of the argument, elementwise.

Parameters: arg (Array or something that can be cast() into one) –
Returns
Return type: Array

nutils.function.sin(__arg)¶

Return the trigonometric sine of the argument, elementwise.

Parameters: arg (Array or something that can be cast() into one) –
Returns
Return type: Array

nutils.function.tan(__arg)¶

Return the trigonometric tangent of the argument, elementwise.

Parameters: arg (Array or something that can be cast() into one) –
Returns
Return type: Array

nutils.function.arccos(__arg)¶

Return the trigonometric inverse cosine of the argument, elementwise.

Parameters: arg (Array or something that can be cast() into one) –
Returns
Return type: Array

nutils.function.arcsin(__arg)¶

Return the trigonometric inverse sine of the argument, elementwise.

Parameters: arg (Array or something that can be cast() into one) –
Returns
Return type: Array

nutils.function.arctan(__arg)¶

Return the trigonometric inverse tangent of the argument, elementwise.

Parameters: arg (Array or something that can be cast() into one) –
Returns
Return type: Array

nutils.function.arctan2(__dividend, __divisor)¶

Return the trigonometric inverse tangent of the dividend / divisor, elementwise.

Parameters: arg (Array or something that can be cast() into one) –
Returns
Return type: Array

nutils.function.cosh(__arg)¶

Return the hyperbolic cosine of the argument, elementwise.

Parameters: arg (Array or something that can be cast() into one) –
Returns
Return type: Array

nutils.function.sinh(__arg)¶

Return the hyperbolic sine of the argument, elementwise.

Parameters: arg (Array or something that can be cast() into one) –
Returns
Return type: Array

nutils.function.tanh(__arg)¶

Return the hyperbolic tangent of the argument, elementwise.

Parameters: arg (Array or something that can be cast() into one) –
Returns
Return type: Array

nutils.function.arctanh(__arg)¶

Return the hyperbolic inverse tangent of the argument, elementwise.

Parameters: arg (Array or something that can be cast() into one) –
Returns
Return type: Array

nutils.function.exp(__arg)¶

Return the exponential of the argument, elementwise.

Parameters: arg (Array or something that can be cast() into one) –
Returns
Return type: Array

nutils.function.log(__arg)¶

Return the natural logarithm of the argument, elementwise.

Parameters: arg (Array or something that can be cast() into one) –
Returns
Return type: Array

nutils.function.ln(__arg)¶

Return the natural logarithm of the argument, elementwise.

Parameters: arg (Array or something that can be cast() into one) –
Returns
Return type: Array

nutils.function.log2(__arg)¶

Return the base 2 logarithm of the argument, elementwise.

Parameters: arg (Array or something that can be cast() into one) –
Returns
Return type: Array

nutils.function.log10(__arg)¶

Return the base 10 logarithm of the argument, elementwise.

Parameters: arg (Array or something that can be cast() into one) –
Returns
Return type: Array

nutils.function.greater(__left, __right)¶

Return if the first argument is greater than the second, elementwise.

Parameters

left (Array or something that can be cast() into one) –
right (Array or something that can be cast() into one) –

Returns

Return type

Array

nutils.function.equal(__left, __right)¶

Return if the first argument equals the second, elementwise.

Parameters

left (Array or something that can be cast() into one) –
right (Array or something that can be cast() into one) –

Returns

Return type

Array

nutils.function.less(__left, __right)¶

Return if the first argument is less than the second, elementwise.

Parameters

left (Array or something that can be cast() into one) –
right (Array or something that can be cast() into one) –

Returns

Return type

Array

nutils.function.min(__a, __b)¶

Return the minimum of the arguments, elementwise.

Parameters

a (Array or something that can be cast() into one) –
b (Array or something that can be cast() into one) –

Returns

Return type

Array

nutils.function.max(__a, __b)¶

Return the maximum of the arguments, elementwise.

Parameters

a (Array or something that can be cast() into one) –
b (Array or something that can be cast() into one) –

Returns

Return type

Array

nutils.function.opposite(__arg)¶

Evaluate this function at the opposite side.

When evaluating a function arg at an interface, the function will be evaluated at one side of the interface. opposite() selects the opposite side.

Parameters: arg (Array or something that can be cast() into one) –
Returns
Return type: Array

Example

We create a one dimensional topology with two elements and a discontinuous function f that is 1 on the first element and 2 on the second:

>>> from nutils import mesh, function
>>> topo, geom = mesh.rectilinear([2])
>>> f = topo.basis('discont', 0).dot([1, 2])

Evaluating this function at the interface gives (for this particular topology) the value at the side of the first element:

>>> topo.interfaces.sample('bezier', 1).eval(f)
array([ 1.])

Using opposite() we obtain the value at the side of second element:

>>> topo.interfaces.sample('bezier', 1).eval(function.opposite(f))
array([ 2.])

It is allowed to nest opposites:

>>> topo.interfaces.sample('bezier', 1).eval(function.opposite(function.opposite(f)))
array([ 1.])

See also

mean(): the mean at an interface
jump(): the jump at an interface

nutils.function.mean(__arg)¶

Return the mean of the argument at an interface.

Parameters: arg (Array or something that can be cast() into one) –
Returns
Return type: Array

Example

We create a one dimensional topology with two elements and a discontinuous function f that is 1 on the first element and 2 on the second:

>>> from nutils import mesh, function
>>> topo, geom = mesh.rectilinear([2])
>>> f = topo.basis('discont', 0).dot([1, 2])

Evaluating the mean of this function at the interface gives:

>>> topo.interfaces.sample('bezier', 1).eval(function.mean(f))
array([ 1.5])

nutils.function.jump(__arg)¶

Return the jump of the argument at an interface.

The sign of the jump depends on the orientation of the interfaces in a Topology. Usually the jump is used as part of an inner product with the normal() of the geometry is used, which is independent of the orientation of the interfaces.

Parameters: arg (Array or something that can be cast() into one) –
Returns
Return type: Array

Example

We create a one dimensional topology with two elements and a discontinuous function f that is 1 on the first element and 2 on the second:

>>> from nutils import mesh, function
>>> topo, geom = mesh.rectilinear([2])
>>> f = topo.basis('discont', 0).dot([1, 2])

Evaluating the jump of this function at the interface gives (for this particular topology):

>>> topo.interfaces.sample('bezier', 1).eval(function.jump(f))
array([ 1.])

nutils.function.sum(__arg, axis=None)¶

Return the sum of array elements over the given axes.

Parameters

arg (Array or something that can be cast() into one) –
axis (int, a sequence of int, or None) – The axis or axes to sum. None, the default, implies all axes.

Returns

Return type

Array

nutils.function.product(__arg, axis)¶

Return the product of array elements over the given axes.

Parameters

arg (Array or something that can be cast() into one) –
axis (int, a sequence of int, or None) – The axis or axes along which the product is performed. None, the default, implies all axes.

Returns

Return type

Array

nutils.function.dot(__a, __b, axes=None)¶

Return the inner product of the arguments over the given axes, elementwise over the remanining axes.

Parameters

arg (Array or something that can be cast() into one) –
axis (int, a sequence of int, or None) – The axis or axes along which the inner product is performed. If the second argument has one dimension and axes is None, the default, the inner product of the second argument with the first axis of the first argument is computed. Otherwise axes=None is not allowed.

Returns

Return type

Array

nutils.function.trace(__arg, axis1=- 2, axis2=- 1)¶

Return the trace, the sum of the diagonal, of an array over the two given axes, elementwise over the remanining axes.

Parameters

arg (Array or something that can be cast() into one) –
axis1 (int) – The first axis. Defaults to the next to last axis.
axis2 (int) – The second axis. Defaults to the last axis.

Returns

Return type

Array

nutils.function.norm2(__arg, axis=- 1)¶

Return the 2-norm of the argument over the given axis, elementwise over the remanining axes.

Parameters

arg (Array or something that can be cast() into one) –
axis (int) – The axis along which the norm is computed. Defaults to the last axis.

Returns

Return type

Array

nutils.function.normalized(__arg, axis=- 1)¶

Return the argument normalized over the given axis, elementwise over the remanining axes.

Parameters

arg (Array or something that can be cast() into one) –
axis (int) – The axis along which the norm is computed. Defaults to the last axis.

Returns

Return type

Array

See also

norm2(): The 2-norm.

nutils.function.matmat(__arg0, *args)¶: helper function, contracts last axis of arg0 with first axis of arg1, etc

nutils.function.inverse(__arg, __axes=(- 2, - 1))¶

Return the inverse of the argument along the given axes, elementwise over the remaining axes.

Parameters

arg (Array or something that can be cast() into one) –
axes (tuple of two int) – The two axes along which the inverse is computed. Defaults to the last two axes.

Returns

Return type

Array

nutils.function.determinant(__arg, __axes=(- 2, - 1))¶

Return the determinant of the argument along the given axes, elementwise over the remaining axes.

Parameters

arg (Array or something that can be cast() into one) –
axes (tuple of two int) – The two axes along which the determinant is computed. Defaults to the last two axes.

Returns

Return type

Array

nutils.function.eig(__arg, __axes=(- 2, - 1), symmetric=False)¶

Return the eigenvalues and right eigenvectors of the argument along the given axes, elementwise over the remaining axes.

Parameters

arg (Array or something that can be cast() into one) –
axes (tuple of two int) – The two axes along which the determinant is computed. Defaults to the last two axes.
symmetric (bool) – Indicates if the argument is Hermitian.

Returns

eigval (Array) – The diagonalized eigenvalues.
eigvec (Array) – The right eigenvectors.

nutils.function.takediag(__arg, __axis=- 2, __rmaxis=- 1)¶

Return the diagonal of the argument along the given axes.

Parameters

arg (Array or something that can be cast() into one) –
axis (int) – The axis to keep. Defaults to the next to last axis.
rmaxis (int) – The axis to remove. Defaults to the last axis.

Returns

Return type

Array

See also

diagonalize(): The complement operation.

nutils.function.diagonalize(__arg, __axis=- 1, __newaxis=- 1)¶

Return argument with newaxis such that axis and newaxis` is diagonal.

Parameters

arg (Array or something that can be cast() into one) –
axis (int) – The axis to diagonalize. Defaults to the last axis w.r.t. the argument.
newaxis (int) – The axis to add. Defaults to the last axis w.r.t. the return value.

Returns

Return type

Array

See also

takediag(): The complement operation.

nutils.function.cross(__arg1, __arg2, axis=- 1)¶

Return the cross product of the arguments over the given axis, elementwise over the remaining axes.

Parameters

arg1 (Array or something that can be cast() into one) –
arg2 (Array or something that can be cast() into one) –
axis (int) – The axis along which the cross product is computed. Defaults to the last axis.

Returns

Return type

Array

See also

takediag(): The inverse operation.

nutils.function.outer(arg1, arg2=None, axis=0)¶: outer product

nutils.function.transpose(__array, __axes=None)¶

Permute the axes of an array.

Parameters

array (Array or something that can be cast() into one) –
axes (sequence of int) – Permutation of range(array.ndim). Defaults to reversing the order of the axes, reversed(range(array.ndim)).

Returns

The transposed array. Axis i of the resulting array corresponds to axis axes[i] of the argument.

Return type

Array

nutils.function.insertaxis(__array, axis, length)¶

Insert an axis with given length.

Parameters

array (Array or something that can be cast() into one) –
axis (class:int) – The position of the inserted axis. Negative values count from the end of the resulting array.
length (int or Array) – The length of the inserted axis.

Returns

Return type

Array

nutils.function.expand_dims(__array, axis)¶

Insert a singleton axis.

Parameters

array (Array or something that can be cast() into one) –
axis (class:int) – The position of the inserted axis. Negative values count from the end of the resulting array.

Returns

Return type

Array

nutils.function.repeat(__array, __n, axis)¶

Repeat the given axis of an array n times.

Parameters

array (Array or something that can be cast() into one) –
n (int or Array) – The number of repetitions.
axis (class:int) – The position of the axis to be repeated.

Returns

Return type

Array

nutils.function.swapaxes(__array, __axis1, __axis2)¶

Swap two axes of an array.

Parameters

array (Array or something that can be cast() into one) –
axis1 (int) – The axes to be swapped.
axis2 (int) – The axes to be swapped.

Returns

Return type

Array

nutils.function.ravel(__array, axis)¶

Ravel two consecutive axes of an array.

Parameters

array (Array or something that can be cast() into one) –
axis (int) – The first of the two consecutive axes to ravel.

Returns

Return type

Array

See also

unravel(): The reverse operation.

nutils.function.unravel(__array, axis, shape)¶

Unravel an axis to the given shape.

Parameters

array (Array or something that can be cast() into one) –
axis (int) – The axis to unravel.
shape (two-tuple of int or Array) – The shape of the unraveled axes.

Returns

The resulting array with unraveled axes axis and axis+1.

Return type

Array

See also

ravel(): The reverse operation.

nutils.function.take(__array, __indices, axis)¶

Take elements from an array along an axis.

Parameters

array (Array or something that can be cast() into one) –
indices (Array with dtype int or bool or something that can be cast() into one) – The indices of elements to take. The array of indices may have any dimension, including zero. However, if the array is boolean, the array must 1-D.
axis (int) – The axis to take elements from or, if indices has more than one dimension, the first axis of a range of indices.ndim axes to take elements from.

Returns

The array with the taken elements. The original axis is replaced by indices.ndim axes.

Return type

Array

See also

get(): Special case of take() with scalar index.
inflate(): The complement operation.

nutils.function.get(__array, __axis, __index)¶

Get one element from an array along an axis.

Parameters

array (Array or something that can be cast() into one) –
axis (int) – The axis to get an element from.
index (int or Array) – The index of the element to get.

Returns

Return type

Array

See also

take(): Take elements from an array along an axis.
kronecker(): The complement operation.

nutils.function.inflate(__array, indices, length, axis)¶

Inflate elements in an axis of given length.

Parameters

array (Array or something that can be cast() into one) –
indices (Array with dtype int or bool or something that can be cast() into one) – The indices of elements in the resulting array. The array of indices may have any dimension, including zero.
length (int or Array) – The length of the inflated axis.
axis (int) – The axis to inflate. The elements are inflated from axes axis to axis+indices.ndim of the input array.

Returns

The inflated array with axes axis to axis+indices.ndim of the input array inflated to the single axis.

Return type

Array

See also

kronecker(): Special case of inflate() with a scalar index.
take(): The complement operation.

nutils.function.kronecker(__array, axis, length, pos)¶

Position an element in an axis of given length.

Parameters

array (Array or something that can be cast() into one) –
axis (int) – The axis to inflate. The elements are inflated from axes axis to axis+indices.ndim of the input array.
length (int or Array) – The length of the inflated axis.
pos (int or Array) – The inde of the element in the resulting array.

Returns

Return type

Array

See also

inflate(): Inflate elements in an axis of given length.
get(): The complement operation.

nutils.function.concatenate(__arrays, axis=0)¶

Join arrays along an existing axis.

Parameters

arrays (sequence of Array or something that can be cast() into one) –
axis (int) – The existing axis along which the arrays are joined.

Returns

Return type

Array

See also

stack(): Join arrays along an new axis.

nutils.function.stack(__arrays, axis=0)¶

Join arrays along a new axis.

Parameters

arrays (sequence of Array or something that can be cast() into one) –
axis (int) – The axis in the resulting array along which the arrays are joined.

Returns

Return type

Array

See also

stack(): Join arrays along an new axis.

nutils.function.find(__array)¶

Return indices of true elements

Parameters: array (a boolean Array or something that can be cast() into one) –
Returns
Return type: Array of int

nutils.function.replace_arguments(__array, __arguments)¶

Replace arguments with Array objects.

Parameters

array (Array or something that can be cast() into one) –
arguments (dict of str and Array) – The argument name to array mapping.

Returns

Return type

Array

nutils.function.derivative(__arg, __var)¶

Differentiate arg to var.

Parameters

arg (Array or something that can be cast() into one) –
var (Array or something that can be cast() into one) –

Returns

Return type

Array

nutils.function.localgradient(__arg, __ndims)¶

Return the gradient of the argument to the local coordinate system.

Parameters

arg (Array or something that can be cast() into one) –
ndims (int) – The dimension of the local coordinate system.

Returns

Return type

Array

nutils.function.grad(__arg, __geom, ndims=0)¶

Return the gradient of the argument to the given geometry.

Parameters

arg (Array or something that can be cast() into one) –
geom (Array or something that can be cast() into one) –
ndims (int) – The dimension of the local coordinate system.

Returns

Return type

Array

nutils.function.normal(__geom, exterior=False)¶

Return the normal of the geometry.

Parameters

geom (Array or something that can be cast() into one) –
exterior (bool) –

Returns

Return type

Array

nutils.function.dotnorm(__arg, __geom, axis=- 1)¶

Return the inner product of an array with the normal of the given geometry.

Parameters

arg (Array or something that can be cast() into one) – The array.
geom (Array or something that can be cast() into one) – The geometry. This must be a 1-D array.
axis (int) – The axis of arg along which the inner product should be performed. Defaults to the last axis.

Returns

Return type

Array

nutils.function.tangent(__geom, __vec)¶

Return the tangent.

Parameters

geom (Array or something that can be cast() into one) –
vec (Array or something that can be cast() into one) –

Returns

Return type

Array

nutils.function.jacobian(__geom, __ndims=None)¶

Return the absolute value of the determinant of the Jacobian matrix of the given geometry.

Parameters

arg (Array or something that can be cast() into one) – The array.
geom (Array or something that can be cast() into one) – The geometry. This must be a 1-D array.
axis (int) – The axis of arg along which the inner product should be performed. Defaults to the last axis.

Returns

Return type

Array

nutils.function.J(__geom, __ndims=None)¶

Return the absolute value of the determinant of the Jacobian matrix of the given geometry.

Alias of jacobian().

nutils.function.surfgrad(__arg, *vars)¶

Return the surface gradient of the argument to the given geometry.

Parameters

arg (Array or something that can be cast() into one) –
geom (Array or something that can be cast() into one) –

Returns

Return type

Array

nutils.function.curvature(__geom, ndims=- 1)¶

Return the curvature of the given geometry.

Parameters

geom (Array or something that can be cast() into one) –
ndims (int) –

Returns

Return type

Array

nutils.function.div(__arg, __geom, ndims=0)¶

Return the divergence of arg w.r.t. the given geometry.

Parameters

arg (Array or something that can be cast() into one) –
geom (Array or something that can be cast() into one) –
ndims (int) –

Returns

Return type

Array

nutils.function.laplace(__arg, __geom, ndims=0)¶

Return the Laplacian of arg w.r.t. the given geometry.

Parameters

arg (Array or something that can be cast() into one) –
geom (Array or something that can be cast() into one) –
ndims (int) –

Returns

Return type

Array

nutils.function.symgrad(__arg, __geom, ndims=0)¶

Return the symmetric gradient of arg w.r.t. the given geometry.

Parameters

arg (Array or something that can be cast() into one) –
geom (Array or something that can be cast() into one) –
ndims (int) –

Returns

Return type

Array

nutils.function.ngrad(__arg, __geom, ndims=0)¶

Return the inner product of the gradient of arg with the normal of the given geometry.

Parameters

arg (Array or something that can be cast() into one) –
geom (Array or something that can be cast() into one) –
ndims (int) –

Returns

Return type

Array

nutils.function.nsymgrad(__arg, __geom, ndims=0)¶

Return the inner product of the symmetric gradient of arg with the normal of the given geometry.

Parameters

arg (Array or something that can be cast() into one) –
geom (Array or something that can be cast() into one) –
ndims (int) –

Returns

Return type

Array

nutils.function.isarray(__arg)¶: Test if the argument is an instance of Array.

nutils.function.rootcoords(__ndims)¶: Return the root coordinates.

nutils.function.Elemwise(__data, __index, dtype)¶: elemwise

nutils.function.Sampled(__points, expect)¶

Basis-like identity operator.

Basis-like function that for every point in a predefined set evaluates to the unit vector corresponding to its index.

Parameters

points (1d Array) – Present point coordinates.
expect (2d Array) – Elementwise constant that evaluates to the predefined point coordinates; used for error checking and to inherit the shape.

nutils.function.piecewise(level, intervals, *funcs)¶

nutils.function.partition(f, *levels)¶

Create a partition of unity for a scalar function f.

When n levels are specified, n+1 indicator functions are formed that evaluate to one if and only if the following condition holds:

indicator 0: f < levels[0]
indicator 1: levels[0] < f < levels[1]
...
indicator n-1: levels[n-2] < f < levels[n-1]
indicator n: f > levels[n-1]

At the interval boundaries the indicators evaluate to one half, in the remainder of the domain they evaluate to zero such that the whole forms a partition of unity. The partitions can be used to create a piecewise continuous function by means of multiplication and addition.

The following example creates a topology consiting of three elements, and a function f that is zero in the first element, parabolic in the second, and zero again in the third element.

>>> from nutils import mesh
>>> domain, x = mesh.rectilinear([3])
>>> left, center, right = partition(x[0], 1, 2)
>>> f = (1 - (2*x[0]-3)**2) * center

Parameters

f (Array) – Scalar-valued function
levels (scalar constants or Arrays) – The interval endpoints.

Returns

The indicator functions.

Return type

list of scalar Arrays

nutils.function.heaviside(f)¶

Create a heaviside step-function based on a scalar function f.

\[ \begin{align}\begin{aligned}H(f) &= 0 && f < 0\\H(f) &= 0.5 && f = 0\\H(f) &= 1 && f > 0\end{aligned}\end{align} \]

Parameters: f (Array) – Scalar-valued function
Returns: The heaviside function.
Return type: Array

See also

partition(): generalized version of heaviside()
sign(): like heaviside() but with different levels

nutils.function.choose(__index, __choices)¶: Function equivalent of numpy.choose().

nutils.function.chain(_funcs)¶

nutils.function.vectorize(args)¶

Combine scalar-valued bases into a vector-valued basis.

Parameters: args (iterable of 1-dimensional nutils.function.Array objects) –
Returns
Return type: Array

nutils.function.add_T(__arg, axes=(- 2, - 1))¶: add transposed

class nutils.function.Basis(ndofs, nelems, index, coords)¶

Bases: nutils.function.Array

Abstract base class for bases.

A basis is a sequence of elementwise polynomial functions.

Parameters

ndofs (int) – The number of functions in this basis.
index (Array) – The element index.
coords (Array) – The element local coordinates.

Notes

Subclasses must implement get_dofs() and get_coefficients() and if possible should redefine get_support().

get_support(self, dof)¶

Return the support of basis function dof.

If dof is an int, return the indices of elements that form the support of dof. If dof is an array, return the union of supports of the selected dofs as a unique array. The returned array is always unique, i.e. strict monotonic increasing.

Parameters: dof (int or array of int or bool) – Index or indices of basis function or a mask.
Returns: support – The elements (as indices) where function dof has support.
Return type: sorted and unique numpy.ndarray

abstract get_dofs(self, ielem)¶

Return an array of indices of basis functions with support on element ielem.

If ielem is an int, return the dofs on element ielem matching the coefficients array as returned by get_coefficients(). If ielem is an array, return the union of dofs on the selected elements as a unique array, i.e. a strict monotonic increasing array.

Parameters: ielem (int or array of int or bool) – Element number(s) or mask.
Returns: dofs – A 1D Array of indices.
Return type: numpy.ndarray

get_ndofs(self, ielem)¶: Return the number of basis functions with support on element ielem.

abstract get_coefficients(self, ielem)¶

Return an array of coefficients for all basis functions with support on element ielem.

Parameters: ielem (int) – Element number.
Returns: coefficients – Array of coefficients with shape (nlocaldofs,)+(degree,)*ndims, where the first axis corresponds to the dofs returned by get_dofs().
Return type: nutils.types.frozenarray

get_coeffshape(self, ielem)¶: Return the shape of the array of coefficients for basis functions with support on element ielem.

class nutils.function.PlainBasis(coefficients, dofs, ndofs, index, coords)¶

Bases: nutils.function.Basis

A general purpose implementation of a Basis.

Use this class only if there exists no specific implementation of Basis for the basis at hand.

Parameters

coefficients (tuple of nutils.types.frozenarray objects) – The coefficients of the basis functions per transform. The order should match the transforms argument.
dofs (tuple of nutils.types.frozenarray objects) – The dofs corresponding to the coefficients argument.
ndofs (int) – The number of basis functions.
index (Array) – The element index.
coords (Array) – The element local coordinates.

class nutils.function.DiscontBasis(coefficients, index, coords)¶

Bases: nutils.function.Basis

A discontinuous basis with monotonic increasing dofs.

Parameters

coefficients (tuple of nutils.types.frozenarray objects) – The coefficients of the basis functions per transform. The order should match the transforms argument.
index (Array) – The element index.
coords (Array) – The element local coordinates.

class nutils.function.MaskedBasis(parent, indices)¶

Bases: nutils.function.Basis

An order preserving subset of another Basis.

Parameters

parent (Basis) – The basis to mask.
indices (array of ints) – The strict monotonic increasing indices of parent basis functions to keep.

class nutils.function.StructuredBasis(coeffs, start_dofs, stop_dofs, dofs_shape, transforms_shape, index, coords)¶

Bases: nutils.function.Basis

A basis for class:nutils.transformseq.StructuredTransforms.

Parameters

coeffs (tuple of tuples of arrays) – Per dimension the coefficients of the basis functions per transform.
start_dofs (tuple of arrays of ints) – Per dimension the dof of the first entry in coeffs per transform.
stop_dofs (tuple of arrays of ints) – Per dimension one plus the dof of the last entry in coeffs per transform.
dofs_shape (tuple of ints) – The tensor shape of the dofs.
transforms_shape (tuple of ints) – The tensor shape of the transforms.
index (Array) – The element index.
coords (Array) – The element local coordinates.

class nutils.function.PrunedBasis(parent, transmap, index, coords)¶

Bases: nutils.function.Basis

A subset of another Basis.

Parameters

parent (Basis) – The basis to prune.
transmap (one-dimensional array of ints) – The indices of transforms in parent that form this subset.
index (Array) – The element index.
coords (Array) – The element local coordinates.

class nutils.function.Namespace(*, default_geometry_name='x', fallback_length=None, functions=None, **kwargs)¶

Bases: object

Namespace for Array objects supporting assignments with tensor expressions.

The Namespace object is used to store Array objects.

>>> from nutils import function
>>> ns = function.Namespace()
>>> ns.A = function.zeros([3, 3])
>>> ns.x = function.zeros([3])
>>> ns.c = 2

In addition to the assignment of Array objects, it is also possible to specify an array using a tensor expression string — see nutils.expression.parse() for the syntax. All attributes defined in this namespace are available as variables in the expression. If the array defined by the expression has one or more dimensions the indices of the axes should be appended to the attribute name. Examples:

>>> ns.cAx_i = 'c A_ij x_j'
>>> ns.xAx = 'x_i A_ij x_j'

It is also possible to simply evaluate an expression without storing its value in the namespace by passing the expression to the method eval_ suffixed with appropriate indices:

>>> ns.eval_('2 c')
Array<>
>>> ns.eval_i('c A_ij x_j')
Array<3>
>>> ns.eval_ij('A_ij + A_ji')
Array<3,3>

For zero and one dimensional expressions the following shorthand can be used:

>>> '2 c' @ ns
Array<>
>>> 'A_ij x_j' @ ns
Array<3>

Sometimes the dimension of an expression cannot be determined, e.g. when evaluating the identity array:

>>> ns.eval_ij('δ_ij')
Traceback (most recent call last):
...
nutils.expression.ExpressionSyntaxError: Length of axis cannot be determined from the expression.
δ_ij
  ^

There are two ways to inform the namespace of the correct lengths. The first is to assign fixed lengths to certain indices via keyword argument length_<indices>:

>>> ns_fixed = function.Namespace(length_ij=2)
>>> ns_fixed.eval_ij('δ_ij')
Array<2,2>

Note that evaluating an expression with an incompatible length raises an exception:

>>> ns = function.Namespace(length_i=2)
>>> ns.a = numpy.array([1,2,3])
>>> 'a_i' @ ns
Traceback (most recent call last):
...
nutils.expression.ExpressionSyntaxError: Length of index i is fixed at 2 but the expression has length 3.
a_i
  ^

The second is to define a fallback length via the fallback_length argument:

>>> ns_fallback = function.Namespace(fallback_length=2)
>>> ns_fallback.eval_ij('δ_ij')
Array<2,2>

When evaluating an expression through this namespace the following functions are available: opposite, sin, cos, tan, sinh, cosh, tanh, arcsin, arccos, arctan2, arctanh, exp, abs, ln, log, log2, log10, sqrt and sign.

Additional pointwise functions can be passed to argument functions. All functions should take Array objects as arguments and must return an Array with as shape the sum of all shapes of the arguments.

>>> def sqr(a):
...   return a**2
>>> def mul(a, b):
...   return a[(...,)+(None,)*b.ndim] * b[(None,)*a.ndim]
>>> ns_funcs = function.Namespace(functions=dict(sqr=sqr, mul=mul))
>>> ns_funcs.a = numpy.array([1,2,3])
>>> ns_funcs.b = numpy.array([4,5])
>>> 'sqr(a_i)' @ ns_funcs # same as 'a_i^2'
Array<3>
>>> ns_funcs.eval_ij('mul(a_i, b_j)') # same as 'a_i b_j'
Array<3,2>
>>> 'mul(a_i, a_i)' @ ns_funcs # same as 'a_i a_i'
Array<>

Parameters

default_geometry_name (str) – The name of the default geometry. This argument is passed to nutils.expression.parse(). Default: 'x'.
fallback_length (int, optional) – The fallback length of an axis if the length cannot be determined from the expression.
length_<indices> (int) – The fixed length of <indices>. All axes in the expression marked with one of the <indices> are asserted to have the specified length.
functions (dict, optional) – Pointwise functions that should be available in the namespace, supplementing the default functions listed above. All functions should return arrays with as shape the sum of all shapes of the arguments.

arg_shapes¶

A readonly map of argument names and shapes.

Type: dict

default_geometry_name¶

The name of the default geometry. See argument with the same name.

Type: str

__getstate__(self)¶: Pickle instructions

__setstate__(self, d)¶: Unpickle instructions

property default_geometry¶

The default geometry, shorthand for getattr(ns, ns.default_geometry_name).

Type: nutils.function.Array

__call__(*args, **subs)¶

Return a copy with arguments replaced by subs.

Return a copy of this namespace with Argument objects replaced according to subs.

Parameters: **subs (dict of str and nutils.function.Array objects) – Replacements of the Argument objects, identified by their names.
Returns: ns – The copy of this namespace with replaced Argument objects.
Return type: Namespace

copy_(self, *, default_geometry_name=None)¶: Return a copy of this namespace.

__getattr__(self, name)¶: Get attribute name.

__setattr__(self, name, value)¶: Set attribute name to value.

__delattr__(self, name)¶: Delete attribute name.

__rmatmul__(expr: str) → nutils.function.Array ¶
__rmatmul__(expr: Union[Tuple[str, …], List[str]]) → Tuple[nutils.function.Array, …]: Evaluate zero or one dimensional expr or a list of expressions.