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)

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)

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.

Parameters:

func (nutils.function.Array) – Integrand.

eval(self, funcs, /, **arguments)

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)

Evaluate function.

Parameters:
  • funcs (nutils.function.Array object or tuple 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 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
1.0
>>> zipped.integrate(function.J(geom2)) # wrong (expected 1)
1.4±1e-10
Parameters:

samples (Sample) – Samples that are to be zipped together.

Returns:

zipped

Return type:

Sample

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:
  • integrals (tuple of integrals) – Integrals to be evaluated.

  • arguments (dict (default: None)) – Optional arguments for function evaluation.

Returns:

results

Return type:

tuple of arrays and/or nutils.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:
  • integrals (tuple of integrals) – Integrals to be evaluated.

  • arguments (dict (default: None)) – Optional arguments for function evaluation.

Returns:

results

Return type:

tuple of arrays and/or nutils.matrix.Matrix objects.