Mondaic
This API reference is not for the latest stable Salvus version.

salvus.mesh.data_structures.unstructured_mesh.unstructured_mesh

The unstructured mesh class for higher order quadrilateral and hexahedral meshes.

Classes

UnstructuredMesh

class UnstructuredMesh(builtins.object):
    def __init__(
        self,
        points: npt.NDArray,
        connectivity: npt.NDArray,
        scale: float = 1.0,
        global_variables: dict = default,
        global_strings: dict = default,
        global_arrays: dict = default,
        elemental_fields: dict[str, npt.NDArray] = default,
        nodal_fields: dict[str, npt.NDArray] = default,
        side_sets: dict[str, typing.Tuple[npt.NDArray, npt.NDArray]] = default,
        deformations: dict[str, npt.NDArray] = default,
    ) -> None: ...

Salvus’ representation of higher-order unstructured meshes.

Parameters
  • points npt.NDArray — Nodes of the mesh, array with shape (number of points, number of dimensions)
  • connectivity npt.NDArray — Connectivity of the mesh defining the elements in the mesh listing all nodes in tensorized order. Must have shape (number of elements, (shape order + 1) ** (number of dimensions)).
  • scale float — A scaling of the mesh that is only applied to the points array upon writing to file.
  • global_variables dict — Global variables stored in the mesh.
  • global_strings dict — Global strings stored in the mesh.
  • global_arrays dict — Global arrays stored in the mesh.
  • elemental_fields dict[str, npt.NDArray] — Fields defined on the mesh.
  • nodal_fields dict[str, npt.NDArray] — Nodal fields.
  • side_sets dict[str, typing.Tuple[npt.NDArray, npt.NDArray]] — The side sets.
  • deformations dict[str, npt.NDArray] — Collects so far unapplied deformations.
Attributes
coordinate_system CoordinateSystem

The coordinate system of the mesh.

edges_per_element int

The number of edge for one element of the mesh.

We only support quads and hexes currently so it will be either 4 or 12.

element_nodal_fields typing.Dict[str, npt.NDArray]

Element nodal fields.

element_nodes_shape typing.Tuple[int, ...]

Return the shape of the element nodes array.

Useful for initializing element nodal fields.

Returns: The shape of the element nodes.

elemental_scalar_fields typing.Dict[str, npt.NDArray]

Element scalar fields.

first_order_connectivity npt.NDArray

First order connectivity constructed from the corner points in case the shape mapping order is larger than 1.

max_dist_abc float

Maximum distance of the absorbing damping layer from the edge of the domain.

ndim int

The dimensionality of the mesh.

nelem int

Total number of spectral elements in the unstructured mesh.

nodes_per_element int

The number of nodes for one element of the mesh.

Will be 4 for first-order 2-D meshes, 9 for second-order 2-D meshes, 8 for first-order 3-D meshes, 125 for fourth-order 3-D meshes and so on.

npoint int

Total number of nodes in the unstructured mesh.

number_of_elemental_fields int

The total number of elemental fields in the mesh.

number_of_elements int

Total number of spectral elements in the unstructured mesh.

number_of_global_arrays int

The total number of global arrays in the mesh.

number_of_global_strings int

The total number of global strings in the mesh.

number_of_global_variables int

The total number of global variables in the mesh.

number_of_nodal_fields int

The total number of nodal fields in the mesh.

number_of_nodes int

Total number of nodes in the unstructured mesh.

number_of_side_sets int

The total number of side sets in the mesh.

shape_order int

Shape mapping order, i.e. the number of points in each direction in the tensorized elements - 1.

Methods
from_exodus()
def from_exodus(
    filename: str | pathlib.Path,
    attach_element_block_indices: bool = False,
    select_element_block_indices: typing.Sequence[int] | None = None,
) -> UnstructuredMesh: ...

Read unstructured mesh from exodus file.

Only supports first order quads or hexes.

Parameters
  • filename str | pathlib.Path — File to open.
  • attach_element_block_indices bool — If True, attach the element block indices to the mesh.
  • select_element_block_indices typing.Sequence[int] | None — If given, read only these element blocks. Keep in mind that exodus uses 1-based indexing.
Returns UnstructuredMesh
from_h5()
def from_h5(
    filename: str | pathlib.Path, read_data: bool = True
) -> UnstructuredMesh: ...

Read an unstructured mesh from an HDF5 Salvus mesh file.

Parameters
  • filename str | pathlib.Path — File to open.
  • read_data bool — read the elemental and element nodal data
Returns UnstructuredMesh
add_dem_2D()
def add_dem_2D(
    mesh: UnstructuredMesh,
    x: npt.NDArray,
    deformation: npt.NDArray,
    vertical_begin_deformation: float = 0.0,
    vertical_end_deformation: float = inf,
    vertical_reference: typing.Optional[float] = None,
    name: typing.Optional[str] = None,
    mode: DeformationMode2D | str = DeformationMode2D.cartesian,
) -> None: ...

Queue a 2D deformation for later application.

Please see the compute_deformation_2D function for more information.

