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.
- class nutils.sample.Sample(spaces, ndims, nelems, npoints)¶
Bases:
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(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.
- __init__(self, spaces, ndims, nelems, npoints)¶
- 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:
See also
getindex()
the non-evaluable equivalent
- integrate(self, funcs, /, **arguments)¶
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)¶
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, _Sample__func)¶
Create Integral object for postponed integration.
- Parameters:
func (
nutils.function.Array
) – Integrand.
- eval(self, funcs, /, **arguments)¶
Evaluate function.
- Parameters:
funcs (
nutils.function.Array
object ortuple
thereof.) – The integrand(s).arguments (
dict
(default: None)) – Optional arguments for function evaluation.
- eval_sparse(self, funcs, /, **arguments)¶
Evaluate function.
- Parameters:
funcs (
nutils.function.Array
object ortuple
thereof.) – The integrand(s).arguments (
dict
(default: None)) – Optional arguments for function evaluation.
- basis(self, interpolation='none')¶
Basis-like 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 nearest-neighbour mapping.
- property tri: ndarray¶
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: ndarray¶
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, _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.
- 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=1e-10) >>> zipped = sample1.zip(sample2) >>> numpy.linalg.norm(zipped.eval(geom1 - geom2)) 0.±1e-10
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±1e-10
- nutils.sample.eval_integrals(*integrals, **arguments)¶
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(*integrals, **arguments)¶
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.