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.
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
-
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
andb
alongaxes
.
-
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.
-
sum
(arg, axis=None)¶ Sum array elements over a given axis.
-
dot
(a, b, axes)¶ Contract
a
andb
alongaxes
.
-
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.
-
classmethod
-
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.
-
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 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, a).simplified == (3*a**2).simplified True
-
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 ofcoeffs
.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 withndims
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.