Parameters
  • mesh UnstructuredMesh — The mesh to queue for.
  • x npt.NDArray — horizontal coordinates of the deformation. Angle in radians for spherical models.
  • deformation npt.NDArray — The deformation sampled at coordinates x.
  • vertical_begin_deformation float — Don’t deform any points with a vertical coordinate smaller than this.
  • vertical_end_deformation float — Don’t deform any points with a vertical coordinate larger than this.
  • vertical_reference typing.Optional[float] — Vertical coordinate, at which the deformation should be applied, e.g. y-coordinate of the surface for surface deformation. Defaults to the max y coordinate / radius in case at least one of y0, y1 are finite.
  • name typing.Optional[str] — Optionally pass a name for the deformation.
  • mode DeformationMode2D | str — The deformation mode.
Returns None
add_dem_3D()
def add_dem_3D(
    mesh: UnstructuredMesh,
    x: npt.NDArray,
    y: npt.NDArray,
    deformation: npt.NDArray,
    vertical_begin_deformation: float = 0.0,
    vertical_end_deformation: float = inf,
    vertical_reference: typing.Optional[float] = None,
    interpolation_order: int = 3,
    mode: DeformationMode3D | str = DeformationMode3D.cartesian,
    name: typing.Optional[str] = None,
) -> None: ...

Queue a 3D deformation for later application.

Please see the compute_deformation_3D function for more information.

Parameters
  • mesh UnstructuredMesh — The mesh to queue for.
  • x npt.NDArray — first horizontal coordinate of the deformation. Angle in radians for spherical models.
  • y npt.NDArray — second horizontal coordinate of the deformation. Angle in radians for spherical models.
  • deformation npt.NDArray — The deformation sampled at coordinates x.
  • vertical_begin_deformation float — Don’t deform any points with a vertical coordinate smaller than this.
  • vertical_end_deformation float — Don’t deform any points with a vertical coordinate larger than this.
  • vertical_reference typing.Optional[float] — Vertical coordinate, at which the deformation should be applied, e.g. y-coordinate of the surface for surface deformation. Defaults to the max y coordinate / radius in case at least one of y0, y1 are finite.
  • interpolation_order int — Horizontal interpolation order.
  • mode DeformationMode3D | str — The deformation mode.
  • name typing.Optional[str] — Optionally pass a name for the deformation.
Returns None
add_dem_cylindrical()
def add_dem_cylindrical(
    mesh: UnstructuredMesh,
    phi: npt.NDArray,
    z: npt.NDArray,
    dem: npt.NDArray,
    r0: float = 0.0,
    r1: float = inf,
    rref: typing.Optional[float] = None,
    name: typing.Optional[str] = None,
) -> None: ...

Queue cylindrical deformations for later application.

Add deformation for cylindrical meshes where the axis of the cylinder is aligned with the z component. The DEM radially stretches the domain in the region of (x,y)-radii in [r0, r1] - points below r0 are kept fixed, points above r1 are moved as the DEM, points in between are interpolated and the full DEM is applied to points at rref.

Usage: first call add_dem_cylindrical for each boundary that is to be perturbed and finally call apply_dem to add the perturbation to the mesh coordinates.

Parameters
  • mesh UnstructuredMesh — The mesh.
  • phi npt.NDArray — Angle in the x-y-plane of the DEM in radians.
  • z npt.NDArray — z-coordinates of the DEM.
  • dem npt.NDArray — the DEM sampled at the coordinates (phi,z)
  • r0 float — radius in x-y-plane at which the stretching begins
  • r1 float — radius in x-y-plane at which the stretching ends, can be infinity
  • rref typing.Optional[float] — radius in x-y-plane at which the deformation should be applied
  • name typing.Optional[str] — name of this deformation to refer to it in UnstructuredMesh.apply_dem()
Returns None
apply_deformations()
def apply_deformations(
    mesh: UnstructuredMesh, names: typing.Optional[typing.List[str]] = None
) -> None: ...

Apply the previously added deformations.

Parameters
  • mesh UnstructuredMesh — The mesh.
  • names typing.Optional[typing.List[str]] — Names of the deformations to apply. Defaults to all added ones.
Returns None
apply_dem()
def apply_dem(
    mesh: UnstructuredMesh, names: typing.Optional[typing.List[str]] = None
) -> None: ...

Apply the previously added deformations.

Parameters
  • mesh UnstructuredMesh — The mesh.
  • names typing.Optional[typing.List[str]] — Names of the deformations to apply. Defaults to all added ones.
Returns None
apply_element_mask()
def apply_element_mask(
    mesh: UnstructuredMesh,
    mask: npt.NDArray,
    return_node_map: bool = False,
    side_sets: typing.Optional[typing.Union[str, typing.List[str]]] = None,
) -> typing.Union[
    UnstructuredMesh, typing.Tuple[UnstructuredMesh, npt.NDArray]
]: ...

Apply an element mask to the mesh returning a new mesh object.

Only retains elements that are set to True in the mask.

Parameters
  • mesh UnstructuredMesh — The mesh.
  • mask npt.NDArray — The mask as boolean array.
  • return_node_map bool — Return a node map together with the new mesh object, to be used to map nodal fields to the set of nodes that are retained in the mesh.
  • side_sets typing.Optional[typing.Union[str, typing.List[str]]] — list of side set names to which the mask should be directly connected. All elements not connected to the side sets are retained. Can be used to avoid cavities in the mask.
