function

class nutils.function.LowerArgs(points_shape, transform_chains, coordinates)

Bases: tuple

Arguments for Lowerable.lower

Parameters:
property points_shape

Alias for field number 0

property transform_chains

Alias for field number 1

property coordinates

Alias for field number 2

__getnewargs__(self)

Return self as a plain tuple. Used by copy and pickle.

static __new__(_cls, points_shape, transform_chains, coordinates)

Create new instance of LowerArgs(points_shape, transform_chains, coordinates)

__repr__(self)

Return a nicely formatted representation string

class nutils.function.Lowerable

Bases: object

Protocol for lowering to nutils.evaluable.Array.

lower(self, args)

Lower this object to a nutils.evaluable.Array.

Parameters:

args (LowerArgs) –

__weakref__

list of weak references to the object (if defined)

class nutils.function.Array(shape, dtype, spaces, arguments)

Bases: NDArrayOperatorsMixin

Base class for array valued functions.

Parameters:
  • shape (tuple of int) – The shape of the array function.

  • dtype (bool, int, float or complex) – The dtype of the array elements.

  • spaces (frozenset of str) – The spaces this array function is defined on.

  • arguments (mapping of str) – The mapping of argument names to their shapes and dtypes for all arguments of this array function.

shape

The shape of this array function.

Type:

tuple of int

ndim

The dimension of this array function.

Type:

int

dtype

The dtype of the array elements.

Type:

bool, int, float or complex

spaces

The spaces this array function is defined on.

Type:

frozenset of str

arguments

The mapping of argument names to their shapes and dtypes for all arguments of this array function.

Type:

mapping of str

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: Union[int, Array]

The total number of elements in this array.

property T: Array

The transposed array.

sum(self, axis=None)

Return the sum of array elements over the given axes.

Warning

This method will change in future to match Numpy’s equivalent method, which sums over all axes by default. During transition, use of this method without an axis argument will raise a warning, and later an error, if the input array is of ndim >= 2.

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 summation over the last axis.

Return type:

Array

prod(self, _Array__axis)

Return the product of array elements over the given axes.

Parameters:

axis (int, a sequence of int, or None) – The axis or axes along which the product is performed. None, the default, implies all axes.

Return type:

Array

dot(self, _Array__other, axes=None)

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

Warning

This method will change in future to match Numpy’s equivalent method, which does not support an axis argument and has different behaviour in case of higher dimensional input. During transition, use of this method for any situation other than the contraction of two vectors will raise a warning, and later an error. For continuity, use numpy.dot, numpy.matmul, or the @ operator instead.

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.

Return type:

Array

normalized(self, _Array__axis=-1)

See normalized().

normal(self, refgeom=None)

See normal().

curvature(self, ndims=-1)

See curvature().

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().

curl(self, _Array__geom)

See curl().

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().

eval(self, /, **arguments)

Evaluate this function.

derivative(self, _Array__var)

See derivative().

replace(self, _Array__arguments)

Return a copy with arguments applied.

contains(self, _Array__name)

Test if target occurs in this function.

conjugate(self)

Return the complex conjugate, elementwise.

Returns:

The complex conjugate.

Return type:

Array

conj(self)

Return the complex conjugate, elementwise.

Returns:

The complex conjugate.

Return type:

Array

property real

Return the real part of the complex argument.

Returns:

The real part of the complex argument.

Return type:

Array

property imag

Return the imaginary part of the complex argument.

Returns:

The imaginary part of the complex argument.

Return type:

Array

class nutils.function.Custom(args, shape, dtype, npointwise=0)

Bases: Array

Combined nutils.function and nutils.evaluable array base class.

Ordinary Array subclasses should define the Array.lower method, which returns the corresponding nutils.evaluable.Array with the proper amount of points axes. In many cases the Array subclass is trivial and the corresponding nutils.evaluable.Array contains all the specifics. For those situations the Custom base class exists. Rather than defining the Array.lower method, this base class allows you to define a Custom.evalf() and optionally a Custom.partial_derivative(), which are used to instantiate a generic nutils.evaluable.Array automatically during lowering.

By default the Array arguments passed to the constructor are unmodified. Broadcasting and singleton expansion, if required, should be applied before passing the arguments to the constructor of Custom. It is possible to declare npointwise leading axes as being pointwise. In that case Custom applies singleton expansion to the leading pointwise axes and the shape of the result passed to Custom should not include the pointwise axes.

