evaluable

The function module defines the Evaluable class and derived objects, commonly referred to as nutils functions. They represent mappings from a nutils.topology onto Python space. The notabe class of Array objects map onto the space of Numpy arrays of predefined dimension and shape. Most functions used in nutils applicatons are of this latter type, including the geometry and function bases for analysis.

Nutils functions are essentially postponed python functions, stored in a tree structure of input/output dependencies. Many Array objects have directly recognizable numpy equivalents, such as Sin or Inverse. By not evaluating directly but merely stacking operations, complex operations can be defined prior to entering a quadrature loop, allowing for a higher level style programming. It also allows for automatic differentiation and code optimization.

It is important to realize that nutils functions do not map for a physical xy-domain but from a topology, where a point is characterized by the combination of an element and its local coordinate. This is a natural fit for typical finite element operations such as quadrature. Evaluation from physical coordinates is possible only via inverting of the geometry function, which is a fundamentally expensive and currently unsupported operation.

nutils.evaluable.equalindex(n, m)

Compare two array indices.

Returns True if the two indices are certainly equal, False if they are certainly not equal, or None if equality cannot be determined at compile time.

nutils.evaluable.equalshape(N, M)

Compare two array shapes.

Returns True if all indices are certainly equal, False if any indices are certainly not equal, or None if equality cannot be determined at compile time.

nutils.evaluable.replace(func=None, depthfirst=False, recursive=False, lru=4)

decorator for deep object replacement

Generates a deep replacement method for general objects based on a callable that is applied (recursively) on individual constructor arguments.

Parameters

• func – Callable which maps an object onto a new object, or None if no replacement is made. It must have one positional argument for the object, and may have any number of additional positional and/or keyword arguments.

• depthfirst (bool) – If True, decompose each object as far a possible, then apply func to all arguments as the objects are reconstructed. Otherwise apply func directly on each new object that is encountered in the decomposition, proceding only if the return value is None.

• recursive (bool) – If True, repeat replacement for any object returned by func until it returns None. Otherwise perform a single, non-recursive sweep.

• lru (int) – Maximum size of the least-recently-used cache. A persistent weak-key dictionary is maintained for every unique set of function arguments. When the size of lru is reached, the least recently used cache is dropped.

Returns

The method that searches the object to perform the replacements.

Return type

callable

class nutils.evaluable.Evaluable(args)

Bases: nutils.types.Singleton

Base class

dependencies

collection of all function arguments

arguments

a frozenset of all arguments of this evaluable

ordereddeps

collection of all function arguments such that the arguments to dependencies[i] can be found in dependencies[:i]

dependencytree

lookup table of function arguments into ordereddeps, such that ordereddeps[i].__args[j] == ordereddeps[dependencytree[i][j]], and self.__args[j] == ordereddeps[dependencytree[-1][j]]

asciitree(self, richoutput=False)

string representation

eval(self, **evalargs)

Evaluate function on a specified element, point set.

eval_withtimes(self, times, **evalargs)

Evaluate function on a specified element, point set while measure time of each step.

class nutils.evaluable.SparseArray(chunks, shape, dtype)

Bases: nutils.evaluable.Evaluable

sparse array

class nutils.evaluable.TransformChain(args, todims=None)

Bases: nutils.evaluable.Evaluable

Chain of affine transformations.

Evaluates to a tuple of nutils.transform.TransformItem objects.

nutils.evaluable.sum(arg, axis=None)

Sum array elements over a given axis.

nutils.evaluable.dot(a, b, axes)

Contract a and b along axes.

class nutils.evaluable.AsEvaluableArray

Bases: object

Protocol for conversion into an Array.

as_evaluable_array(self)

Lower this object to a nutils.evaluable.Array.

__weakref__

list of weak references to the object (if defined)

class nutils.evaluable.Array(args, shape, dtype)

Bases: nutils.evaluable.Evaluable

Base class for array valued functions.

shape

The shape of this array function.

Type

tuple of ints

ndim

The number of dimensions of this array array function. Equal to len(shape).

Type

int

dtype

The dtype of the array elements.

Type

int, float

sum(arg, axis=None)

Sum array elements over a given axis.

dot(a, b, axes)

Contract a and b along axes.

assparse

Convert to a SparseArray.

as_evaluable_array(self)

return self

class nutils.evaluable.NPoints

Bases: nutils.evaluable.Array

The length of the points axis.

class nutils.evaluable.Normal(lgrad)

Bases: nutils.evaluable.Array

normal

class nutils.evaluable.Inverse(func)

Bases: nutils.evaluable.Array

Matrix inverse of func over the last two axes. All other axes are treated element-wise.

class nutils.evaluable.Interpolate(x, xp, fp, left=None, right=None)

Bases: nutils.evaluable.Array

interpolate uniformly spaced data; stepwise for now

class nutils.evaluable.Pointwise(*args)

Bases: nutils.evaluable.Array

Abstract base class for pointwise array functions.