Returns typing.Union[UnstructuredMesh, typing.Tuple[UnstructuredMesh, npt.NDArray]]
apply_scale()
def apply_scale(mesh: UnstructuredMesh) -> None: ...

Apply the scaling factor to the mesh.

Parameters
  • mesh UnstructuredMesh — The mesh.
Returns None
attach_elemental_field()
def attach_elemental_field(self, name: str, value: npt.NDArray) -> None: ...

Attach an elemental field to the mesh.

Parameters
  • name str — The name of the elemental field.
  • value npt.NDArray — The data array to store.
Returns None
attach_field()
def attach_field(self, name: str, data: npt.NDArray) -> None: ...

Attach a field to the mesh.

The shape of the data determines

Parameters
  • name str — name of the field
  • data npt.NDArray — data to store. 1D numpy array, with size of either nelem or npoint.
Returns None
attach_global_variable()
def attach_global_variable(
    self, name: str, data: typing.Union[float, str, npt.NDArray]
) -> None: ...

Add a global variable to the mesh.

Depending on the type of data it will go to different containers.

Parameters
  • name str — The key to store.
  • data typing.Union[float, str, npt.NDArray] — The value to store.
Returns None
attach_nodal_field()
def attach_nodal_field(self, name: str, value: npt.NDArray) -> None: ...

Attach a nodal field to the mesh.

Parameters
  • name str — The name of the nodal field.
  • value npt.NDArray — The data array to store.
Returns None
change_tensor_order()
def change_tensor_order(
    mesh: UnstructuredMesh,
    tensor_order: typing.Optional[salvus._core.types.int_] = None,
    interpolation_mode: InterpolationMode | str = InterpolationMode.linear,
    interpolation_kwargs: typing.Optional[typing.Dict] = None,
    make_unique_points: bool = True,
    tensor_node_locations: typing.Optional[npt.NDArray] = None,
) -> None: ...

Change the tensor order of a mesh’s elements

Usually going from linear to higher order elements.

Please be aware that this will delete any potentially set element nodal fields and nodal fields. Elemental fields and side sets will be retained.

New grid points are created by interpolating the existing corner points. This function supports a variety of interpolation modes (some of which require extra kwargs to set as part of the interpolation_kwargs dictionary):

  • "linear": The default. Perform a bi/trilinear interpolation. No extra keyword arguments are supported or required for this mode.
  • "spherical": Linearly interpolate in radial direction, and apply spherical linear interpolation (slerp) laterally. The center of the sphere is always considered to be at the origin of the coordinate system. Supported additional keywords:
  • "r1_spherical": Apply slerp only for radii >= r1_spherical, default: 0.0.
  • "r0_spherical": Apply bi/trilinear interpolation for radii < r0_spherical, default: 0.0.

If r1_spherical > r0_spherical intermediate radii will linearly interpolate between both modes.

  • "cylindrical": Linearly interpolate radially and along the last dimension. Slerp in the middle dimension. Only defined in 3D, for 2D point symmetry use "spherical". Supported additional keywords:
  • "r1_cylindrical": Apply slerp only for radii >= r1_cylindrical, default: 0.0.
  • "r0_cylindrical": Apply bi/trilinear interpolation for radii < r0_cylindrical, default: 0.0.

If r1_cylindrical > r0_cylindrical intermediate radii will linearly interpolate between both modes.

  • "SmoothieSEM": Special interpolation mode for spherical SmoothieSEM mesh that preserves the cylindrical “inner core”. Supported additional keywords: "r0_spherical", "r1_spherical", "r0_cylindrical", and "r1_cylindrical" with the same meaning as for the other interpolation modes.
Parameters
  • mesh UnstructuredMesh — The mesh whose tensor order to change.
  • tensor_order typing.Optional[salvus._core.types.int_] — Desired new tensor order of the elements.
  • interpolation_mode InterpolationMode | str — How to interpolate the location of the new grid points. See above description.
  • interpolation_kwargs typing.Optional[typing.Dict] — Extra keyword arguments for the chosen interpolation mode. See above description.
  • make_unique_points bool — Remove duplicate points. Make sure to have a reason if you set this to False.
  • tensor_node_locations typing.Optional[npt.NDArray] — Locations of the tensor nodes. Defaults to the GLL locations of the chosen tensor order. In almost all cases you will not have to change this.
Returns None
clear()
def clear(self) -> None: ...

“Clear” the mesh.

This will remove everything that is not related to the geometry, e.g. only the points, connectivity and scale will be kept.

Returns None
compute_dt()
def compute_dt(
    mesh: UnstructuredMesh,
    max_velocity: typing.Union[npt.NDArray, float],
    courant_number: float = 1.0,
    min_gll_point_distance: float = 1.0,
    fast: bool = True,
    return_hmin_elemnodes: bool = False,
) -> typing.Union[
    typing.Tuple[float, npt.NDArray],
    typing.Tuple[float, npt.NDArray, npt.NDArray],
]: ...

Compute an estimation of the time step set by each element.

Parameters
  • mesh UnstructuredMesh — The mesh to compute it for.
  • max_velocity typing.Union[npt.NDArray, float] — Fastest velocity in each element.
  • courant_number float — Courant number
  • min_gll_point_distance float — min_gll_point_distance
  • fast bool — fast
  • return_hmin_elemnodes bool — return_hmin_elemnodes