For internal reasons, both evalf and partial_derivative must be decorated as classmethod or staticmethod, meaning that they will not receive a reference to self when called. Instead, all relevant data should be passed to evalf via the constructor argument args. The constructor will automatically distinguish between Array and non-Array arguments, and pass the latter on to evalf unchanged. The partial_derivative will not be called for those arguments.

The lowered array does not have a Nutils hash by default. If this is desired, the methods evalf() and partial_derivative() can be decorated with nutils.types.hashable_function() in addition to classmethod or staticmethod.

Parameters:
  • args (iterable of Array objects or immutable and hashable objects) – The arguments of this array function.

  • shape (tuple of int or Array) – The shape of the array function without leading pointwise axes.

  • dtype (bool, int, float or complex) – The dtype of the array elements.

  • npointwise (int) – The number of leading pointwise axis.

Example

The following class implements multiply() using Custom without broadcasting and for float arrays only.

>>> class Multiply(Custom):
...
...   def __init__(self, left: IntoArray, right: IntoArray) -> None:
...     # Broadcast the arrays. `broadcast_arrays` automatically casts the
...     # arguments to `Array`.
...     left, right = broadcast_arrays(left, right)
...     # Dtype coercion is beyond the scope of this example.
...     if left.dtype != float or right.dtype != float:
...       raise ValueError('left and right arguments should have dtype float')
...     # We treat all axes as pointwise, hence parameter `shape`, the shape
...     # of the remainder, is empty and `npointwise` is the dimension of the
...     # arrays.
...     super().__init__(args=(left, right), shape=(), dtype=float, npointwise=left.ndim)
...
...   @staticmethod
...   def evalf(left: numpy.ndarray, right: numpy.ndarray) -> numpy.ndarray:
...     # Because all axes are pointwise, the evaluated `left` and `right`
...     # arrays are 1d.
...     return left * right
...
...   @staticmethod
...   def partial_derivative(iarg: int, left: Array, right: Array) -> IntoArray:
...     # The arguments passed to this function are of type `Array` and the
...     # pointwise axes are omitted, hence `left` and `right` are 0d.
...     if iarg == 0:
...       return right
...     elif iarg == 1:
...       return left
...     else:
...       raise NotImplementedError
...
>>> Multiply([1., 2.], [3., 4.]).eval()
array([ 3.,  8.])
>>> a = Argument('a', (2,))
>>> Multiply(a, [3., 4.]).derivative(a).eval(a=numpy.array([1., 2.])).export('dense')
array([[ 3.,  0.],
       [ 0.,  4.]])

The following class wraps numpy.roll(), applied to the last axis of the array argument, with constant shift.

>>> class Roll(Custom):
...
...   def __init__(self, array: IntoArray, shift: int) -> None:
...     array = asarray(array)
...     # We are being nit-picky here and cast `exponent` to an `int` without
...     # truncation.
...     shift = shift.__index__()
...     # We treat all but the last axis of `array` as pointwise.
...     super().__init__(args=(array, shift), shape=array.shape[-1:], dtype=array.dtype, npointwise=array.ndim-1)
...
...   @staticmethod
...   def evalf(array: numpy.ndarray, shift: int) -> numpy.ndarray:
...     # `array` is evaluated to a `numpy.ndarray` because we passed `array`
...     # as an `Array` to the constructor. `shift`, however, is untouched
...     # because it is not an `Array`. The `array` has two axes: a points
...     # axis and the axis to be rolled.
...     return numpy.roll(array, shift, 1)
...
...   @staticmethod
...   def partial_derivative(iarg, array: Array, shift: int) -> IntoArray:
...     if iarg == 0:
...       return Roll(eye(array.shape[0]), shift).T
...     else:
...       # We don't implement the derivative to `shift`, because this is
...       # a constant `int`.
...       raise NotImplementedError
...
>>> Roll([1, 2, 3], 1).eval()
array([3, 1, 2])
>>> b = Argument('b', (3,))
>>> Roll(b, 1).derivative(b).eval().export('dense')
array([[ 0.,  0.,  1.],
       [ 1.,  0.,  0.],
       [ 0.,  1.,  0.]])
classmethod evalf(*args)

Evaluate this function for the given evaluated arguments.

This function is called with arguments that correspond to the arguments that are passed to the constructor of Custom: every instance of Array is evaluated to a numpy.ndarray with one leading axis compared to the Array and all other instances are passed as is. The return value of this method should also include a leading axis with the same length as the other array arguments have, or length one if there are no array arguments. If constructor argument npointwise is nonzero, the pointwise axes of the Array arguments are raveled and included in the single leading axis of the evaluated array arguments as well.