classmethod outer(*args)

Alternative constructor that outer-aligns the arguments.

The output shape of this pointwise function is the sum of all shapes of its arguments. When called with multiple arguments, the first argument will be appended with singleton axes to match the output shape, the second argument will be prepended with as many singleton axes as the dimension of the original first argument and appended to match the output shape, and so forth and so on.

class nutils.evaluable.Cos(*args)

Bases: nutils.evaluable.Pointwise

Cosine, element-wise.

evalf = <ufunc 'cos'>

class nutils.evaluable.Sin(*args)

Bases: nutils.evaluable.Pointwise

Sine, element-wise.

evalf = <ufunc 'sin'>

class nutils.evaluable.Tan(*args)

Bases: nutils.evaluable.Pointwise

Tangent, element-wise.

evalf = <ufunc 'tan'>

class nutils.evaluable.ArcSin(*args)

Bases: nutils.evaluable.Pointwise

Inverse sine, element-wise.

evalf = <ufunc 'arcsin'>

class nutils.evaluable.ArcCos(*args)

Bases: nutils.evaluable.Pointwise

Inverse cosine, element-wise.

evalf = <ufunc 'arccos'>

class nutils.evaluable.ArcTan(*args)

Bases: nutils.evaluable.Pointwise

Inverse tangent, element-wise.

evalf = <ufunc 'arctan'>

class nutils.evaluable.Sampled(points, expect)

Bases: nutils.evaluable.Array

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.

class nutils.evaluable.Zeros(shape, dtype)

Bases: nutils.evaluable.Array

zero

class nutils.evaluable.Guard(fun)

Bases: nutils.evaluable.Array

bar all simplifications

class nutils.evaluable.TrigNormal(angle)

Bases: nutils.evaluable.Array

cos, sin

class nutils.evaluable.TrigTangent(angle)

Bases: nutils.evaluable.Array

-sin, cos

class nutils.evaluable.Find(where)

Bases: nutils.evaluable.Array

indices of boolean index vector

class nutils.evaluable.DerivativeTargetBase(args, shape, dtype)

Bases: nutils.evaluable.Array

base class for derivative targets

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

Bases: nutils.evaluable.DerivativeTargetBase

Array argument, to be substituted before evaluation.

The Argument is an Array with a known shape, but whose values are to be defined later, before evaluation, e.g. using replace_arguments().

It is possible to take the derivative of an Array to an Argument:

>>> from nutils import evaluable
>>> a = evaluable.Argument('x', [])
>>> b = evaluable.Argument('y', [])
>>> f = a**3 + b**2
>>> evaluable.derivative(f, a).simplified == (3*a**2).simplified
True

Parameters

• name (str) – The Identifier of this argument.

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

class nutils.evaluable.LocalCoords(ndims)

Bases: nutils.evaluable.DerivativeTargetBase

local coords derivative target

class nutils.evaluable.Polyval(coeffs, points, ngrad=0)

Bases: nutils.evaluable.Array

Computes the \(k\)-dimensional array

\[\begin{split}j_0,\dots,j_{k-1} \mapsto \sum_{\substack{i_0,\dots,i_{n-1}\in\mathbb{N}\\i_0+\cdots+i_{n-1}\le d}} p_0^{i_0} \cdots p_{n-1}^{i_{n-1}} c_{j_0,\dots,j_{k-1},i_0,\dots,i_{n-1}},\end{split}\]

where \(p\) are the \(n\)-dimensional local coordinates and \(c\) is the argument coeffs and \(d\) is the degree of the polynomial, where \(d\) is the length of the last \(n\) axes of coeffs.

Warning

All coefficients with a (combined) degree larger than \(d\) should be zero. Failing to do so won’t raise an Exception, but might give incorrect results.

class nutils.evaluable.RevolutionAngle

Bases: nutils.evaluable.Array

Pseudo coordinates of a nutils.topology.RevolutionTopology.

class nutils.evaluable.Choose(index, choices)

Bases: nutils.evaluable.Array

Function equivalent of numpy.choose().

nutils.evaluable.jacobian(geom, ndims)

Return \(\sqrt{|J^T J|}\) with \(J\) the gradient of geom to the local coordinate system with ndims dimensions (localgradient(geom, ndims)).

nutils.evaluable.derivative(func, var, seen=None)

nutils.evaluable.localgradient(arg, ndims)

local derivative

nutils.evaluable.prependaxes(func, shape)

Prepend axes with specified shape to func.

nutils.evaluable.appendaxes(func, shape)

Append axes with specified shape to func.

nutils.evaluable.replace_arguments(value, arguments)

Replace Argument objects in value.

Replace Argument objects in value according to the arguments map, taking into account derivatives to the local coordinates.

Parameters

• value (Array) – Array to be edited.

• arguments (collections.abc.Mapping with Arrays as values) – Arguments replacements. The key correspond to the name passed to an Argument and the value is the replacement.

Returns

The edited value.

Return type

Array