Returns typing.Union[typing.Tuple[float, npt.NDArray], typing.Tuple[float, npt.NDArray, npt.NDArray]]
compute_mesh_quality()
def compute_mesh_quality(
    mesh: UnstructuredMesh, quality_metric: str = "edge_aspect_ratio"
) -> npt.NDArray: ...

Compute a few proxies for for mesh quality.

Parameters
  • mesh UnstructuredMesh — The mesh to compute it for.
  • quality_metric str — The quality metric to compute.
Returns npt.NDArray
compute_resolved_frequency()
def compute_resolved_frequency(
    mesh: UnstructuredMesh,
    min_velocity: npt.NDArray,
    elements_per_wavelength: float,
) -> typing.Tuple[float, npt.NDArray]: ...

Estimate the highest resolved frequency in each element.

Parameters
  • mesh UnstructuredMesh — The mesh to compute it for.
  • min_velocity npt.NDArray — Minimum velocity in each element.
  • elements_per_wavelength float — The elements per wavelength.
Returns typing.Tuple[float, npt.NDArray]
compute_spatial_gradients()
def compute_spatial_gradients(
    mesh: UnstructuredMesh,
    fields: typing.Optional[typing.Union[str, typing.List[str]]] = None,
) -> None: ...

Extract spatial model gradients.

This function takes a mesh object and computes the spatial model gradient of each field contained in the mesh. The function returns the same mesh with additional fields for each component of the gradient.

Model gradients are always computed in Cartesian coordinates. By construction of the Lagrange basis, the gradients are not continuous across elemental boundaries. Hence, the values of the gradient on points shared between elements, depend on which element they are computed in.

Parameters
  • mesh UnstructuredMesh — Mesh object for which model gradients are to be computed.
  • fields typing.Optional[typing.Union[str, typing.List[str]]] — Optional list of fields for which model gradients should be computed. Defaults to all fields contained in the mesh.
Returns None
copy()
def copy(self) -> UnstructuredMesh: ...

Return a deep copy of the object.

Returns UnstructuredMesh
create_side_set()
def create_side_set(
    mesh: UnstructuredMesh,
    side_set_name: str,
    side_set: typing.Optional[
        typing.Union[
            typing.Tuple[npt.NDArray, npt.NDArray],
            typing.Set[typing.Tuple[int, int]],
        ]
    ] = None,
    element_indices: typing.Optional[npt.NDArray] = None,
    side_indices: typing.Optional[npt.NDArray] = None,
) -> None: ...

Create a new side set on the mesh.

There are a two options here:

  • Provide the element and side indices.
  • Directly provide the side set set as provided by UnstructuredMesh.get_side_set().
Parameters
  • mesh UnstructuredMesh — The mesh.
  • side_set_name str — The name of the to be create side set.
  • side_set typing.Optional[typing.Union[typing.Tuple[npt.NDArray, npt.NDArray], typing.Set[typing.Tuple[int, int]]]] — Directly provide the side set.
  • element_indices typing.Optional[npt.NDArray] — The global element indices for the new side set.
  • side_indices typing.Optional[npt.NDArray] — The side ids to use for each element.
Returns None
estimate_resolved_frequency()
def estimate_resolved_frequency(
    mesh: UnstructuredMesh,
    min_velocity: npt.NDArray,
    elements_per_wavelength: float,
) -> typing.Tuple[float, npt.NDArray]: ...

Estimate the highest resolved frequency in each element.

Parameters
  • mesh UnstructuredMesh — The mesh to compute it for.
  • min_velocity npt.NDArray — Minimum velocity in each element.
  • elements_per_wavelength float — The elements per wavelength.
Returns typing.Tuple[float, npt.NDArray]
estimate_time_step()
def estimate_time_step(
    mesh: UnstructuredMesh,
    max_velocity: typing.Union[npt.NDArray, float],
    courant_number: float = 1.0,
    min_gll_point_distance: float = 1.0,
    fast: bool = True,
    return_hmin_elemnodes: bool = False,
) -> typing.Union[
    typing.Tuple[float, npt.NDArray],
    typing.Tuple[float, npt.NDArray, npt.NDArray],
]: ...

Compute an estimation of the time step set by each element.

Parameters
  • mesh UnstructuredMesh — The mesh to compute it for.
  • max_velocity typing.Union[npt.NDArray, float] — Fastest velocity in each element.
  • courant_number float — Courant number
  • min_gll_point_distance float — min_gll_point_distance
  • fast bool — fast
  • return_hmin_elemnodes bool — return_hmin_elemnodes
Returns typing.Union[typing.Tuple[float, npt.NDArray], typing.Tuple[float, npt.NDArray, npt.NDArray]]
extrude()
def extrude(
    mesh: UnstructuredMesh,
    offsets: npt.NDArray,
    scale: typing.Optional[npt.NDArray] = None,
    rotation: typing.Optional[npt.NDArray] = None,
    center: typing.Optional[npt.NDArray] = None,
) -> UnstructuredMesh: ...

Extrude a 2D mesh to create a 3D mesh.

Each extruded 2D mesh can be offset, scaled and rotated copies of the original.

