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, index)

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

Parameters:
  • transforms (tuple or transformation chains) – List of transformation chains leading to local coordinate systems that contain points.
  • points (tuple of point sets) – List of point sets matching transforms.
  • index (tuple of integer arrays) – List of indices matching transforms, defining the order on which points show up in the evaluation.
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.
integral(self, 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.
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.
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.

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
__weakref__

list of weak references to the object (if defined)

class nutils.sample.Integral(integrands)

Bases: nutils.types.Singleton

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.
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:
  • 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.