topology¶

The topology module defines the topology objects, notably the StructuredTopology. Maintaining strict separation of topological and geometrical information, the topology represents a set of elements and their interconnectivity, boundaries, refinements, subtopologies etc, but not their positioning in physical space. The dimension of the topology represents the dimension of its elements, not that of the the space they are embedded in.

The primary role of topologies is to form a domain for nutils.function objects, like the geometry function and function bases for analysis, as well as provide tools for their construction. It also offers methods for integration and sampling, thus providing a high level interface to operations otherwise written out in element loops. For lower level operations topologies can be used as nutils.element iterators.

class nutils.topology.Topology(spaces, space_dims, references)¶

Bases: object

topology base class

Parameters:	spaces (`tuple` of `str`) – The unique, ordered list of spaces on which this topology is defined. space_dims (`tuple` of `int`) – The dimension of each space in `spaces`. references (`nutils.elementseq.References`) – The references.

spaces¶

The unique, ordered list of spaces on which this topology is defined.

Type:	`tuple` of `str`

space_dims¶

The dimension of each space in spaces.

Type:	`tuple` of `int`

references¶

The references.

Type:	`nutils.elementseq.References`

ndims¶

The dimension of this topology.

Type:	`int`

static empty(spaces, space_dims, ndims)¶

Return an empty topology.

Parameters:	spaces (`tuple` of `str`) – The unique, ordered list of spaces on which the empty topology is defined. space_dims (`tuple` of `int`) – The dimension of each space in `spaces`. ndims (`int`) – The dimension of the empty topology.
Returns:	The empty topology.
Return type:	`Topology`

See also

empty_like(): create an empty topology with spaces and dimension copied from another topology

empty_like(self)¶

Return an empty topology with the same spaces and dimensions as this topology.

Returns:	The empty topology.
Return type:	`Topology`

See also

empty_like(): create an empty topology with custom spaces and dimension

disjoint_union(*topos)¶

Return the union of the given disjoint topologies.

Parameters:	*topos (`Topology`) – The disjoint parts.
Returns:	The union.
Return type:	`Topology`

__str__(self)¶: string representation

get_groups(self, *groups)¶

Return the union of the given groups.

Parameters:	*groups (`str`) – The identifiers of the groups.
Returns:	The union of the given groups.
Return type:	`Topology`

take(self, _Topology__indices)¶

Return the selected elements as a disconnected topology.

The indices refer to the raveled list of elements in this topology. The indices are treated as a set: duplicate indices are silently ignored and the returned elements have the same order as in this topology.

Parameters:	indices (integer `numpy.ndarray` or similar) – The one-dimensional array of element indices.
Returns:	The selected elements.
Return type:	`Topology`

See also

compress(): select elements using a mask

compress(self, _Topology__mask)¶

Return the selected elements as a disconnected topology.

The mask refers to the raveled list of elements in this topology.

Parameters:	mask (boolean `numpy.ndarray` or similar) – The one-dimensional array of elements to select.
Returns:	The selected elements.
Return type:	`Topology`

See also

take(): select elements by index

slice(self, _Topology__s, _Topology__idim)¶

Return a slice of the given dimension index.

Parameters:	s (`slice`) – The slice. idim (`int`) – The dimension index.
Returns:	The slice.
Return type:	`Topology`

f_index¶: The evaluable index of the element in this topology.

f_coords¶: The evaluable element local coordinates.

basis(self, name, *args, **kwargs)¶: Create a basis.

sample(self, ischeme, degree)¶: Create sample.

integrate_elementwise¶: element-wise integration

integrate¶: integrate functions

integral(self, func, ischeme='gauss', degree=None, edit=None)¶

projection(self, fun, onto, geometry, **kwargs)¶: project and return as function

project(self, fun, onto, geometry, ischeme='gauss', degree=None, droptol=1e-12, exact_boundaries=False, constrain=None, verify=None, ptype='lsqr', edit=None, *, arguments=None, **solverargs)¶: L2 projection of function onto function space

refined_by(self, refine)¶

Create hierarchically refined topology by selectively refining elements.

Parameters:	refine (`Topology` or iterable of `int` or transformation chains) – The elements to refine, specified either as a subtopology or by their indices or locations in the topology.
Returns:	The refined topology.
Return type:	`Topology`

refine(self, _Topology__arg)¶

Return the refined topology.

If the argument is an int, then this method behaves like refine_count(). If the argument is a sequence of str, then this method behaves like refine_spaces(). If the argument is a dictionary of str and int, then this method behaves like refine_spaces_count().

Returns:	The refined topology.
Return type:	`Topology`

See also

refine_count(): refine a topology the given amount times
refine_spaces(): refine the given spaces of the topology
refine_spaces_count(): refine the given spaces the given amount times

refine_count(self, count)¶

Return the topology refined count times.

Parameters:	count (`int`) – The number of times to refine. count is allowed to be zero, in which case the original topology is returned, but not negative.
Returns:	The refined topology.
Return type:	`Topology`

See also