Parameters
  • mesh UnstructuredMesh — The mesh to extrude.
  • offsets npt.NDArray — offsets, either in the new dimension or all 3 dimension, shape is (nextrude, ) or (nextrude, 3)
  • scale typing.Optional[npt.NDArray] — scaling factor for each extruded copy, relative to the center, shape is (nextrude,)
  • rotation typing.Optional[npt.NDArray] — rotation of each extruded copy in terms of euler angles relative to the center, shape is (nextrude, 3)
  • center typing.Optional[npt.NDArray] — center coordinates for rotation, defaults to the center of mass of the original 2D mesh, shape is (3,)
Returns UnstructuredMesh
extrude_side_set()
def extrude_side_set(
    mesh: UnstructuredMesh,
    side_set: str,
    offsets: npt.NDArray,
    scale: typing.Optional[npt.NDArray] = None,
    rotation: typing.Optional[npt.NDArray] = None,
    center: typing.Optional[npt.NDArray] = None,
) -> UnstructuredMesh: ...

Extrude a side set to add new elements to the mesh.

Parameters
  • mesh UnstructuredMesh — The mesh to extrude.
  • side_set str — name of the side set
  • offsets npt.NDArray — offsets, either in the new dimension or all 3 dimension, shape is (nextrude, ) or (nextrude, 3)
  • scale typing.Optional[npt.NDArray] — scaling factor for each extruded copy, relative to the center, shape is (nextrude,)
  • rotation typing.Optional[npt.NDArray] — rotation of each extruded copy in terms of euler angles relative to the center, shape is (nextrude, 3)
  • center typing.Optional[npt.NDArray] — center coordinates for rotation, defaults to the center of mass of the original 2D mesh, shape is (3,)
Returns UnstructuredMesh
extrude_side_set_2D()
def extrude_side_set_2D(
    mesh: UnstructuredMesh,
    side_set: str,
    offsets: npt.NDArray,
    direction: typing.Optional[str] = None,
) -> UnstructuredMesh: ...

Extrude a side set of a 2D mesh and append new elements.

Currently, the functionality is limited to cartesian meshes with side sets that are aligned with the coordinate axis.

Parameters
  • mesh UnstructuredMesh — The mesh to extrude.
  • side_set str — name of the side set
  • offsets npt.NDArray — offsets, either in the new dimension or all 3 dimension, shape is (nextrude, ) or (nextrude, 3)
  • direction typing.Optional[str] — Optional axis of extrusion if offsets is a one-dimensional array. Must be x or y.
Returns UnstructuredMesh
find_side_sets()
def find_side_sets(
    mesh: UnstructuredMesh, mode: str = "cartesian", tolerance: float = 1e-08
) -> None: ...

Find surfaces of simple box or spherical meshes in 2 or 3 dimension.

Use UnstructuredMesh.find_surface() for more complex shapes.

Parameters
  • mesh UnstructuredMesh — The unstructured mesh.
  • mode str — the side sets to be found depend on the shape of the mesh, should be one of “cartesian”, “cylindrical”, “spherical_full”, “spherical_chunk”, “spherical_chunk_z”, or “spherical_SmoothieSEM”.
  • tolerance float — Floating point tolerance to assume a node is on a given side.
Returns None
find_side_sets_enclosing()
def find_side_sets_enclosing(
    mesh: UnstructuredMesh, mode: str = "cartesian", tolerance: float = 1e-08
) -> None: ...

Find surfaces of simple box or spherical meshes in 2 or 3 dimension, augmented by a catch-all surface for unidentified portions of the surface, named “remainder_side_set”.

Runs find_side_sets followed by find_surface to find the remainder side-sets of any non-found facets. Uniquefies side-sets, which will alter existing side-sets.

Parameters
  • mesh UnstructuredMesh — The unstructured mesh.
  • mode str — the side sets to be found depend on the shape of the mesh, should be one of “cartesian”, “cylindrical”, “spherical_full”, “spherical_chunk”, “spherical_chunk_z”, or “spherical_SmoothieSEM”.
  • tolerance float — Floating point tolerance to assume a node is on a given side.
Returns None
find_side_sets_generic()
def find_side_sets_generic(
    mesh: UnstructuredMesh,
    name: str,
    distance: typing.Union[
        typing.Callable[[npt.NDArray], npt.NDArray], npt.NDArray
    ],
    tolerance: float = 1e-08,
    attach_side_set: bool = True,
) -> typing.Optional[typing.Tuple[npt.NDArray, npt.NDArray]]: ...

Find side sets based on a distance function.

Parameters
  • mesh UnstructuredMesh — The mesh.
  • name str — Name of the new side set.
  • distance typing.Union[typing.Callable[[npt.NDArray], npt.NDArray], npt.NDArray] — Callback function taking in points and returning a distance.
  • tolerance float — Point with a distance beneath this are part of the side set.
  • attach_side_set bool — If true, add the side set to the mesh, othewise return the side set elements and sides.
Returns typing.Optional[typing.Tuple[npt.NDArray, npt.NDArray]]
find_surface()
def find_surface(
    mesh: UnstructuredMesh, side_set_name: str = "surface"
) -> None: ...

Mark all surface faces as a side set.

