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

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(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 matching transforms, defining the order on which points show up in the evaluation. If absent the indices will be strict increasing.

__init__(self, transforms, points)
Parameters
abstract getindex(self, ielem)

Return the indices of Sample.points[ielem] in results of Sample.eval.

integrate(self, funcs, arguments=Ellipsis)

Integrate functions.

Parameters
integrate_sparse(self, funcs, arguments=None)

Integrate functions into sparse data.

Parameters
integral(self, func)

Create Integral object for postponed integration.

Parameters

func (nutils.function.Array) – Integrand.

eval(self, funcs, arguments=Ellipsis)

Evaluate function.

Parameters
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 a nutils.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.

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

class nutils.sample.Integral(integrands, shape)

Postponed integration.

The Integral class represents postponed integration. Integrals are internally represented as pairs of Sample and nutils.function.Array objects. Evaluation proceeds via either the 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.

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 the nutils.solver module which provides linear and non-linear solvers.

Parameters
• integrands (dict) – Dictionary representing a sum of integrals, where every key-value pair binds together the sample set and the integrand.

• shape (tuple) – Array dimensions of the integral.

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').

Parameters

target (str) – Name of the derivative target.

Returns

derivative

Return type

Integral

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 to self.replace(args).eval(...). Note, however, that after the replacement it is no longer possible to take derivatives against any of the targets in arguments.

Parameters

arguments (dict) – Arguments for function evaluation.

Returns

replaced

Return type

Integral

contains(self, name)

Test if target occurs in any of the integrands.

Parameters

name (str) – Target name.

Returns

iscontained

Return type

bool

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/or nutils.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/or nutils.matrix.Matrix objects.