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: nutils.types.Singleton

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

property f_index: nutils.function.Array¶: The evaluable index of the element in this topology.

property f_coords: nutils.function.Array¶: The evaluable element local coordinates.

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

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

integrate_elementwise(self, funcs, *, degree, asfunction=False, ischeme='gauss', arguments=None)¶: element-wise integration

integrate(self, funcs, ischeme='gauss', degree=None, edit=None, *, arguments=None)¶: 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 refined space by refining dofs in existing one

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

property boundary: nutils.topology.Topology¶: Topology: The boundary of this topology.

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

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

__init__(self, space, root, axes, nrefine=0, bnames=(('left', 'right'), ('bottom', 'top'), ('front', 'back')))¶: constructor

boundary¶

interfaces¶

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

property refined¶: refine non-uniformly

__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

__init__(self, basetopo, indices_per_level)¶: constructor

boundary¶: boundary elements

interfaces¶

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.MultipatchTopology(patches)¶

Bases: nutils.topology.TransformChainsTopology

multipatch topology

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

__init__(self, patches)¶: constructor

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

boundary¶

interfaces¶: Return a topology with all element interfaces. The patch interfaces are accessible via the group 'interpatch' and the interfaces inside a patch via 'intrapatch'.

refined¶: refine