Parameters
  • mesh UnstructuredMesh — The mesh to use.
  • side_set_name str — Name to give to the found surface.
Returns None
get_element_centroid()
def get_element_centroid(
    mesh: UnstructuredMesh, spherical: bool = False
) -> npt.NDArray: ...

For each element, compute its centroid.

Parameters
  • mesh UnstructuredMesh — The mesh.
  • spherical bool — Assume a spherical mesh to perform a spherical computation.
Returns npt.NDArray
get_element_centroid_radius()
def get_element_centroid_radius(mesh: UnstructuredMesh) -> npt.NDArray: ...

Get the radius of the centroid of each element for spherical meshes.

Compute the centroids of all elements on the fly from the nodes of the mesh. Useful to determine which domain in a layered medium an element belongs to or to compute elemental properties from the model. This function computes the spherical radius directly and is hence more memory efficient than UnstructuredMesh.get_element_centroid()

Parameters
  • mesh UnstructuredMesh — The mesh.
Returns npt.NDArray
get_element_nodes()
def get_element_nodes(
    mesh: UnstructuredMesh,
    mask: typing.Union[typing.Tuple, npt.NDArray] = (slice(None, None, None),),
) -> npt.NDArray: ...

Get the nodes for each element in the mesh.

Get duplicated nodes, i.e. an array with shape (nelem, nodes_per_element, ndim) containing the node locations for all elements for all nodes. This can be significant in terms of memory requirements.

Parameters
  • mesh UnstructuredMesh — The mesh.
  • mask typing.Union[typing.Tuple, npt.NDArray] — An optional mask to apply to the connectivity before returning the points.
Returns npt.NDArray
get_side_set()
def get_side_set(
    mesh: UnstructuredMesh, name: str
) -> typing.Set[typing.Tuple[int, int]]: ...

Get one side set as a set.

Useful for logical operations on side sets.

Parameters
  • mesh UnstructuredMesh — The mesh.
  • name str — Name of the side set.
Returns typing.Set[typing.Tuple[int, int]]
get_side_set_facet_nodes()
def get_side_set_facet_nodes(
    mesh: UnstructuredMesh, name: str
) -> typing.Tuple[npt.NDArray[np.float_], npt.NDArray[np.int_]]: ...

Get the tensorized nodes along a side set.

Note that this function respects the tensor order of the mesh, and will therefore return nodes equivalent to a tensorized quad in 3-D and all the nodes along an edge in 2-D.

Parameters
  • mesh UnstructuredMesh — The mesh.
  • name str — The name of the side set.
Returns typing.Tuple[npt.NDArray[np.float_], npt.NDArray[np.int_]] — A tuple of two values: 1st value: The tensorized nodes along the side set, with the shape (n_elem_on_side_set, n_points_per_facet, n_dim). 2st value: The global element nodes indices corresponding to the returned tensorized points.
get_side_set_nodes()
def get_side_set_nodes(mesh: UnstructuredMesh, name: str) -> npt.NDArray: ...

Return side set node ids as an array.

Parameters
  • mesh UnstructuredMesh — The mesh.
  • name str — Name of the side set.
Returns npt.NDArray
jacobian_at_nodes()
def jacobian_at_nodes(mesh: UnstructuredMesh) -> npt.NDArray: ...

Compute the Jacobian at each element and each node.

Parameters
  • mesh UnstructuredMesh — The mesh.
Returns npt.NDArray — The Jacobian: [n_elm, n_node, n_dim, n_dim].
map_nodal_fields_to_element_nodal()
def map_nodal_fields_to_element_nodal(self) -> None: ...

Map all nodal fields to element nodal and reset the nodal fields dictionary. To be used to store such data using UnstructuredMesh.write_h5

Returns None
queue_mesh_deformations_2D()
def queue_mesh_deformations_2D(
    mesh: UnstructuredMesh,
    x: npt.NDArray,
    deformation: npt.NDArray,
    vertical_begin_deformation: float = 0.0,
    vertical_end_deformation: float = inf,
    vertical_reference: typing.Optional[float] = None,
    name: typing.Optional[str] = None,
    mode: DeformationMode2D | str = DeformationMode2D.cartesian,
) -> None: ...

Queue a 2D deformation for later application.

Please see the compute_deformation_2D function for more information.

Parameters
  • mesh UnstructuredMesh — The mesh to queue for.
  • x npt.NDArray — horizontal coordinates of the deformation. Angle in radians for spherical models.
  • deformation npt.NDArray — The deformation sampled at coordinates x.
  • vertical_begin_deformation float — Don’t deform any points with a vertical coordinate smaller than this.
  • vertical_end_deformation float — Don’t deform any points with a vertical coordinate larger than this.
  • vertical_reference typing.Optional[float] — Vertical coordinate, at which the deformation should be applied, e.g. y-coordinate of the surface for surface deformation. Defaults to the max y coordinate / radius in case at least one of y0, y1 are finite.
  • name typing.Optional[str] — Optionally pass a name for the deformation.
  • mode DeformationMode2D | str — The deformation mode.
