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 xydomain 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.
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, nonrecursive sweep.  lru (
int
) – Maximum size of the leastrecentlyused cache. A persistent weakkey 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:

class
nutils.evaluable.
Evaluable
(args)¶ Bases:
nutils.types.Singleton
Base class

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.
EvaluableConstant
(value)¶ Bases:
nutils.evaluable.Evaluable
Evaluate to the given constant value.
Parameters: value – The return value of eval
.

nutils.evaluable.
sum
(arg, axis=None)¶ Sum array elements over a given axis.

nutils.evaluable.
dot
(a, b, axes)¶ Contract
a
andb
alongaxes
.

nutils.evaluable.
align
(arg, where, shape)¶ Align array to target shape.
The align operation can be considered the opposite of transpose: instead of specifying for each axis of the return value the original position in the argument, align specifies for each axis of the argument the new position in the return value. In addition, the return value may be of higher dimension, with new axes being inserted according to the
shape
argument.Parameters: Returns: The aligned array.
Return type:

nutils.evaluable.
unalign
(*args, naxes=None)¶ Remove (joint) inserted axes.
Given one or more array arguments, return the shortest common axis vector along with function arguments such that the original arrays can be recovered by
align()
. Axes beyond the firstnaxes
are not considered for removal, keep their position (as seen from the right), and are not part of the common axis vector. Those axes should be added to the axis vector before callingalign()
.If
naxes
isNone
(the default), all arguments must have the same number of axes andnaxes
is set to this number.

class
nutils.evaluable.
AsEvaluableArray
¶ Bases:
object
Protocol for conversion into an
Array
.
as_evaluable_array
¶ 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.

sum
(arg, axis=None)¶ Sum array elements over a given axis.

dot
(a, b, axes)¶ Contract
a
andb
alongaxes
.

as_evaluable_array
¶ return self


class
nutils.evaluable.
NPoints
¶ Bases:
nutils.evaluable.Array
The length of the points axis.

class
nutils.evaluable.
Orthonormal
(basis, vector)¶ Bases:
nutils.evaluable.Array
make a vector orthonormal to a subspace

class
nutils.evaluable.
Inverse
(func)¶ Bases:
nutils.evaluable.Array
Matrix inverse of
func
over the last two axes. All other axes are treated elementwise.
static
evalf
(A)¶ Matrix inverse.
Fully equivalent to
numpy.linalg.inv()
, with the exception that upon singular systemsinv()
does not raise aLinAlgError
, but rather issues aRuntimeWarning
and returns NaN (not a number) values. For arguments of dimension >2 the return array contains NaN values only for those entries that correspond to singular matrices.

static

class
nutils.evaluable.
Pointwise
(*args, **params)¶ Bases:
nutils.evaluable.Array
Abstract base class for pointwise array functions.

classmethod
outer
(*args)¶ Alternative constructor that outeraligns 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.

classmethod

class
nutils.evaluable.
Cos
(*args, **params)¶ Bases:
nutils.evaluable.Pointwise
Cosine, elementwise.

evalf
= <ufunc 'cos'>¶


class
nutils.evaluable.
Sin
(*args, **params)¶ Bases:
nutils.evaluable.Pointwise
Sine, elementwise.

evalf
= <ufunc 'sin'>¶


class
nutils.evaluable.
Tan
(*args, **params)¶ Bases:
nutils.evaluable.Pointwise
Tangent, elementwise.

evalf
= <ufunc 'tan'>¶


class
nutils.evaluable.
ArcSin
(*args, **params)¶ Bases:
nutils.evaluable.Pointwise
Inverse sine, elementwise.

evalf
= <ufunc 'arcsin'>¶


class
nutils.evaluable.
ArcCos
(*args, **params)¶ Bases:
nutils.evaluable.Pointwise
Inverse cosine, elementwise.

evalf
= <ufunc 'arccos'>¶


class
nutils.evaluable.
ArcTan
(*args, **params)¶ Bases:
nutils.evaluable.Pointwise
Inverse tangent, elementwise.

evalf
= <ufunc 'arctan'>¶


class
nutils.evaluable.
CosH
(*args, **params)¶ Bases:
nutils.evaluable.Pointwise
Hyperbolic cosine, elementwise.

evalf
= <ufunc 'cosh'>¶


class
nutils.evaluable.
SinH
(*args, **params)¶ Bases:
nutils.evaluable.Pointwise
Hyperbolic sine, elementwise.

evalf
= <ufunc 'sinh'>¶


class
nutils.evaluable.
TanH
(*args, **params)¶ Bases:
nutils.evaluable.Pointwise
Hyperbolic tangent, elementwise.

evalf
= <ufunc 'tanh'>¶