If possible this method should not use self, e.g. by decorating this method with staticmethod(). The result of this function must only depend on the arguments and must not mutate the arguments.

This method is equivalent to nutils.evaluable.Array.evalf up to the treatment of the leading axis.

Parameters:

*args – The evaluated arguments corresponding to the args parameter of the Custom constructor.

Returns:

The result of this function with one leading points axis.

Return type:

numpy.ndarray

classmethod partial_derivative(iarg, *args)

Return the partial derivative of this function to Custom constructor argument number iarg.

This method is only called for those arguments that are instances of Array with dtype float and have the derivative target as a dependency. It is therefor allowed to omit an implementation for some or all arguments if the above conditions are not met.

Axes that are declared pointwise via the npointwise constructor argument are omitted.

Parameters:
  • iarg (int) – The index of the argument to compute the derivative for.

  • *args – The arguments as passed to the constructor of Custom.

Returns:

The partial derivative of this function to the given argument.

Return type:

Array or similar

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

Bases: Array

Array valued function argument.

Parameters:
  • name (str) – The name of this argument.

  • shape (tuple of int) – The shape of this argument.

  • dtype (bool, int, float or complex) – 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.

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.

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.

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.

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.

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) –

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) –

Return type:

Array

nutils.function.positive(__arg)

Return the argument unchanged.

Parameters:

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

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) –

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) –

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) –

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) –

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) –

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) –

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) –

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) –

Return type:

Array

nutils.function.matmul(__arg1, __arg2)

Return the matrix product of two arrays.

Parameters:
  • arg1 (Array or something that can be cast() into one) – Input arrays.

  • arg2 (Array or something that can be cast() into one) – Input arrays.

Return type:

Array

See also

numpy.matmul

the equivalent Numpy function.

nutils.function.sign(__arg)

Return the sign of the argument, elementwise.

Parameters:

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

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) –

Return type:

Array

nutils.function.divmod(__dividend, __divisor)

Return the floor-division and remainder, elementwise.

Parameters:
  • dividend (Array or something that can be cast() into one) –

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

Return type:

tuple of Array and Array

nutils.function.cos(__arg)

Return the trigonometric cosine of the argument, elementwise.

Parameters:

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

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) –

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) –

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) –

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) –

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) –

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) –

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) –

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) –

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) –

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) –

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) –

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) –

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) –

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) –

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) –

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) –

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) –

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) –

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) –

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) –

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) –

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) –

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) –

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.

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.

Return type:

Array

nutils.function.conjugate(__arg)

Return the complex conjugate, elementwise.

Parameters:

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

Returns:

The complex conjugate.

Return type:

Array

nutils.function.conj(__arg)

Return the complex conjugate, elementwise.

Parameters:

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

Returns:

The complex conjugate.

Return type:

Array

nutils.function.real(__arg)

Return the real part of the complex argument.

Parameters:

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

Returns:

The real part of the complex argument.

Return type:

Array

nutils.function.imag(__arg)

Return the imaginary part of the complex argument.

Parameters:

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

Returns:

The imaginary part of the complex argument.

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:
  • a (Array or something that can be cast() into one) –

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

  • axes (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.

Return type:

Array

nutils.function.vdot(__a, __b, axes=None)

Return the dot product of two vectors.

If the arguments are not 1D, the arguments are flattened. The dot product is then defined as

sum(conjugate(a) * b)

Parameters:
  • a (Array or something that can be cast() into one) –

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

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.

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.

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.

Return type:

Array

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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) – 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.

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.

Return type:

Array

See also

take()

Take elements from an array along an axis.

kronecker()

The complement operation.

nutils.function.scatter(__array, length, indices)

Distribute the last dimensions of an array over a new axis.

Parameters:
  • array (Array or something that can be cast() into one) –

  • length (int) – The target length of the scattered axis.

  • indices (Array) – The indices of the elements in the resulting array.

Return type:

Array

Notes

Scatter strictly reorganizes array entries, it cannot assign multiple entries to the same position. In other words, the provided indices must be unique.

See also

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) – The length of the inflated axis.

  • pos (int or Array) – The index of the element in the resulting array.

Return type:

Array

See also

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.

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.

Return type:

Array

See also

stack()

Join arrays along an new axis.

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.

Return type:

Array

nutils.function.linearize(__array, __arguments)

Linearize functional.

Similar to derivative(), linearize takes the derivative of an array to one or more arguments, but with the derivative directions represented by arguments rather than array axes. The result is by definition linear in the new arguments.

