Utilities#

sigmaepsilon.mesh.utils.space.frame_of_plane(coords: ndarray) → Tuple[ndarray, ndarray][source]#

Returns the frame of a planar surface. It needs at least 3 pointds to work properly (len(coords>=3)).

It takes the center, the first point and a point from the middle to form the coordinate axes.

Parameters:: coords (numpy.ndarray) – 2d coordinate array
Returns:: 3x3 global -> local DCM matrix
Return type:: numpy.ndarray

sigmaepsilon.mesh.utils.space.frames_of_lines(coords: ndarray, topo: ndarray, refZ: ndarray | None = None) → ndarray[source]#

Returns coordinate frames of line elements defined by a coordinate array and a topology array. The cross-sections of the line elements are in the local y-z plane. The direction of the local z axis can be set by providing reference points in the local x-z planes of the lines. If there are no references provided, local z axes lean towards global z. Other properties are determined in a way, so that x-y-z form a right-handed orthonormal basis.

Parameters:

coords (numpy.ndarray) – 2d coordinate array
topo (numpy.ndarray) – 2d point-based topology array
refZ (numpy.ndarray, Optional) – 1d or 2d float array of reference points. If it is 2d, it must contain values for all lines defined by topo. Default is None.

Returns:

3d array of 3x3 transformation matrices

Return type:

numpy.ndarray

sigmaepsilon.mesh.utils.space.frames_of_surfaces(coords: ndarray, topo: ndarray) → ndarray[source]#

Returns the coordinates of the axes forming the local coordinate systems of the surfaces using the first three vertices of the cells.

Note

This is only working for flat 2d cells.

Parameters:

coords (numpy.ndarray) – 2d coordinate array
topo (numpy.ndarray) – 2d point-based topology array

Returns:

3d array of 3x3 transformation matrices

Return type:

numpy.ndarray

sigmaepsilon.mesh.utils.space.index_of_closest_point(coords: ndarray, target: ndarray) → int[source]#

Returs the index of the point in ‘coords’, being closest to one or more targets.

Parameters:

coords (numpy.ndarray) – 2d float array of vertex coordinates.
target (numpy.ndarray) – 1d or 2d coordinate array of the target point(s).

Returns:

One or more indices of ‘coords’, for which the distance from one or more points described by ‘target’ is minimal.

Return type:

int or Iterable[int]

sigmaepsilon.mesh.utils.space.index_of_furthest_point(coords: ndarray, target: ndarray) → int[source]#

Returs the index of the point in ‘coords’, being furthest from one or more targets.

Parameters:

coords (numpy.ndarray) – 2d float array of vertex coordinates.
target (numpy.ndarray) – 1d or 2d coordinate array of the target point(s).

Returns:

One or more indices of ‘coords’, for which the distance from one or more points described by ‘target’ is maximal.

Return type:

int or Iterable[int]

sigmaepsilon.mesh.utils.space.is_line(coords: ndarray, tol=1e-08) → bool[source]#

Returns true if all the normals point in the same direction. The provided normal vectors are assumed to be normalized.

Parameters:

coords (numpy.ndarray) – 2d float array of point coordinates
tol (float) – Floating point tolerance as maximum deviation.

Returns:

True if all absolute deviations from the line between the first and the last point is smaller than ‘tol’.

Return type:

bool

sigmaepsilon.mesh.utils.space.is_planar(coords: ndarray, tol: float = 1e-08) → bool[source]#

Returns true if all the points fit on a planar surface.

Parameters:

coords (numpy.ndarray) – 2d float array of point coordinates
tol (float) – Floating point tolerance as maximum deviation.

Return type:

bool

sigmaepsilon.mesh.utils.space.is_planar_surface(normals: ndarray, tol: float = 1e-08) → bool[source]#

Returns true if all the normals point in the same direction. The provided normal vectors are assumed to be normalized.

Parameters:

normals (numpy.ndarray) – 2d float array of surface normals
tol (float) – Floating point tolerance as maximum deviation.

Returns:

True if the surfaces whose normal vectors are provided form a flat surface, False otherwise.

Return type:

bool

sigmaepsilon.mesh.utils.space.tr_cell_glob_to_loc_bulk(coords: ndarray, topo: ndarray) → Tuple[ndarray, ndarray, ndarray][source]#

Returns the coordinates of the cells in their local coordinate system, the coordinates of their centers and the coordinates of the axes forming their local coordinate system. The local coordinate systems are located at the centers of the cells.

Parameters:

coords (numpy.ndarray) – 2d coordinate array
topo (numpy.ndarray) – 2d point-based topology array

Returns:

numpy.ndarray – 2d coordinate array of local coordinates
numpy.ndarray – 2d array of cell centers
numpy.ndarray – 3d array of 3x3 transformation matrices

sigmaepsilon.mesh.utils.topology.topo.cells_at_nodes(topo: ndarray | Array | csr_matrix, *_, frmt: str | None = None, assume_regular: bool = False, cellIDs: Iterable | None = None, return_counts: bool = False, **__) → Any[source]#

