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 (ndimensional) 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.

class
nutils.sample.
Sample
(spaces, ndims, nelems, npoints)¶ 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 (ndimensional) 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
(space, 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 (integer array or
tuple
of integer arrays, optional) – Indices defining the order in which points show up in the evaluation. If absent the indices will be strictly increasing.
 transforms (

__init__
(self, spaces, ndims, nelems, npoints)¶ Parameters:

getindex
(self, _Sample__ielem)¶ Return the indices of Sample.points[ielem] in results of Sample.eval.

get_evaluable_indices
(self, _Sample__ielem)¶ Return the evaluable indices for the given evaluable element index.
Parameters: ielem ( nutils.evaluable.Array
, ndim: 0, dtype:int
) – The element index.Returns: indices – The indices of the points belonging to the given element as a 1D array. Return type: nutils.evaluable.Array
See also
getindex()
 the nonevaluable equivalent

integrate
¶ Integrate functions.
Parameters:  funcs (
nutils.function.Array
object ortuple
thereof.) – The integrand(s).  arguments (
dict
(default: None)) – Optional arguments for function evaluation.
 funcs (

integrate_sparse
¶ 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.
 funcs (

integral
(self, _Sample__func)¶ Create Integral object for postponed integration.
Parameters: func ( nutils.function.Array
) – Integrand.

eval
¶ Evaluate function.
Parameters:  funcs (
nutils.function.Array
object ortuple
thereof.) – The integrand(s).  arguments (
dict
(default: None)) – Optional arguments for function evaluation.
 funcs (

eval_sparse
¶ Evaluate function.
Parameters:  funcs (
nutils.function.Array
object ortuple
thereof.) – The integrand(s).  arguments (
dict
(default: None)) – Optional arguments for function evaluation.
 funcs (

basis
(self, interpolation='none')¶ Basislike function that for every point in the sample evaluates to the unit vector corresponding to its index.
Parameters: interpolation ( str
) – Same as inasfunction()
.

asfunction
(self, array, interpolation='none')¶ Convert sampled data to evaluable array.
Using the result of
Sample.eval()
, create a 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.
 interpolation (
str
) – Interpolation scheme used to map sample values to the evaluating sample. Valid values are “none”, demanding that the evaluating sample mathes self, or “nearest” for nearestneighbour mapping.

tri
¶ Triangulation of interior.
A twodimensional integer array with
ndims+1
columns, of which every row defines a simplex by mapping vertices into the list of points.

hull
¶ Triangulation of the exterior hull.
A twodimensional 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, _Sample__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.
Parameters: mask ( bool
array.) – Boolean mask that selects all points that should remain. The resulting Sample may contain more points than this, but not less.Returns: subset Return type: Sample

zip
(*samples)¶ Join multiple samples, with identical point count but differing spaces, into a new sample with the same point count and the total of spaces. The result is a sample that is able to evaluate any function that is evaluable on at least one of the individual samples.
>>> from . import mesh >>> topo1, geom1 = mesh.line([0,.5,1], space='X') >>> topo2, geom2 = mesh.line([0,.2,1], space='Y') >>> sample1 = topo1.sample('uniform', 3) >>> sample2 = topo2.locate(geom2, sample1.eval(geom1), tol=1e10) >>> zipped = sample1.zip(sample2) >>> numpy.linalg.norm(zipped.eval(geom1  geom2)) 0.±1e10
Though zipping is almost entirely symmetric, the first argument has special status in case the zipped sample is used to form an integral, in which case the first sample provides the quadrature weights. This means that integrals involving any but the first sample’s geometry scale incorrectly.
>>> zipped.integrate(function.J(geom1)) # correct 1.0 >>> zipped.integrate(function.J(geom2)) # wrong (expected 1) 1.4±1e10
Parameters: samples ( Sample
) – Samples that are to be zipped together.Returns: zipped Return type: Sample

static

nutils.sample.
eval_integrals
¶ Deprecated since version 7.0: sample.eval_integrals is deprecated, use function.eval instead
Evaluate integrals.
Evaluate one or several postponed integrals. By evaluating them simultaneously, rather than using
nutils.function.Array.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
¶ Deprecated since version 7.0: sample.eval_integrals_sparse is deprecated, use function.eval_sparse instead
Evaluate integrals into sparse data.
Evaluate one or several postponed integrals. By evaluating them simultaneously, rather than using
nutils.function.Array.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.