function¶

class nutils.function.Lowerable¶

Bases: object

Protocol for lowering to nutils.evaluable.Array.

lower(self, points_shape, transform_chains, coordinates)¶

Lower this object to a nutils.evaluable.Array.

Parameters

points_shape (tuple of scalar, integer nutils.evaluable.Array) – The shape of the leading points axes that are to be added to the lowered nutils.evaluable.Array.
transform_chains (mapping of str to nutils.transform.EvaluableTransformChain pairs) –
coordinates (mapping of str to nutils.evaluable.Array objects) – The coordinates at which the function will be evaluated.

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

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

Bases: numpy.lib.mixins.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, nutils.function.Array]¶: The total number of elements in this array.

property T: nutils.function.Array¶: The transposed array.

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, refgeom=None)¶: 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().

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)¶: See conjugate().

conj(self)¶: See conjugate().

property real¶: See real().

property imag¶: See imag().

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

Bases: nutils.function.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: nutils.function.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.implements(np_function)¶: Register an __array_function__ or __array_ufunc__ implementation for Array objects.

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