refine_spaces(): refine the given spaces of the topology
refine_spaces_count(): refine the given spaces the given amount times

refine_spaces(self, _Topology__spaces)¶

Return the topology with the given spaces refined once.

Parameters:	spaces (iterable of `str`) – The spaces to refine. It is an error to specify spaces that do not exist in this topology. It is allowed to specify no spaces, in which case the original topology is returned.
Returns:	The refined topology.
Return type:	`Topology`

See also

refine_count(): refine a topology the given amount times
refine_spaces_count(): refine the given spaces the given amount times

refine_spaces_unchecked(self, _Topology__spaces)¶

Return the topology with the given spaces refined once.

Parameters:	spaces (iterable of `str`) – The spaces to refine. It is an error to specify spaces that do not exist in this topology. It is allowed to specify no spaces, in which case the original topology is returned.
Returns:	The refined topology.
Return type:	`Topology`

Notes

This method does not check the validity of the arguments. Use refine_spaces() instead unless you’re absolutely sure what you are doing.

refine_spaces_count(self, count)¶

Return the topology with the given spaces refined the given amount times.

Parameters:	spaces (mapping of `str` to `int`) – The spaces to refine together with the count. It is an error to specify spaces that do not exist in this topology. It is allowed to specify no spaces, in which case the original topology is returned.
Returns:	The refined topology.
Return type:	`Topology`

See also

refine_count(): refine a topology the given amount times
refine_spaces(): refine the given spaces of the topology

trim(self, levelset, maxrefine, ndivisions=8, name='trimmed', leveltopo=None, *, arguments=None)¶: trim element along levelset

subset(self, topo, newboundary=None, strict=False)¶: intersection

indicator(self, subtopo)¶: Create an indicator function for a subtopology.

locate(self, geom, coords, *, tol=0, eps=0, maxiter=0, arguments=None, weights=None, maxdist=None, ischeme=None, scale=None, skip_missing=False)¶

Create a sample based on physical coordinates.

In a finite element application, functions are commonly evaluated in points that are defined on the topology. The reverse, finding a point on the topology based on a function value, is often a nonlinear process and as such involves Newton iterations. The locate function facilitates this search process and produces a nutils.sample.Sample instance that can be used for the subsequent evaluation of any function in the given physical points.

Example:

>>> from . import mesh
>>> domain, geom = mesh.unitsquare(nelems=3, etype='mixed')
>>> sample = domain.locate(geom, [[.9, .4]], tol=1e-12)
>>> sample.eval(geom).round(5).tolist()
[[0.9, 0.4]]

Locate requires a geometry function, an array of coordinates, and at least one of tol and eps to set the tolerance in physical of element space, respectively; if both are specified the least restrictive takes precedence.

Parameters:	geom (1-dimensional `nutils.function.Array`) – Geometry function of length `ndims`. coords (2-dimensional `float` array) – Array of coordinates with `ndims` columns. tol (`float` (default: 0)) – Maximum allowed distance in physical coordinates between target and located point. eps (`float` (default: 0)) – Maximum allowed distance in element coordinates between target and located point. maxiter (`int` (default: 0)) – Maximum allowed number of Newton iterations, or 0 for unlimited. arguments (`dict` (default: None)) – Arguments for function evaluation. weights (`float` array (default: None)) – Optional weights, in case `coords` are quadrature points, making the resulting sample suitable for integration. maxdist (`float` (default: None)) – Speed up failure by setting a physical distance between point and element centroid above which the element is rejected immediately. If all points are expected to be located then this can safely be left unspecified. skip_missing (`bool` (default: False)) – When set to true, skip points that are not found (for instance because they fall outside the domain) in the returned sample. When set to false (the default) missing points raise a `LocateError`.
Returns:	located
Return type:	`nutils.sample.Sample`

boundary_spaces(self, _Topology__spaces)¶

Return the boundary in the given spaces.

Parameters:	spaces (iterable of `str`) – Nonstrict subset of `spaces`. Duplicates are silently ignored.
Returns:	The boundary in the given spaces.
Return type:	`Topology`
Raises:	`ValueError` – If the topology is 0D or the set of spaces is empty or not a subset of `spaces`.

boundary_spaces_unchecked(self, _Topology__spaces)¶

Return the boundary in the given spaces.

The topology must be at least one-dimensional.

Parameters:	spaces (`frozenset` of `str`) – Unempty, nonstrict subset of `spaces`.
Returns:	The boundary in the given spaces.
Return type:	`Topology`

Notes

This method does not check the validity of the arguments or the dimension of the topology. Use boundary_spaces() instead unless you’re absolutely sure what you are doing.

interfaces_spaces(self, _Topology__spaces)¶

Return the interfaces in the given spaces.

Parameters:	spaces (iterable of `str`) – Nonstrict subset of `spaces`. Duplicates are silently ignored.
Returns:	The interfaces in the given spaces.
Return type:	`Topology`
Raises:	`ValueError` – If the topology is 0D or the set of spaces is empty or not a subset of `spaces`.