Parameters:
  • array (Array or something that can be cast() into one) –

  • arguments (str, dict or iterable of strings) –

Example

The following example demonstrates the use of linearize with four equivalent argument specifications:

>>> u, v, p, q = [Argument(s, (), float) for s in 'uvpq']
>>> f = u**2 + p
>>> lin1 = linearize(f, 'u:v,p:q')
>>> lin2 = linearize(f, dict(u='v', p='q'))
>>> lin3 = linearize(f, ('u:v', 'p:q'))
>>> lin4 = linearize(f, (('u', 'v'), ('p', 'q')))
>>> # lin1 = lin2 == lin3 == lin4 == 2 * u * v + q
nutils.function.broadcast_arrays(*arrays)

Broadcast the given arrays.

Parameters:

*arrays (Array or similar) –

Returns:

The broadcasted arrays.

Return type:

tuple of Array

nutils.function.typecast_arrays(*arrays, min_dtype=<class 'bool'>)

Cast the given arrays to the same dtype.

Parameters:

*arrays (Array or similar) –

Returns:

The typecasted arrays.

Return type:

tuple of Array

nutils.function.broadcast_shapes(*shapes)

Broadcast the given shapes into a single shape.

Parameters:

*shapes (tuple or int) –

Returns:

The broadcasted shape.

Return type:

tuple of int

nutils.function.broadcast_to(array, shape)

Broadcast an array to a new shape.

Parameters:
  • array (Array or similar) – The array to broadcast.

  • shape (tuple of int) – The desired shape.

Returns:

The broadcasted array.

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) –

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.

Return type:

Array

nutils.function.curl(__arg, __geom)

Return the curl of the argument 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) –

Return type:

Array

nutils.function.normal(__geom, refgeom=None)

Return the normal of the geometry.

Parameters:
  • geom (Array or something that can be cast() into one) –

  • refgeom (Array, optional`) – The reference geometry. If None, the reference geometry is the tip coordinate system of the spaces on which geom is defined. The dimension of the reference geometry must be exactly one smaller than the dimension of the geometry.

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.

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) –

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:

geom (Array or something that can be cast() into one) – The geometry.

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, geom)

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) –

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) –

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) –

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) –

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) –

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) –

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) –

Return type:

Array

nutils.function.eval(funcs, /, **arguments)

Evaluate one or several Array objects.

Parameters:
  • funcs (tuple of Array objects) – Arrays to be evaluated.

  • arguments (dict (default: None)) – Optional arguments for function evaluation.

Returns:

results

Return type:

tuple of arrays

nutils.function.integral(func, sample)

Integrate a function over a sample.

Parameters:
nutils.function.sample(func, sample)

Evaluate a function in all sample points.

Parameters:
nutils.function.isarray(__arg)

Test if the argument is an instance of Array.

nutils.function.rootcoords(space, __dim)

Return the root coordinates.

nutils.function.Elemwise(__data, __index, dtype)

elemwise

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) –

Return type:

Array

nutils.function.add_T(__arg, axes=(-2, -1))

add transposed

nutils.function.dotarg(__argname, *arrays, shape=(), dtype=<class 'float'>)

Return the inner product of the first axes of the given arrays with an argument with the given name.

An argument with shape (arrays[0].shape[0], ..., arrays[-1].shape[0]) + shape will be created. Repeatedly the inner product of the result, starting with the argument, with every array from arrays is taken, where all but the first axis are treated as an outer product.

Parameters:
  • argname (str) – The name of the argument.

  • *arrays (Array or something that can be cast() into one) – The arrays to take inner products with.

  • shape (tuple of int, optional) – The shape to be appended to the argument.

  • dtype (bool, int, float or complex) – The dtype of the argument.

Returns:

The inner product with shape shape + arrays[0].shape[1:] + ... + arrays[-1].shape[1:].

Return type:

Array

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

Bases: 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

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.

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:

numpy.ndarray

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

Bases: 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 numpy.ndarray objects) – The coefficients of the basis functions per transform. The order should match the transforms argument.

  • dofs (tuple of numpy.ndarray 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: Basis

A discontinuous basis with monotonic increasing dofs.

Parameters:
  • coefficients (tuple of numpy.ndarray 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.LegendreBasis(degree, nelems, index, coords)

Bases: Basis

A discontinuous Legendre basis.

Parameters:
  • degree (int) – The degree of the basis.

  • nelems (int) – The number of elements.

  • index (Array) – The element index.

  • coords (Array) – The element local coordinates.

class nutils.function.MaskedBasis(parent, indices)

Bases: 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: 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: 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.