Returns None
queue_mesh_deformations_3D()
def queue_mesh_deformations_3D(
    mesh: UnstructuredMesh,
    x: npt.NDArray,
    y: npt.NDArray,
    deformation: npt.NDArray,
    vertical_begin_deformation: float = 0.0,
    vertical_end_deformation: float = inf,
    vertical_reference: typing.Optional[float] = None,
    interpolation_order: int = 3,
    mode: DeformationMode3D | str = DeformationMode3D.cartesian,
    name: typing.Optional[str] = None,
) -> None: ...

Queue a 3D deformation for later application.

Please see the compute_deformation_3D function for more information.

Parameters
  • mesh UnstructuredMesh — The mesh to queue for.
  • x npt.NDArray — first horizontal coordinate of the deformation. Angle in radians for spherical models.
  • y npt.NDArray — second horizontal coordinate of the deformation. Angle in radians for spherical models.
  • deformation npt.NDArray — The deformation sampled at coordinates x.
  • vertical_begin_deformation float — Don’t deform any points with a vertical coordinate smaller than this.
  • vertical_end_deformation float — Don’t deform any points with a vertical coordinate larger than this.
  • vertical_reference typing.Optional[float] — Vertical coordinate, at which the deformation should be applied, e.g. y-coordinate of the surface for surface deformation. Defaults to the max y coordinate / radius in case at least one of y0, y1 are finite.
  • interpolation_order int — Horizontal interpolation order.
  • mode DeformationMode3D | str — The deformation mode.
  • name typing.Optional[str] — Optionally pass a name for the deformation.
Returns None
queue_mesh_deformations_cylindrical()
def queue_mesh_deformations_cylindrical(
    mesh: UnstructuredMesh,
    phi: npt.NDArray,
    z: npt.NDArray,
    dem: npt.NDArray,
    r0: float = 0.0,
    r1: float = inf,
    rref: typing.Optional[float] = None,
    name: typing.Optional[str] = None,
) -> None: ...

Queue cylindrical deformations for later application.

Add deformation for cylindrical meshes where the axis of the cylinder is aligned with the z component. The DEM radially stretches the domain in the region of (x,y)-radii in [r0, r1] - points below r0 are kept fixed, points above r1 are moved as the DEM, points in between are interpolated and the full DEM is applied to points at rref.

Usage: first call add_dem_cylindrical for each boundary that is to be perturbed and finally call apply_dem to add the perturbation to the mesh coordinates.

Parameters
  • mesh UnstructuredMesh — The mesh.
  • phi npt.NDArray — Angle in the x-y-plane of the DEM in radians.
  • z npt.NDArray — z-coordinates of the DEM.
  • dem npt.NDArray — the DEM sampled at the coordinates (phi,z)
  • r0 float — radius in x-y-plane at which the stretching begins
  • r1 float — radius in x-y-plane at which the stretching ends, can be infinity
  • rref typing.Optional[float] — radius in x-y-plane at which the deformation should be applied
  • name typing.Optional[str] — name of this deformation to refer to it in UnstructuredMesh.apply_dem()
Returns None
refine_locally()
def refine_locally(
    mesh: UnstructuredMesh,
    mask: npt.NDArray,
    refinement_level: int = 1,
    hierarchical_map: typing.Optional[npt.NDArray] = None,
    refinement_type: RefinementType | str = RefinementType.unstable,
    interpolation_mode: InterpolationMode | str = InterpolationMode.linear,
    interpolation_kwargs: typing.Optional[typing.Dict] = None,
    reinterpolate_nodal_fields: bool = False,
    unique_points_tolerance: int = 12,
) -> typing.Optional[npt.NDArray]: ...

Refine the mesh locally using various refinement templates.

Please not that this will modify the mesh. Create a copy if you don’t desire this behavior.

New grid points are created by interpolating the existing corner points. This function supports a variety of interpolation modes (some of which require extra kwargs to set as part of the interpolation_kwargs dictionary):

  • "linear": The default. Perform a bi/trilinear interpolation. No extra keyword arguments are supported or required for this mode.
  • "spherical": Linearly interpolate radially, slerp laterally. The center of the sphere is always considered to be at the origin of the coordinate system. Supported additional keywords: "r0_spherical" and "r1_spherical". Don’t slerp < r0, slerp => r0, and linearly interpolate between both modes in between.
  • "cylindrical": Linearly interpolate radially and along the last dimension. Slerp in the middle dimension. Only makes sense in 3D, for 2D point symmetry use "spherical" Supported additional keywords: "r0_cylindrical" and "r1_cylindrical". Don’t slerp < r0, slerp => r0, and linearly interpolate between both modes in between.
  • "SmoothieSEM": Special for SmoothieSEM, only for expert usage.
