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