Returns data about element connectivity at the nodes of a mesh.

Parameters:

topo (numpy.ndarray or sigmaepsilon.math.linalg.sparse.JaggedArray) – A 2d array (either jagged or not) representing topological data of a mesh.
frmt (str) – A string specifying the output format. Valid options are ‘jagged’, ‘csr’, ‘scipy-csr’ and ‘dicts’. See below for the details on the returned object.
return_counts (bool) – Wether to return the numbers of connecting elements at the nodes as a numpy array. If format is ‘raw’, the counts are always returned irrelevant to this option.
assume_regular (bool) – If the topology is regular, you can gain some speed with providing it as True. Default is False.
cellIDs (numpy.ndarray) – Indices of the cells in topo. If nor None, format must be ‘dicts’. Default is None.

Returns:

If return_counts is True, the number of connecting elements for
each node is returned as either a numpy array (if cellIDs is None)
or a dictionary (if cellIDs is not None). If format is ‘raw’, the
counts are always returned.
frmt = None –

countsnp.ndarray(nN) - numbers of connecting elements, only returned
if ‘return_counts’ is True

ereg : np.ndarray(nN, nmax) - indices of connecting elements

nregnp.ndarray(nN, nmax) - node indices with respect to the
connecting elements
where – nN - is the number of nodes,

nmax - is the maximum number of elements that meet at a node, that is
count.max()
frmt = ‘csr’ –

counts(optionally)np.ndarray(nN) - number of connecting elements, only returned
if ‘return_counts’ is True

csrcsr_matrix - sparse matrix in a numba-jittable csr format.
Column indices denote element indices, values have the meaning of element node locations.
frmt = ‘scipy-csr’ or ‘csr-scipy’ –

counts(optionally)np.ndarray(nN) - number of connecting elements, only returned
if ‘return_counts’ is True

csrcsr_matrix - An instance of scipy.linalg.sparse.csr_matrix.
Column indices denote element indices, values have the meaning of element node locations.
frmt = ‘dicts’ –

counts(optionally)np.ndarray(nN) - number of connecting elements, only returned
if ‘return_counts’ is True

eregnumba Dict(intint[:]) - indices of elements for each node
index

nregnumba Dict(intint[:]) - local indices of nodes in the
connecting elements
frmt = ‘jagged’ –

counts(optionally)np.ndarray(nN) - number of connecting elements, only returned
if ‘return_counts’ is True

ereg : JaggedArray - indices of elements for each node index

nreg : JaggedArray - local indices of nodes in the connecting elements

sigmaepsilon.mesh.utils.topology.topo.count_cells_at_nodes(topo: ndarray | Array | csr_matrix, regular: bool = False) → ndarray | dict[source]#

Returns an array or a dictionary, that counts connecting elements at the nodes of a mesh.

Parameters:

topo (TopoLike) – 2d numpy array describing the topoogy of a mesh.
regular (bool, Optional) – A True value means that ‘topo’ has tight and zeroed indexing. In this case, the output is a NumPy array. If False, the output a dictionary.

Returns:

count – Number of connecting elements for each node in a mesh.

Return type:

numpy.ndarray or dict

sigmaepsilon.mesh.utils.topology.topo.detach(coords: ndarray | PointCloud, topo: ndarray | Array | csr_matrix, inds: ndarray | None = None)[source]#

Given a topology array and the coordinate array it refers to, the function returns the coordinate array of the points involved in the topology, and a new topology array, with indices referencing the unique coordinate array.

Parameters:

coords (CoordsLike) – A 2d float array representing geometrical data of a mesh. If it is a PointCloud instance, indices may be included and parameter inds is obsolete.
topo (TopoLike) – A 2d integer array (either jagged or not) representing topological data of a mesh.
inds (ndarray, Optional) –
Global indices of the coordinates, in coords. If provided, the coordinates of node j of cell i is accessible as

