sample¶
The sample module defines the Sample
class, which represents a
collection of discrete points on a topology and is typically formed via
nutils.topology.Topology.sample()
. Any function evaluation starts from
this sampling step, which drops element information and other topological
properties such as boundaries and groups, but retains point positions and
(optionally) integration weights. Evaluation is performed by subsequent calls
to Sample.integrate()
, Sample.integral()
or Sample.eval()
.
Besides the location of points, Sample
also keeps track of point
connectivity through its Sample.tri
and Sample.hull
properties, representing a (n-dimensional) triangulation of the interior and
boundary, respectively. Availability of these properties depends on the
selected sample points, and is typically used in combination with the “bezier”
set.
In addition to Sample
, the sample module defines the Integral
class which represents postponed integration. Integrals are internally
represented as pairs of Sample
and nutils.function.Array
objects. Evaluation proceeds via either the Integral.eval()
method, or
the eval_integrals()
function. The latter can also be used to evaluate
multiple integrals simultaneously, which has the advantage that it can
efficiently combine common substructures.
- class nutils.sample.Sample(transforms, points)¶
Bases:
nutils.types.Singleton
Collection of points on a topology.
The
Sample
class represents a collection of discrete points on a topology and is typically formed vianutils.topology.Topology.sample()
. Any function evaluation starts from this sampling step, which drops element information and other topological properties such as boundaries and groups, but retains point positions and (optionally) integration weights. Evaluation is performed by subsequent calls tointegrate()
,integral()
oreval()
.Besides the location of points,
Sample
also keeps track of point connectivity through itstri
andhull
properties, representing a (n-dimensional) triangulation of the interior and boundary, respectively. Availability of these properties depends on the selected sample points, and is typically used in combination with the “bezier” set.- static new(transforms, points, index=None)¶
Create a new
Sample
.- Parameters
transforms (
tuple
or transformation chains) – List of transformation chains leading to local coordinate systems that contain points.points (
PointsSequence
) – Points sequence.index (
tuple
of integer arrays, optional) – List of indices matchingtransforms
, defining the order on which points show up in the evaluation. If absent the indices will be strict increasing.
- __init__(self, transforms, points)¶
- Parameters
transforms (
tuple
or transformation chains) – List of transformation chains leading to local coordinate systems that contain points.points (
PointsSequence
) – Points sequence.
- abstract getindex(self, ielem)¶
Return the indices of Sample.points[ielem] in results of Sample.eval.
- integrate(self, funcs, arguments=Ellipsis)¶
Integrate functions.
- Parameters
funcs (
nutils.function.Array
object ortuple
thereof.) – The integrand(s).arguments (
dict
(default: None)) – Optional arguments for function evaluation.
- integrate_sparse(self, funcs, arguments=None)¶
Integrate functions into sparse data.
- Parameters
funcs (
nutils.function.Array
object ortuple
thereof.) – The integrand(s).arguments (
dict
(default: None)) – Optional arguments for function evaluation.
- integral(self, func)¶
Create Integral object for postponed integration.
- Parameters
func (
nutils.function.Array
) – Integrand.
- eval(self, funcs, arguments=Ellipsis)¶
Evaluate function.
- Parameters
funcs (
nutils.function.Array
object ortuple
thereof.) – The integrand(s).arguments (
dict
(default: None)) – Optional arguments for function evaluation.
- basis(self)¶
Basis-like function that for every point in the sample evaluates to the unit vector corresponding to its index.
- asfunction(self, array)¶
Convert sampled data to evaluable array.
Using the result of
Sample.eval()
, create anutils.function.Sampled
array that upon evaluation recovers the original function in the set of points matching the original sampling.>>> from nutils import mesh >>> domain, geom = mesh.rectilinear([1,2]) >>> gauss = domain.sample('gauss', 2) >>> data = gauss.eval(geom) >>> sampled = gauss.asfunction(data) >>> domain.integrate(sampled, degree=2) array([ 1., 2.])
- Parameters
array – The sampled data.
- property tri¶
Triangulation of interior.
A two-dimensional integer array with
ndims+1
columns, of which every row defines a simplex by mapping vertices into the list of points.
- property hull¶
Triangulation of the exterior hull.
A two-dimensional integer array with
ndims
columns, of which every row defines a simplex by mapping vertices into the list of points. Note that the hull often does contain internal element boundaries as the triangulations originating from separate elements are disconnected.
- subset(self, mask)¶
Reduce the number of points.
Simple selection mechanism that returns a reduced Sample based on a selection mask. Points that are marked True will still be part of the new subset; points marked False may be dropped but this is not guaranteed. The point order of the original Sample is preserved.
- class nutils.sample.Integral(integrands, shape)¶
Bases:
nutils.types.Singleton
Postponed integration.
The
Integral
class represents postponed integration. Integrals are internally represented as pairs ofSample
andnutils.function.Array
objects. Evaluation proceeds via either theeval()
method, or theeval_integrals()
function. The latter can also be used to evaluate multiple integrals simultaneously, which has the advantage that it can efficiently combine common substructures.Integrals support basic arithmetic such as summation, subtraction, and scalar multiplication and division. It also supports differentiation via the
derivative()
method. This makes Integral particularly well suited for use in combination with thenutils.solver
module which provides linear and non-linear solvers.- Parameters
- eval(self, **kwargs)¶
Evaluate integral.
Equivalent to
eval_integrals()
(self, …).
- derivative(self, target)¶
Differentiate integral.
Return an Integral in which all integrands are differentiated with respect to a target. This is typically used in combination with
nutils.function.Namespace
, in which targets are denoted with a question mark (e.g.'?dofs_n'
corresponds to target'dofs'
).
- replace(self, arguments)¶
Return copy with arguments applied.
Return a copy of self in which all all arguments are edited into the integrands. The effect is that
self.eval(..., arguments=args)
is equivalent toself.replace(args).eval(...)
. Note, however, that after the replacement it is no longer possible to take derivatives against any of the targets inarguments
.
- nutils.sample.eval_integrals(*integrals, **arguments)¶
Evaluate integrals.
Evaluate one or several postponed integrals. By evaluating them simultaneously, rather than using
Integral.eval()
on each integral individually, integrations will be grouped per Sample and jointly executed, potentially increasing efficiency.- Parameters
- Returns
results
- Return type
tuple
of arrays and/ornutils.matrix.Matrix
objects.
- nutils.sample.eval_integrals_sparse(*integrals, **arguments)¶
Evaluate integrals into sparse data.
Evaluate one or several postponed integrals. By evaluating them simultaneously, rather than using
Integral.eval()
on each integral individually, integrations will be grouped per Sample and jointly executed, potentially increasing efficiency.- Parameters
- Returns
results
- Return type
tuple
of arrays and/ornutils.matrix.Matrix
objects.