Parameters
  • mesh UnstructuredMesh — The unstructured mesh to refine.
  • mask npt.NDArray — Mark either elements, nodes or edges to refine, boolean array with shape (nelem,), (npoint,) or (nelem, edges_per_element)
  • refinement_level int — Refinement level, can only be larger than 1 for stable schemes and an elemental mask.
  • hierarchical_map typing.Optional[npt.NDArray] — Pass a hierarchical map to keep track of which element in a coarser mesh the newly created elements belongs to.
  • refinement_type RefinementType | str — Choose the refinement style, currently available in 2D are ‘stable’, ‘unstable’, ‘stable_convex’ and ‘unstable_convex’, in 3D ‘unstable_unidir’, ‘unstable’, ‘stable_convex’, ‘unstable_convex’, ‘unstable_convex_dir’, ‘unstable_dir’. Here stable refers to maintaining the angles in multilevel refinements, convexity refers to the region in the mesh in terms of its connectivity (which may be different to its geometric shape for non-rectilinar meshes) and directionality refers to isotropic or anisotropic refinements (where the latter need an edge based refinement mask).
  • interpolation_mode InterpolationMode | str — How to interpolate the location of the new grid points. See above description.
  • interpolation_kwargs typing.Optional[typing.Dict] — Extra keyword arguments for the chosen interpolation mode. See above description.
  • reinterpolate_nodal_fields bool — map nodal fields to the newly created nodes using linear interpolation
  • unique_points_tolerance int — The number of decimal digits used to determine unique points in the refined mesh.
Returns typing.Optional[npt.NDArray]
rotate_coordinates()
def rotate_coordinates(
    mesh: UnstructuredMesh, euler_angles: npt.NDArray
) -> None: ...

Rotate the nodes coordinates around the origin.

Parameters
  • mesh UnstructuredMesh — The mesh.
  • euler_angles npt.NDArray — Euler-angles to rotate around.
Returns None
to_material()
def to_material(mesh: UnstructuredMesh) -> material.Material: ...

Create a material from the mesh, without encoding geometrical information.

Parameters
  • mesh UnstructuredMesh — The mesh.
Returns material.Material — The material, with all parameters of type ArrayParameter.
transform_material()
def transform_material(
    mesh: UnstructuredMesh,
    m: typing.Type[material.Material],
    reduction_method: (
        typing.Literal["remove-components", "force"] | None
    ) = None,
) -> UnstructuredMesh: ...

Transform the material of a mesh to another compatible material.

Parameters
  • mesh UnstructuredMesh — The mesh.
  • m typing.Type[material.Material] — The desired material.
  • reduction_method typing.Literal['remove-components', 'force'] | None — Method to move between incompatible symmetry classes. None will only move to symmetries that are equal or more permissive, while remove-components will drop components that are found to match the new material’s constraints as necessary, and thus leading to loss of free parameters but not of information. The option “force” will take all information necessary to construct the new parameter set without verification, leading to loss of information.
Returns UnstructuredMesh — A mesh with replaced elemental nodal fields for the material properties.
write_binary_vtk()
def write_binary_vtk(
    mesh: UnstructuredMesh, filename: typing.Union[str, pathlib.Path]
) -> None: ...

Write a binary VTK file.

Please note that this method currently writes the mesh without any attached material parameters. The advantage of using this output format is that ParaView can visualize high-order shapes (e.g. curved elements) in that format.

Parameters
  • mesh UnstructuredMesh — The mesh to write.
  • filename typing.Union[str, pathlib.Path] — Filename. Make sure it uses a .vtu extension so ParaView recognizes it.
Returns None
write_h5()
def write_h5(
    mesh: UnstructuredMesh,
    filename: typing.Union[str, pathlib.Path],
    datatype: typing.Type[np.number] = numpy.float64,
    compression: typing.Optional[typing.Tuple[str, int]] = None,
    mode: str = "model",
    write_chunk_size: int = 10000,
    overwrite: bool = True,
    periodic_bcs: typing.Optional[typing.List[typing.Tuple[str, str]]] = None,
) -> None: ...

Write the mesh to an h5 file with xdmf descriptor.

Parameters
  • mesh UnstructuredMesh — The mesh to write.
  • filename typing.Union[str, pathlib.Path] — Filename.
  • datatype typing.Type[np.number] — Datatype to write.
  • compression typing.Optional[typing.Tuple[str, int]] — Turn on compression. Pass a tuple of (method, option), e.g. ("gzip", 2). Slows down writing a lot but the resulting files are potentially much smaller.
  • mode str — one of "all", "model", "skeleton" or "minimal". Controls the content of the mesh file and whether an xdmf file is added. ‘all’: largest file size, multiple block xdmf file and faster reading from file with UnstructuredMesh.from_h5() ‘model’: all data to view the model, single block xdmf file for easy opening in paraview ‘skeleton’: only the first order connectivity can be viewed ‘minimal’: smallest file size, no xdmf.
  • write_chunk_size int — HDF5 chunk size in bytes.
  • overwrite bool — Potentially overwrite an existing file.
  • periodic_bcs typing.Optional[typing.List[typing.Tuple[str, str]]] — Pass a tuple of side sets that you would like to make periodic. For example: [("x0", "x1"), ("z0", "z1)]. This option will only work if the mesh has been derived from the StructuredGrid3D.cube() class.
Returns None
write_vtp()
def write_vtp(
    mesh: UnstructuredMesh,
    filename: typing.Union[str, pathlib.Path],
    side_sets: typing.List[str] = ["x0", "x1", "y0", "y1", "z0", "z1"],
) -> None: ...

Write the mesh to a vtp file, meant for visualization with the GUI.

In 3D, it only writes the hull.

Parameters
  • mesh UnstructuredMesh — The mesh to write.
  • filename typing.Union[str, pathlib.Path] — filename
  • side_sets typing.List[str] — Side sets to write.
Returns None