interfaces_spaces_unchecked(self, _Topology__spaces)¶

Return the interfaces in the given spaces.

The topology must be at least one-dimensional.

Parameters:	spaces (`frozenset` of `str`) – Unempty, nonstrict subset of `spaces`.
Returns:	The interfaces in the given spaces.
Return type:	`Topology`

Notes

This method does not check the validity of the arguments or the dimension of the topology. Use interfaces_spaces() instead unless you’re absolutely sure what you are doing.

basis_discont(self, degree)¶: discontinuous shape functions

__weakref__¶: list of weak references to the object (if defined)

class nutils.topology.TransformChainsTopology(space, references, transforms, opposites)¶

Bases: nutils.topology.Topology

base class for topologies with transform chains

sample(self, ischeme, degree)¶: Create sample.

basis_lagrange(self, degree)¶: lagrange shape functions

basis_bernstein(self, degree)¶: bernstein shape functions

basis_std(self, degree)¶: bernstein shape functions

class nutils.topology.WithGroupsTopology(basetopo, vgroups={}, bgroups={}, igroups={}, pgroups={})¶

Bases: nutils.topology.TransformChainsTopology

item topology

class nutils.topology.OppositeTopology(basetopo)¶

Bases: nutils.topology.TransformChainsTopology

opposite topology

class nutils.topology.EmptyTopology(space, todims, fromdims)¶

Bases: nutils.topology.TransformChainsTopology

empty topology

class nutils.topology.StructuredTopology(space, root, axes, nrefine=0, bnames=(('left', 'right'), ('bottom', 'top'), ('front', 'back')))¶

Bases: nutils.topology.TransformChainsTopology

structured topology

basis_spline(self, degree, removedofs=None, knotvalues=None, knotmultiplicities=None, continuity=-1, periodic=None)¶: spline basis

__str__(self)¶: string representation

class nutils.topology.ConnectedTopology(space, references, transforms, opposites, connectivity)¶

Bases: nutils.topology.TransformChainsTopology

unstructured topology with connectivity

class nutils.topology.SimplexTopology(space, simplices, transforms, opposites)¶

Bases: nutils.topology.TransformChainsTopology

simpex topology

basis_bubble(self)¶: bubble from vertices

class nutils.topology.UnionTopology(topos, names=())¶

Bases: nutils.topology.TransformChainsTopology

grouped topology

class nutils.topology.DisjointUnionTopology(topos, names=())¶

Bases: nutils.topology.TransformChainsTopology

grouped topology

class nutils.topology.SubsetTopology(basetopo, refs, newboundary=None)¶

Bases: nutils.topology.TransformChainsTopology

trimmed

class nutils.topology.RefinedTopology(basetopo)¶

Bases: nutils.topology.TransformChainsTopology

refinement

class nutils.topology.HierarchicalTopology(basetopo, indices_per_level)¶

Bases: nutils.topology.TransformChainsTopology

collection of nested topology elments

basis(self, name, *args, truncation_tolerance=1e-15, **kwargs)¶

Create hierarchical basis.

A hierarchical basis is constructed from bases on different levels of uniform refinement. Two different types of hierarchical bases are supported:

1. Classical – Starting from the set of all basis functions originating from all levels of uniform refinement, only those basis functions are selected for which at least one supporting element is part of the hierarchical topology.

2. Truncated – Like classical, but with basis functions modified such that the area of support is reduced. An additional effect of this procedure is that it restores partition of unity. The spanned function space remains unchanged.

Truncation is based on linear combinations of basis functions, where fine level basis functions are used to reduce the support of coarser level basis functions. See Giannelli et al. 2012 for more information on truncated hierarchical refinement.

Parameters:	name (`str`) – Type of basis function as provided by the base topology, with prefix `h-` (`h-std`, `h-spline`) for a classical hierarchical basis and prefix `th-` (`th-std`, `th-spline`) for a truncated hierarchical basis. truncation_tolerance (`float` (default 1e-15)) – In order to benefit from the extra sparsity resulting from truncation, vanishing polynomials need to be actively identified and removed from the basis. The `trunctation_tolerance` offers control over this threshold.
Returns:	basis
Return type:	`nutils.function.Array`

class nutils.topology.PatchBoundary(id, dim, side, reverse, transpose)¶

Bases: object

__weakref__¶: list of weak references to the object (if defined)

class nutils.topology.Patch(topo, verts, boundaries)¶

Bases: object

__weakref__¶: list of weak references to the object (if defined)

class nutils.topology.MultipatchTopology(patches)¶

Bases: nutils.topology.TransformChainsTopology

multipatch topology

static build_boundarydata(connectivity)¶: build boundary data based on connectivity

basis_spline(self, degree, patchcontinuous=True, knotvalues=None, knotmultiplicities=None, *, continuity=-1)¶

spline from vertices

Create a spline basis with degree degree per patch. If patchcontinuous` is true the basis is $C^0$-continuous at patch interfaces.

basis_patch(self)¶: degree zero patchwise discontinuous basis