coords[imap[topo[i, j]],

where imap is a mapping from local to global indices, and gets automatically generated from inds. Default is None.

Returns:

ndarray – NumPy array similar to coords, but possibly with less entries.
TopoLike – Integer array representing the topology, with a good cahnce of being jagged, depending on your input.

sigmaepsilon.mesh.utils.topology.topo.detach_mesh_bulk(coords: ndarray, topo: ndarray)[source]#: Given a topology array and the coordinate array it refers to, the function returns the coordinate array of the points involved in the topology, and a new topology array, with indices referencing the new coordinate array.

sigmaepsilon.mesh.utils.topology.topo.detach_mesh_data_bulk(coords: ndarray, topo: ndarray, data: ndarray)[source]#: Given a subset of the topology of a mesh, the function returns the coordinates and nodal data of the points involved in the topology, and a new topology array, with indices referencing the new coordinate array.

sigmaepsilon.mesh.utils.topology.topo.is_regular(topo: ndarray | Array | csr_matrix) → bool[source]#: Returns True if the topology is regular, in the meaning that the smallest node index is zero, and every integer is represented up to the maximum index.

sigmaepsilon.mesh.utils.topology.topo.nodal_adjacency(topo: ndarray | Array | csr_matrix, *_, frmt: str | None = None, assume_regular: bool = False, **__) → Any[source]#

Returns nodal adjacency information of a mesh.

Parameters:

topo (numpy.ndarray array or JaggedArray) – A 2d array (either jagged or not) representing topological data of a mesh.
frmt (str) – A string specifying the output format. Valid options are ‘jagged’, ‘csr’, ‘nx’ and ‘scipy-csr’. See below for the details on the returned object.
assume_regular (bool) – If the topology is regular, you can gain some speed with providing it as True. Default is False.

Notes

You need networkx to be installed for most of the functionality here.
A node is adjacent to itself.

Returns:

frmt = None – A dictionary of numpy arrays for each node.
frmt = ‘csr’ – csr_matrix - A sparse matrix in a numba-jittable csr format.
frmt = ‘scipy-csr’ – An instance of scipy.linalg.sparse.csr_matrix.
frmt = ‘nx’ – A networkx Graph.
frmt = ‘jagged’ – A JaggedArray instance.

sigmaepsilon.mesh.utils.topology.topo.regularize(topo: ndarray | Array | csr_matrix) → Tuple[ndarray | Array | csr_matrix, ndarray][source]#

Returns a regularized topology and the unique indices. The returned topology array contains indices of the unique array.

Parameters:: topo (numpy.array or awkward.Array) – A topology array.
Returns:: An array with a similar type as the input array.
Return type:: numpy.array or awkward.Array

sigmaepsilon.mesh.utils.topology.topo.remap_topo(topo: ndarray, imap) → ndarray[source]#: Returns a new topology array. The argument ‘imap’ may be a dictionary or an array, that contains new indices for the indices in the old topology array.

sigmaepsilon.mesh.utils.topology.topo.rewire(topo: ndarray | Array | csr_matrix, imap: ndarray | MutableMapping, invert: bool = False) → Iterable[source]#

Returns a new topology array. The argument ‘imap’ may be a dictionary or an array, that contains new indices for the indices in the old topology array.

Parameters:

topo (numpy.ndarray or sigmaepsilon.math.linalg.sparse.JaggedArray) – 1d or 2d integer array representing topological data of a mesh.
imap (MappingLike) – Inverse mapping on the index sets from global to local.
invert (bool, Optional) – If True the argument imap describes a local to global mapping and an inversion takes place. In this case, imap must be a numpy array. Default is False.

Returns:

The same topology with the new numbering.

Return type:

TopoLike

sigmaepsilon.mesh.utils.topology.topo.unique_topo_data(topo3d: ndarray | Array | csr_matrix) → Tuple[ndarray, ndarray][source]#

Returns information about unique topological elements of a mesh. It can be used to return unique lines of a 2d mesh, unique faces of a 3d mesh, etc.

Parameters:

topo (numpy.ndarray) – Hierarchical topology array. The array must be 3 dimensional containing node indices for every node as a subarray. For instance for a 2d cell, the node indices of the j-th edge of the i-th element read as topo[i, j]. In general, the first axis runs for the elements, the second axis runs for edges (2d) or faces (3d).

Returns:

numpy.ndarray – The sorted unique topolical entities as integer arrays of node indices.
numpy.ndarray – Indices of the unique array, that can be used to reconstruct topo. See the examples.

Examples

Find unique edges of a mesh of Q4 quadrilaterals

>>> from sigmaepsilon.mesh.grid import grid
>>> from sigmaepsilon.mesh.utils.topodata import edges_Q4

>>> coords, topo = grid(size=(1, 1), shape=(10, 10), eshape='Q4')

To get a 3d integer array listing all the edges of all quads:

>>> edges3d = edges_Q4(topo)

To find the unique edges of the mesh:

>>> edges, edgeIDs = unique_topo_data(edges3d)

Then, to reconstruct edges3d, do the following

>>> edges3d_ = np.zeros_like(edges3d)
>>> for i in range(edgeIDs.shape[0]):
>>>     for j in range(edgeIDs.shape[1]):
>>>         edges3d_[i, j, :] = edges[edgeIDs[i, j]]
>>> assert np.all(edges3d == edges3d_)
True

sigmaepsilon.mesh.utils.topology.tr.transform_topology(topo: ndarray, path: ndarray, data: ndarray | None = None, *_, MT: bool = True, max_workers: int = 4, **__) → ndarray | Tuple[ndarray][source]#

Transforms a mesh by canging the celltype, but keeping the topology of the overall configuration.

Parameters:

topo (numpy.ndarray) – The input topology.
path (numpy.ndarray) – The transformation path.
data (numpy.ndarray, Optional) – Data attached to the points or the cells. Default is None.
MT (bool, Optional) – If True, transformation is carried out using multiple threads. Default is True.
max_workers (int, Optional) – The maximum number of worker threads. Only relevant if MT is True. Default is 4.

Returns:

Topology, and optionally data as NumPy arrays.

Return type:

Union[numpy.ndarray, Tuple[numpy.ndarray]]

Example

For instance, this could be a way of producing a more coarse triangulation:

>>> from sigmaepsilon.mesh.utils.topology import transform_topology
>>> from sigmaepsilon.mesh.triang import triangulate
>>> from sigmaepsilon.mesh.grid import grid
>>> coords, topo, _ = triangulate(size=(Lx, Ly), shape=(nx, ny))
>>> nE1 = topo.shape[0]
>>> coords, topo = T3_to_T6(coords, topo)
>>> coords, topo = T6_to_T3(coords, topo)
>>> nE2 = topo.shape[0]
>>> nE1 * 4 == nE2
True

The functions T3_to_T6 and T6_to_T3 call transform_topology to do the transformations. The same with calling transform_topology directly could be like this:

>>> coords, topo, _ = triangulate(size=(Lx, Ly), shape=(nx, ny))
>>> nE1 = topo.shape[0]
>>> coords, topo = T3_to_T6(coords, topo)
>>> path = np.array(
...     [[0, 3, 5], [3, 1, 4], [5, 4, 2], [5, 3, 4]], dtype=int
...            )
>>> topo = transform_topology(topo, path)
>>> nE2 = topo.shape[0]
>>> nE1 * 4 == nE2
True

In both cases, the original triangulation is splitted to 4 subtriangles per each cell. Hence, transform_topology is more general, since you have more control over how you want to split the cells that make up the original mesh.

sigmaepsilon.mesh.utils.tri.area_tri(ecoords: ndarray) → ndarray[source]#

Returns the the signed area of a single 3-noded triangle.

Parameters:: ecoords (numpy.ndarray) – Element coordinates, see the example.

Notes

This function is numba-jittable in ‘nopython’ mode.

Returns:: Returns a positive number if the vertices are listed counterclockwise, negative if they are listed clockwise.
Return type:: float

sigmaepsilon.mesh.utils.tri.area_tri_bulk(ecoords: ndarray) → ndarray[source]#

Returns the signed area of several triangles.

Parameters:: ecoords (numpy.ndarray) – 3d float numpy array of element coordinates for multiple cells.

Notes

This function is numba-jittable in ‘nopython’ mode.

Returns:: 1d numpy float array
Return type:: numpy.ndarray

sigmaepsilon.mesh.utils.tri.areas_tri(ecoords: ndarray) → ndarray[source]#

Returns the total sum of signed areas of several triangles.

Parameters:: ecoords (numpy.ndarray) – 3d float numpy array of element coordinates for multiple cells.

Notes

This function is numba-jittable in ‘nopython’ mode.

Returns:: The sum of areas of all triangles.
Return type:: float

sigmaepsilon.mesh.utils.tri.glob_to_loc_tri(gcoord: ndarray, gcoords: ndarray, center: ndarray = None) → ndarray[source]#

Transformation from global to local coordinates within a triangle.

Notes

This function is numba-jittable in ‘nopython’ mode.

sigmaepsilon.mesh.utils.tri.glob_to_nat_tri(gcoord: ndarray, ecoords: ndarray) → ndarray[source]#

Transformation from global to natural coordinates within a triangle.

Notes

This function is numba-jittable in ‘nopython’ mode.

sigmaepsilon.mesh.utils.tri.inscribed_radii(ecoords: ndarray) → ndarray[source]#

Returns the radii of the inscribed circle of several triangles.

Parameters:: ecoords (numpy.ndarray) – 3d float numpy array of element coordinates for multiple cells.

Notes

This function is numba-jittable in ‘nopython’ mode.

Returns:: 1d numpy float array
Return type:: numpy.ndarray

sigmaepsilon.mesh.utils.tri.inscribed_radius(ecoords: ndarray) → ndarray[source]#

Returns the radius of the inscribed circle of a single triangle.

Parameters:: ecoords (numpy.ndarray) – 2d float numpy array of element coordinates.

Notes

If the sides have length a, b, c, we define the semiperimeter s to be half their sum, so s = (a+b+c)/2. Given this, the radius is given using the following:

r2 = (s - a)*(s - b)*(s - c) / s.

This function is numba-jittable in ‘nopython’ mode.

Return type:: float

sigmaepsilon.mesh.utils.tri.lcoords_tri(center: ndarray = None) → ndarray[source]#

Returns the local coordinates (r, s) of the vertices of a triangle.

By default, it is assumed that the origo of the (r, s) system is at the geometric center of the triangle, unless the coordinates of geometric center are provided with the argument ‘center’.

Example

>>> import numpy as np
>>> from sigmaepsilon.mesh.utils.tri import lcoords_tri
>>> lcoords = lcoords_tri(np.array([1/3, 1/3]))

sigmaepsilon.mesh.utils.tri.loc_to_glob_tri(lcoord: ndarray, gcoords: ndarray, center: ndarray = None) → ndarray[source]#

Transformation from local to global coordinates within a triangle.

Notes

This function is numba-jittable in ‘nopython’ mode.

sigmaepsilon.mesh.utils.tri.loc_to_nat_tri(lcoord: ndarray, center: ndarray = None) → ndarray[source]#

Transformation from local to natural coordinates within a triangle.

Notes

This function is numba-jittable in ‘nopython’ mode.

sigmaepsilon.mesh.utils.tri.nat_to_glob_tri(ncoord: ndarray, ecoords: ndarray) → ndarray[source]#

Transformation from natural to global coordinates within a triangle.

Notes

This function is numba-jittable in ‘nopython’ mode.

sigmaepsilon.mesh.utils.tri.nat_to_loc_tri(acoord: ndarray, lcoords: ndarray = None, center: ndarray = None) → ndarray[source]#

Transformation from natural to local coordinates within a triangle.

Parameters:

acoord (numpy.ndarray) – 1d NumPy array of area coordinates of a point.
lcoords (numpy.ndarray, Optional) – 2d NumPy array of parametric coordinates (r, s) of the master cell of a triangle.
center (numpy.ndarray) – The local coordinates (r, s) of the geometric center of the master triangle. If not provided it is assumed to be at (0, 0).

Notes

This function is numba-jittable in ‘nopython’ mode.

sigmaepsilon.mesh.utils.tri.ncenter_tri() → ndarray[source]#: Returns the area coordinates of the geometric center of the master triangle.

sigmaepsilon.mesh.utils.tri.shp_tri_loc(lcoord: ndarray, center: ndarray = None) → ndarray[source]#

Evaluates the shape functions at the parametric coordinates (r, s).

By default, it is assumed that the origo of the (r, s) system is at the geometric center of the triangle, unless the coordinates of geometric center are provided with the argument ‘center’.

Example

For a master triangle with centroid at the first vertex: >>> import numpy as np >>> from sigmaepsilon.mesh.utils.tri import shp_tri_loc >>> A1, A2, A3 = shp_tri_loc(np.array([0.0, 0.0]), np.array([1/3, 1/3]))

sigmaepsilon.mesh.utils.tet.glob_to_nat_tet(gcoord: ndarray, ecoords: ndarray) → ndarray[source]#

Transformation from global to natural coordinates within a tetrahedron.

Notes

This function is numba-jittable in ‘nopython’ mode.

sigmaepsilon.mesh.utils.tet.lcoords_tet(center: ndarray = None) → ndarray[source]#: Returns coordinates of the master element of a simplex in 3d.

sigmaepsilon.mesh.utils.tet.nat_to_loc_tet(acoord: ndarray, lcoords: ndarray = None, center: ndarray = None) → ndarray[source]#

Transformation from natural to local coordinates within a tetrahedra.

Parameters:

acoord (numpy.ndarray) – 1d NumPy array of natural coordinates of a point.
lcoords (numpy.ndarray, Optional) – 2d NumPy array of parametric coordinates (r, s, t) of the master cell of a tetrahedron.
center (numpy.ndarray) – The local coordinates (r, s, t) of the geometric center of the master tetrahedron. If not provided it is assumed to be at (0, 0, 0).

Notes

This function is numba-jittable in ‘nopython’ mode.

sigmaepsilon.mesh.utils.tet.vol_tet(ecoords: ndarray) → ndarray[source]#

Calculates volumes of several tetrahedra.

Parameters:: ecoords (numpy.ndarray) – A 3d float array of shape (nE, nNE, 3) of nodal coordinates for several elements. Here nE is the number of nodes and nNE is the number of nodes per element.
Returns:: 1d float array of volumes.
Return type:: numpy.ndarray

Note

This only returns exact results for linear cells. For nonlinear cells, use objects that calculate the volumes using numerical integration.

sigmaepsilon.mesh.utils.tet.vol_tet_bulk(ecoords: ndarray) → ndarray[source]#

Calculates volumes of several tetrahedra.

Parameters:: ecoords (numpy.ndarray) – A 3d float array of shape (nE, nNE, 3) of nodal coordinates for several elements. Here nE is the number of nodes and nNE is the number of nodes per element.
Returns:: 1d float array of volumes.
Return type:: numpy.ndarray

Note

This only returns exact results for linear cells. For nonlinear cells, use objects that calculate the volumes using numerical integration.

sigmaepsilon.mesh.utils.knn.k_nearest_neighbours(X: ndarray, Y: ndarray | None = None, *, backend: str = 'scipy', k: int = 1, workers: int = -1, tree_kwargs: dict | None = None, query_kwargs: dict | None = None, leaf_size: int = 30, return_distance: bool = False, max_distance: float | None = None)[source]#

Returns the k nearest neighbours (KNN) of a KDTree for a pointcloud using scipy or sklearn. The function acts as a uniform interface for similar functionality of scipy and sklearn. The most important parameters are highlighted, for the complete list of arguments, see the corresponding docs:

https://docs.scipy.org/doc/scipy/reference/generated/scipy.spatial.KDTree.html#scipy.spatial.KDTree

https://scikit-learn.org/stable/modules/generated/sklearn.neighbors.KDTree.html

To learn more about nearest neighbour searches in general:

https://scikit-learn.org/stable/modules/neighbors.html

Parameters:

X (numpy.ndarray) – An array of points to build the tree.
Y (numpy.ndarray, Optional) – An array of sampling points to query the tree. If None it is the same as the points used to build the tree. Default is None.
k (int or Sequence[int], Optional) – Either the number of nearest neighbors to return, or a list of the k-th nearest neighbors to return, starting from 1.
leaf_size (positive int, Optional) – The number of points at which the algorithm switches over to brute-force. Default is 10.
workers (int, Optional) – Only if backend is ‘scipy’. Number of workers to use for parallel processing. If -1 is given all CPU threads are used. Default: -1. New in ‘scipy’ version 1.6.0.
max_distance (float, Optional) – Return only neighbors within this distance. It can be a single value, or an array of values of shape matching the input, while a None value translates to an infinite upper bound. Default is None.
tree_kwargs (dict, Optional) – Extra keyword arguments passed to the KDTree creator of the selected backend. Default is None.

Returns:

d (float or array of floats) – The distances to the nearest neighbors. Only returned if return_distance==True.
i (integer or array of integers) – The index of each neighbor.

Raises:

ImportError – In the abscence of a usable backend.

Examples

>>> from sigmaepsilon.mesh.grid import Grid
>>> from sigmaepsilon.mesh import KNN
>>> size = 80, 60, 20
>>> shape = 10, 8, 4
>>> grid = Grid(size=size, shape=shape, eshape='H8')
>>> X = grid.centers()
>>> i = KNN(X, X, k=3, max_distance=10.0)

sigmaepsilon.mesh.utils.utils.cell_center(coords: ndarray) → ndarray[source]#

Returns the center of a single cell.

Parameters:: ecoords (numpy.ndarray) – 2d coordinate array of the element. The array has as many rows, as the number of nodes of the cell, and three columns.
Returns:: 1d coordinate array.
Return type:: numpy.ndarray

sigmaepsilon.mesh.utils.utils.cell_center_2d(ecoords: ndarray) → ndarray[source]#

Returns the center of a 2d cell.

Parameters:: ecoords (numpy.ndarray) – 2d coordinate array of the element. The array has as many rows, as the number of nodes of the cell, and two columns.
Returns:: 1d coordinate array.
Return type:: numpy.ndarray

sigmaepsilon.mesh.utils.utils.cell_centers_bulk(coords: ndarray, topo: ndarray) → ndarray[source]#

Returns coordinates of the centers of cells of the same kind.

Parameters:

coords (numpy.ndarray) – 2d coordinate array.
topo (numpy.ndarray) – 2d point-based topology array.

Returns:

2d coordinate array.

Return type:

numpy.ndarray

sigmaepsilon.mesh.utils.utils.cell_centers_bulk2(ecoords: ndarray) → ndarray[source]#

Returns coordinates of the centers of cells of the same kind.

Parameters:: ecoords (numpy.ndarray) – 3d coordinate array of element coordinates.
Returns:: 2d coordinate array.
Return type:: numpy.ndarray

sigmaepsilon.mesh.utils.utils.cell_coords(coords: ndarray, topo: ndarray) → ndarray[source]#

Returns coordinates of a single cell from a coordinate array and a topology array.

Parameters:

coords (numpy.ndarray) – 2d array of shape (nP, nD) of vertex coordinates. nP : number of points nD : number of dimensions of the model space
topo (numpy.ndarray) – 1d array of vertex indices of shape (nNE,). nNE : number of nodes per element

Returns:

2d NumPy array of (nNE, nD) of coordinates for all nodes of all cells according to the argument ‘topo’.

Return type:

numpy.ndarray

Notes

The array ‘coords’ must be fully populated up to the maximum index in ‘topo’. (len(coords) >= (topo.max() + 1))

sigmaepsilon.mesh.utils.utils.cells_around(*args, **kwargs) → JaggedArray | csr_matrix | dict[source]#: Alias for points_around().

sigmaepsilon.mesh.utils.utils.cells_coords(coords: ndarray, topo: ndarray) → ndarray[source]#

Returns coordinates of cells from a coordinate base array and a topology array.

Parameters:

coords (numpy.ndarray) – 2d float array of shape (nP, nD) of vertex coordinates. nP : number of points nD : number of dimensions of the model space
topo (numpy.ndarray) – A 2D array of shape (nE, nNE) of vertex indices. The i-th row contains the vertex indices of the i-th element. nE : number of elements nNE : number of nodes per element

Returns:

A 3d array of shape (nE, nNE, nD) that contains coordinates for all nodes of all cells according to the argument ‘topo’.

Return type:

numpy.ndarray

Notes

The array ‘coords’ must be fully populated up to the maximum index in ‘topo’. (len(coords) >= (topo.max() + 1))

sigmaepsilon.mesh.utils.utils.center_of_points(coords: ndarray) → ndarray[source]#

Returns the center of several points.

Parameters:: coords (numpy.ndarray) – A 2d coordinate array.

sigmaepsilon.mesh.utils.utils.centralize(coords: ndarray) → ndarray[source]#

Centralizes coordinates of a point cloud.

Parameters:: coords (numpy.ndarray) – A 2d coordinate array.

sigmaepsilon.mesh.utils.utils.collect_nodal_data(celldata: ndarray, topo: ndarray, cids: ndarray, ndf: csr_matrix, res: ndarray) → ndarray[source]#

Collects nodal data from data defined on nodes of cells.

Parameters:

celldata (numpy.ndarray) – Data defined on nodes of cells. It can be any array with at least 2 dimensions with a shape (nE, nNE, …), where nE and nNE are the number of cells and nodes per cell.
topo (numpy.ndarray) – A 2d integer array describing the topology of several cells of the same kind.
cids (numpy.ndarray) – A 1d integer array describing the indices of the cells.
ndf (csr_matrix) – Nodal distribution factors for each node of each cell in ‘topo’. This must contain values for all cells in a mesh, not just the ones for which cell data and topology is provided by ‘celldata’ and ‘topo’.
res (numpy.ndarray) – An array for the output. It must have a proper size, at lest up to the maximum node index in ‘topo’.

sigmaepsilon.mesh.utils.utils.decompose(ecoords: ndarray, topo: ndarray, coords_out: ndarray) → None[source]#: Performes the inverse operation to coordinate explosion. Example usage at AxisVM domains. Works for all kinds of arrays.

sigmaepsilon.mesh.utils.utils.distances_of_points(coords: ndarray) → ndarray[source]#

Calculates distances between a series of points.

Parameters:: coords (numpy.ndarray) – 2d float array of shape (N, …).
Returns:: 1d float array of shape (nP,).
Return type:: numpy.ndarray

sigmaepsilon.mesh.utils.utils.distribute_nodal_data_bulk(data: ndarray, topo: ndarray, ndf: ndarray) → ndarray[source]#

Distributes nodal data to the cells for the case when the topology of the mesh is dense. The parameter ‘ndf’ controls the behaviour of the distribution.

Parameters:

data (numpy.ndarray) – 2d array of shape (nP, nX), the data defined on points.
topo (numpy.ndarray) – 2d integer array of shape (nE, nNE), describing the topology.
ndf (numpy.ndarray) – 2d float array of shape (nE, nNE), describing the distribution of cells to the nodes.

Returns:

A 3d float array of shape (nE, nNE, nX).

Return type:

numpy.ndarray

sigmaepsilon.mesh.utils.utils.distribute_nodal_data_sparse(data: ndarray, topo: ndarray, cids: ndarray, ndf: csr_matrix) → ndarray[source]#

Distributes nodal data to the cells for the case when the topology of the mesh is sparse. The parameter ‘ndf’ controls the behaviour of the distribution.

Parameters:

data (numpy.ndarray) – 2d array of shape (nP, nX), the data defined on points.
topo (numpy.ndarray) – 2d integer array of shape (nE, nNE), describing the topology.
cids (numpy.ndarray) – A 1d integer array describing the indices of the cells.
ndf (csr_matrix) – 2d float array of shape (nE, nNE), describing the distribution of cells to all nodes in the mesh.

Returns:

A 3d float array of shape (nE, nNE, nX).

Return type:

numpy.ndarray

sigmaepsilon.mesh.utils.utils.explode_mesh_bulk(coords: ndarray, topo: ndarray) → Tuple[ndarray][source]#

Turns an implicit representation of a mesh into an explicit one.

Parameters:

coords (numpy.ndarray) – A 2d coordinate array.
topo (numpy.ndarray) – A 2d integer array describing the topology of several cells of the same kind.

Returns:

numpy.ndarray – A new coordinate array.
numpy.ndarray – A new topology array.

sigmaepsilon.mesh.utils.utils.explode_mesh_data_bulk(coords: ndarray, topo: ndarray, data: ndarray) → Tuple[ndarray][source]#

Turns an implicit representation of a mesh into an explicit one and also data defined on the nodes of the cells to an 1d data array defined on the points of the new mesh.

Parameters:

coords (numpy.ndarray) – A 2d coordinate array.
topo (numpy.ndarray) – A 2d integer array describing the topology of several cells of the same kind.
data (numpy.ndarray) – A 2d array describing data on all nodes of the cells.

Returns:

numpy.ndarray – A new coordinate array.
numpy.ndarray – A new topology array.
numpy.ndarray – A new 1d data array.

sigmaepsilon.mesh.utils.utils.global_shape_function_derivatives(dshp: ndarray, jac: ndarray) → ndarray[source]#

Calculates derivatives of shape functions wrt. the local axes of cells using derivatives along master axes evaulated at some points in the interval [-1, 1], and jacobian matrices of local-to-global mappings.

Parameters:

dshp (numpy.ndarray) – Derivatives of an nNE number of shape functions evaluated at an nP number of points as a float array of shape (nP, nNE, nD).
jac (numpy.ndarray) – Jacobian matrices, evaluated for a a nP number of points in nE number of cells and for nD spatial dimensions as a float array of shape (nE, nP, nD, nD).

Returns:

4d float array of shape (nE, nP, nNE, nD).

Return type:

numpy.ndarray

sigmaepsilon.mesh.utils.utils.homogenize_nodal_values(data: ndarray, measure: ndarray) → ndarray[source]#: Calculates constant values for cells from existing data defined for each node, according to some measure.

sigmaepsilon.mesh.utils.utils.is_ccw(points: Iterable) → bool[source]#: Returns True, if the polygon described by the points is counterclockwise, False if it is clockwise.

sigmaepsilon.mesh.utils.utils.is_cw(points: Iterable) → bool[source]#: Returns True, if the polygon described by the points is clockwise, False if it is counterclockwise.

sigmaepsilon.mesh.utils.utils.jacobian_det_bulk_1d(jac: ndarray) → ndarray[source]#

Calculates Jacobian determinants for 1d cells.

Parameters:: jac (numpy.ndarray) – 4d float array of shape (nE, nG, 1, 1) for an nE number of elements and nG number of evaluation points.
Returns:: A 2d array of shape (nE, nG) of jacobian determinants calculated for each element and evaluation points.
Return type:: numpy.ndarray

sigmaepsilon.mesh.utils.utils.jacobian_matrix_bulk(dshp: ndarray, ecoords: ndarray) → ndarray[source]#

Returns Jacobian matrices of local to global transformation for several cells and evaluation points.

Parameters:

dshp (numpy.ndarray) – A 3d numpy array of shape (nG, nNE, nD), where nG, nNE and nD are the number of integration points, nodes and spatial dimensions.
ecoords (numpy.ndarray) – A 3d numpy array of shape (nE, nNE, nD), where nE, nNE and nD are the number of elements, nodes and spatial dimensions.

Returns:

A 4d array of shape (nE, nP, nD, nD).

Return type:

numpy.ndarray

sigmaepsilon.mesh.utils.utils.jacobian_matrix_bulk_1d(dshp: ndarray, ecoords: ndarray) → ndarray[source]#

Returns the Jacobian matrix for multiple cells (nE), evaluated at multiple (nP) points.

Returns:: A 4d NumPy array of shape (nE, nP, 1, 1).
Return type:: numpy.ndarray

Notes

As long as the line is straight, it is a constant metric element, and ‘dshp’ is only required here to provide an output with a correct shape.

sigmaepsilon.mesh.utils.utils.jacobian_matrix_single(dshp: ndarray, ecoords: ndarray) → ndarray[source]#

Returns Jacobian matrix of local to global transformation for for one cell and multiple evaluation pointsd.

Parameters:

dshp (numpy.ndarray) – A 3d numpy array of shape (nP, nNE, nD), where nP, nNE and nD are the number of evaluation points, nodes and spatial dimensions.
ecoords (numpy.ndarray) – A 2d numpy array of shape (nNE, nD), where nNE and nD are the number of nodes and spatial dimensions.

Returns:

A 3d array of shape (nP, nD, nD).

Return type:

numpy.ndarray

sigmaepsilon.mesh.utils.utils.lengths_of_lines(coords: ndarray, topo: ndarray) → ndarray[source]#

Returns lengths of several lines, where the geometry is defined implicitly.

Parameters:

coords (numpy.ndarray) – A 2d coordinate array.
topo (numpy.ndarray) – A 2d topology array.

sigmaepsilon.mesh.utils.utils.lengths_of_lines2(ecoords: ndarray) → ndarray[source]#

Returns lengths of several lines, where line cooridnates are specified explicitly.

Parameters:: ecoords (numpy.ndarray) – A 3d numpy array of shape (nE, nNE, nD), where nE, nNE and nD are the number of elements, nodes and spatial dimensions.

sigmaepsilon.mesh.utils.utils.nodal_distribution_factors(topo: csr_matrix | ndarray, weights: ndarray) → csr_matrix | ndarray[source]#

The j-th factor of the i-th row is the contribution of element i to the j-th node. Assumes zeroed and tight indexing.

Parameters:

topo (numpy.ndarray or csr_matrix) – 2d integer topology array.
w (numpy.ndarray) – The weights of the cells.

Returns:

A 2d matrix with a matching shape to ‘topo’.

Return type:

numpy.ndarray or csr_matrix