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: 
references
¶ The references.
Type: nutils.elementseq.References

static
empty
(spaces, space_dims, ndims)¶ Return an empty topology.
Parameters: Returns: The empty topology.
Return type: 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 onedimensional 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 onedimensional 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: Returns: The slice.
Return type:

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
¶ elementwise 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=1e12, 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 ofint
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 likerefine_count()
. If the argument is a sequence ofstr
, then this method behaves likerefine_spaces()
. If the argument is a dictionary ofstr
andint
, then this method behaves likerefine_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
toint
) – 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 anutils.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=1e12) >>> 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
andeps
to set the tolerance in physical of element space, respectively; if both are specified the least restrictive takes precedence.Parameters:  geom (1dimensional
nutils.function.Array
) – Geometry function of lengthndims
.  coords (2dimensional
float
array) – Array of coordinates withndims
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 casecoords
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 aLocateError
.
Returns: located
Return type:  geom (1dimensional

boundary_spaces
(self, _Topology__spaces)¶ Return the boundary in the given spaces.
Parameters: spaces (iterable of str
) – Nonstrict subset ofspaces
. 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 ofspaces
.

boundary_spaces_unchecked
(self, _Topology__spaces)¶ Return the boundary in the given spaces.
The topology must be at least onedimensional.
Parameters: spaces ( frozenset
ofstr
) – Unempty, nonstrict subset ofspaces
.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 ofspaces
. 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 ofspaces
.

interfaces_spaces_unchecked
(self, _Topology__spaces)¶ Return the interfaces in the given spaces.
The topology must be at least onedimensional.
Parameters: spaces ( frozenset
ofstr
) – Unempty, nonstrict subset ofspaces
.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=1e15, **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 prefixh
(hstd
,hspline
) for a classical hierarchical basis and prefixth
(thstd
,thspline
) for a truncated hierarchical basis.  truncation_tolerance (
float
(default 1e15)) – In order to benefit from the extra sparsity resulting from truncation, vanishing polynomials need to be actively identified and removed from the basis. Thetrunctation_tolerance
offers control over this threshold.
Returns: basis
Return type:  name (


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. Ifpatchcontinuous`
is true the basis is $C^0$continuous at patch interfaces.

basis_patch
(self)¶ degree zero patchwise discontinuous basis

static