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.
- 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:
See also
empty_like()
create an empty topology with custom spaces and dimension
- disjoint_union(*topos)¶
Return the union of the given disjoint topologies.
- __str__(self)¶
string representation
- get_groups(self, *groups)¶
Return the union of the given groups.
- 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:
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:
See also
take()
select elements by index
- slice(self, _Topology__s, _Topology__idim)¶
Return a slice of the given dimension index.
- 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 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:
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:
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:
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:
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:
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=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
andeps
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 lengthndims
.coords (2-dimensional
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:
- 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:
- 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
ofstr
) – Unempty, nonstrict subset ofspaces
.- Returns:
The boundary in the given spaces.
- Return type:
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:
- 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
ofstr
) – Unempty, nonstrict subset ofspaces
.- Returns:
The interfaces in the given spaces.
- Return type:
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:
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:
TransformChainsTopology
item topology
- class nutils.topology.OppositeTopology(basetopo)¶
Bases:
TransformChainsTopology
opposite topology
- class nutils.topology.EmptyTopology(space, todims, fromdims)¶
Bases:
TransformChainsTopology
empty topology
- class nutils.topology.StructuredTopology(space, root, axes, nrefine=0, bnames=(('left', 'right'), ('bottom', 'top'), ('front', 'back')))¶
Bases:
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:
TransformChainsTopology
unstructured topology with connectivity
- class nutils.topology.SimplexTopology(space, simplices, transforms, opposites)¶
Bases:
TransformChainsTopology
simpex topology
- basis_bubble(self)¶
bubble from vertices
- class nutils.topology.UnionTopology(topos, names=())¶
Bases:
TransformChainsTopology
grouped topology
- class nutils.topology.DisjointUnionTopology(topos, names=())¶
Bases:
TransformChainsTopology
grouped topology
- class nutils.topology.SubsetTopology(basetopo, refs, newboundary=None)¶
Bases:
TransformChainsTopology
trimmed
- class nutils.topology.RefinedTopology(basetopo)¶
Bases:
TransformChainsTopology
refinement
- class nutils.topology.HierarchicalTopology(basetopo, indices_per_level)¶
Bases:
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 prefixh-
(h-std
,h-spline
) for a classical hierarchical basis and prefixth-
(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. Thetrunctation_tolerance
offers control over this threshold.
- Returns:
basis
- Return type:
- 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:
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