class
nutils.evaluable.
ArcTanH
(*args, **params)¶ Bases:
nutils.evaluable.Pointwise
Inverse hyperbolic tangent, elementwise.

evalf
= <ufunc 'arctanh'>¶


class
nutils.evaluable.
Sampled
(points, target, interpolation)¶ Bases:
nutils.evaluable.Array
Basislike identity operator.
Basislike function that for every point evaluates to a partition of unity of a predefined set based on the selected interpolation scheme.
Parameters:

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.
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.
WithDerivative
(func, var, derivative)¶ Bases:
nutils.evaluable.Array
Wrap the given function and define the derivative to a target.
The wrapper is typically used together with a virtual derivative target like
IdentifierDerivativeTarget
. The wrapper is removed in the simplified form.Parameters:  func (
Array
) – The function to wrap.  var (
DerivativeTargetBase
) – The derivative target.  derivative (
Array
) – The derivative with shapefunc.shape + var.shape
.
See also
IdentifierDerivativeTarget
 a virtual derivative target
 func (

class
nutils.evaluable.
Argument
(name, shape, dtype=<class 'float'>)¶ Bases:
nutils.evaluable.DerivativeTargetBase
Array argument, to be substituted before evaluation.
The
Argument
is anArray
with a known shape, but whose values are to be defined later, before evaluation, e.g. usingreplace_arguments()
.It is possible to take the derivative of an
Array
to anArgument
:>>> from nutils import evaluable >>> a = evaluable.Argument('x', ()) >>> b = evaluable.Argument('y', ()) >>> f = a**3 + b**2 >>> evaluable.derivative(f, b).simplified == 2.*b True
Parameters:

class
nutils.evaluable.
IdentifierDerivativeTarget
(identifier, shape)¶ Bases:
nutils.evaluable.DerivativeTargetBase
Virtual derivative target distinguished by an identifier.
Parameters: See also
WithDerivative
Array
wrapper with additional derivative

class
nutils.evaluable.
Polyval
(coeffs, points)¶ Bases:
nutils.evaluable.Array
Evaluate a polynomial
The polynomials are of the form
\[Σ_{k ∈ ℤ^n  Σ_i k_i ≤ p} c_k ∏_i x_i^(k_i)\]where \(c\) is a vector of coefficients, \(x\) a vector of \(n\) variables and \(p\) a nonnegative integer degree. The coefficients are assumed to be in reverse [lexicographic order]: the coefficient for powers \(j ∈ ℤ^n\) comes before the coefficient for powers \(k ∈ ℤ^n / {j}\) iff \(j_i > k_i\), where \(i = max_l(j_l ≠ k_l)\), the index of the last nonmatching power.
Parameters: 
static
evalf
(coeffs, coords)¶ Evaluates all pairs of polynomials and values.
The degree of the polynomial and the number of variables are automatically determined from the lengths of the last axes of the arguments.
Parameters:  coeffs (
numpy.ndarray
) – The polynomial coefficients. The last axis constitutes the axis of coefficients.  values (
numpy.ndarray
) – The values for the variables of the coefficients. The last axis constitutes the axis of variables.
Returns: The evaluated polynomial. The leading axes of
values
come first, followed by the leading axes ofcoeffs
.Return type: See also
eval()
 Evaluates joined polynomials and values.
 coeffs (

static

class
nutils.evaluable.
PolyDegree
(ncoeffs, nvars)¶ Bases:
nutils.evaluable.Array
Returns the degree of a polynomial given the number of coefficients and number of variables
Parameters: Notes
See
Polyval
for a definition of the polynomial.

class
nutils.evaluable.
PolyNCoeffs
(nvars, degree)¶ Bases:
nutils.evaluable.Array
Returns the number of coefficients for a polynomial of given degree and number of variables
Parameters: Notes
See
Polyval
for a definition of the polynomial.

class
nutils.evaluable.
PolyMul
(coeffs_left, coeffs_right, vars)¶ Bases:
nutils.evaluable.Array
Compute the coefficients for the product of two polynomials
Return the coefficients such that calling
Polyval
on this result is equal to the product ofPolyval
called on the individual arrays of coefficients (with the appropriate selection of the variables as described by parametervars
).Parameters:  coeffs_left (
Array
) – The coefficients for the left operand. The last axis is treated as the coefficients axis.  coeffs_right (
Array
) – The coefficients for the right operand. The last axis is treated as the coefficients axis.  vars (
tuple
ofnutils_poly.MulVar
) – For each variable of this product,var
defines if the variable exists in the left polynomial, the right or both.
Notes
See
Polyval
for a definition of the polynomial. coeffs_left (

class
nutils.evaluable.
PolyGrad
(coeffs, nvars)¶ Bases:
nutils.evaluable.Array
Compute the coefficients for the gradient of a polynomial
The last two axes of this array are the axis of variables and the axis of coefficients.
Parameters: Notes
See
Polyval
for a definition of the polynomial.

class
nutils.evaluable.
Legendre
(x, degree)¶ Bases:
nutils.evaluable.Array
Series of Legendre polynomial up to and including the given degree.
Parameters:

class
nutils.evaluable.
Choose
(index, *choices)¶ Bases:
nutils.evaluable.Array
Function equivalent of
numpy.choose()
.

class
nutils.evaluable.
TransformCoords
(target, source, index, coords)¶ Bases:
nutils.evaluable.Array
Transform coordinates from one coordinate system to another (spatial part)
Parameters:  target (
nutils.transformseq.Transforms
, optional) – The target coordinate system. If None the target is root coordinate system.  source (
nutils.transformseq.Transforms
) – The source coordinate system.  index (scalar, integer
Array
) – The index part of the source coordinates.  coords (
Array
) – The spatial part of the source coordinates.
 target (

class
nutils.evaluable.
TransformIndex
(target, source, index)¶ Bases:
nutils.evaluable.Array
Transform coordinates from one coordinate system to another (index part)
Parameters:  target (
nutils.transformseq.Transforms
, optional) – The target coordinate system. If None the target is the root coordinate system.  source (
nutils.transformseq.Transforms
) – The source coordinate system.  index (scalar, integer
Array
) – The index part of the source coordinates.
 target (

class
nutils.evaluable.
TransformLinear
(target, source, index)¶ Bases:
nutils.evaluable.Array
Linear part of a coordinate transformation
Parameters:  target (
nutils.transformseq.Transforms
, optional) – The target coordinate system. If None the target is the root coordinate system.  source (
nutils.transformseq.Transforms
) – The source coordinate system.  index (scalar, integer
Array
) – The index part of the source coordinates.
 target (

class
nutils.evaluable.
TransformBasis
(source, index)¶ Bases:
nutils.evaluable.Array
Vector basis for the root and a source coordinate system
The columns of this matrix form a vector basis for the space of root coordinates. The first n vectors also span the space of source coordinates mapped to the root, where n is the dimension of the source coordinate system. The remainder is not a span of the complement space in general.
No additional properties are guaranteed beyond the above. In particular, if the source coordinate system has the same dimension as the root, the basis is not necessarily the same as
TransformLinear(None, source, index)
.Parameters:  source (
nutils.transformseq.Transforms
) – The source coordinate system.  index (scalar, integer
Array
) – The index part of the source coordinates.
 source (

class
nutils.evaluable.
SearchSorted
(arg, *, array, side, sorter)¶ Bases:
nutils.evaluable.Array
Find index of evaluable array into sorted numpy array.

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

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 invalue
.Replace
Argument
objects invalue
according to thearguments
map, taking into account derivatives to the local coordinates.Parameters:  value (
Array
) – Array to be edited.  arguments (
collections.abc.Mapping
withArray
s as values) –Argument
s replacements. The key correspond to thename
passed to anArgument
and the value is the replacement.
Returns: The edited
value
.Return type:  value (

nutils.evaluable.
einsum
(fmt, *args, **dims)¶ Multiply and/or contract arrays via format string.
The format string consists of a comma separated list of axis labels, followed by
>
and the axis labels of the return value. For example, the following swaps the axes of a matrix:>>> a45 = ones(tuple(map(constant, [4,5]))) # 4x5 matrix >>> einsum('ij>ji', a45) nutils.evaluable.Transpose<f:(5),(4)>
Axis labels that do not occur in the return value are summed. For example, the following performs a matrixvector product:
>>> a5 = ones(tuple(map(constant, [5]))) # vector with length 5 >>> einsum('ij,j>i', a45, a5) nutils.evaluable.Sum<f:4>
The following contracts a third order tensor, a matrix, and a vector, and transposes the result:
>>> a234 = ones(tuple(map(constant, [2,3,4]))) # 2x3x4 tensor >>> einsum('ijk,kl,l>ji', a234, a45, a5) nutils.evaluable.Sum<f:3,2>
In case the dimension of the input and output arrays may vary, a variable length axes group can be denoted by a capital. Its length is automatically established based on the dimension of the input arrays. The following example performs a tensor product of an array and a vector:
>>> einsum('A,i>Ai', a234, a5) nutils.evaluable.Multiply<f:2,3,4,5>
The format string may contain multiple variable length axes groups, but their lengths must be resolvable from left to right. In case this is not possible, lengths may be specified as keyword arguments.
>>> einsum('AjB,i>AijB', a234, a5, B=1) nutils.evaluable.Multiply<f:2,5,3,4>