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 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 integrate(), integral() or eval().

Besides the location of points, Sample also keeps track of point connectivity through its tri and 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.

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)

Parameters:

spaces (tuple of str) – The names of the spaces on which this sample is defined.
ndims (int) – The dimension of the coordinates.
nelems (int) – The number of elements.
npoints (int) – The number of points.

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 non-evaluable equivalent

integrate(self, funcs, /, arguments=None, *, legacy=None, **kwargs)

Integrate functions.

Parameters:

funcs (nutils.function.Array object or tuple thereof.) – The integrand(s).
arguments (dict (default: None)) – Optional arguments for function evaluation.

integrate_sparse(self, funcs, /, arguments=None, **kwargs)

Integrate functions into sparse data.

Parameters:

funcs (nutils.function.Array object or tuple thereof.) – The integrand(s).
arguments (dict (default: None)) – Optional arguments for function evaluation.

integral(self, _Sample__func)

Create Integral object for postponed integration.

The following two expressions are equivalent: sample.integrate(f) and sample.integral(f).eval().

Parameters:: func (nutils.function.Array) – Integrand.

eval(self, funcs, /, arguments=None, **kwargs)

Evaluate function.

Parameters:

funcs (nutils.function.Array object or tuple thereof.) – The integrand(s).
arguments (dict (default: None)) – Optional arguments for function evaluation.

eval_sparse(self, funcs, arguments=None, /, **kwargs)

Evaluate function.

Parameters:

funcs (nutils.function.Array object or tuple thereof.) – The integrand(s).
arguments (dict (default: None)) – Optional arguments for function evaluation.

bind(self, func, /)

Bind sample to function array.

This method produces a function array that evaluates to the argument’s function values in all the sample points, adding a point dimension before the existing array dimensions. The following two expressions are equivalent: sample.eval(f) and sample.bind(f).eval().

Parameters:: func (nutils.function.Array) – Function to bind the the sample.

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 in asfunction().

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.

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=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
array(1.0)
>>> zipped.integrate(function.J(geom2)) # wrong (expected 1)
array(1.4)

Parameters:: samples (Sample) – Samples that are to be zipped together.
Returns:: zipped
Return type:: Sample

rename_spaces(self, map, /)

Return a Sample with spaces renamed according to map.

Parameters:: map (mapping of str to str) – A mapping of old space to new space.
Returns:: renamed
Return type:: Sample