cashocs.geometry#

Mesh generation, quality, and management tools.

This module consists of tools for the fast generation of meshes into fenics. The regular_mesh and regular_box_mesh commands create 2D and 3D box meshes which are great for testing and development.

Functions

`compute_boundary_distance`(mesh[, ...])	Computes (an approximation of) the distance to the boundary.
`compute_mesh_quality`(mesh[, quality_type, ...])	This computes the mesh quality of a given mesh.
`generate_measure`(idx, measure)	Generates a measure based on indices.
`interval_mesh`([n, start, end, partitions, comm])	Creates an 1D interval mesh starting at x=0 to x=length.
`regular_box_mesh`([n, start_x, start_y, ...])	Creates a mesh corresponding to a rectangle or cube.
`regular_mesh`([n, length_x, length_y, ...])	Creates a mesh corresponding to a rectangle or cube.

Classes

`DeformationHandler`(mesh, a_priori_tester, ...)	A class, which implements mesh deformations.
`MeshQuality`()	A class used to compute the quality of a mesh.

class cashocs.geometry.DeformationHandler(mesh, a_priori_tester, intersection_tester)[source]#

Bases: object

A class, which implements mesh deformations.

The deformations can be due to a deformation vector field or a (piecewise) update of the mesh coordinates.

Initializes self.

Parameters:

mesh (fenics.Mesh) – The fenics mesh which is to be deformed.
a_priori_tester (mesh_testing.APrioriMeshTester) – The tester before mesh modification.
intersection_tester (mesh_testing.IntersectionTester) – The tester after mesh modification (for (self) intersections).

assign_coordinates(coordinates)[source]#

Assigns coordinates to self.mesh.

Parameters:: coordinates (ndarray) – Array of mesh coordinates, which you want to assign.
Returns:: True if the assignment was possible, False if not.
Return type:: bool

coordinate_to_dof(coordinate_deformation)[source]#

Converts a coordinate deformation to a deformation vector field (dof based).

Parameters:: coordinate_deformation (ndarray) – The deformation for the mesh coordinates.
Returns:: The deformation vector field.
Return type:: fenics.Function

dof_to_coordinate(dof_deformation)[source]#

Converts a deformation vector field to a coordinate based deformation.

Parameters:: dof_deformation (fenics.Function) – The deformation vector field.
Returns:: The array which can be used to deform the mesh coordinates.
Return type:: ndarray

move_mesh(transformation, validated_a_priori=False, test_for_intersections=True)[source]#

Transforms the mesh by perturbation of identity.

Moves the mesh according to the deformation given by

\[\text{id} + \mathcal{V}(x),\]

where \(\mathcal{V}\) is the transformation. This represents the perturbation of identity.

Parameters:

transformation (fenics.Function | ndarray) – The transformation for the mesh, a vector CG1 Function.
validated_a_priori (bool) – A boolean flag, which indicates whether an a-priori check has already been performed before moving the mesh. Default is False
test_for_intersections (bool) – A boolean flag which indicates whether an a-posteriori check for (self)-intersections of the mesh should be performed.

Returns:

True if the mesh movement was successful, False otherwise.

Return type:

bool

revert_transformation()[source]#

Reverts the previous mesh transformation.

This is used when the mesh quality for the resulting deformed mesh is not sufficient, or when the solution algorithm terminates, e.g., due to lack of sufficient decrease in the Armijo rule

Return type:: None

class cashocs.geometry.MeshQuality[source]#

Bases: object

A class used to compute the quality of a mesh.

All quality measures have values in \([0,1]\), where 1 corresponds to the reference (optimal) element, and 0 corresponds to degenerate elements.

classmethod avg(calculator, mesh)[source]#

Computes the average mesh quality.

Parameters:

calculator (MeshQualityCalculator) – The calculator used to compute the mesh quality.
mesh (fenics.Mesh) – The mesh under investigation.

Returns:

The average mesh quality according to the measure used.

Return type:

float

classmethod min(calculator, mesh)[source]#

Computes the minimum mesh quality.

Parameters:

calculator (MeshQualityCalculator) – The calculator used to compute the mesh quality.
mesh (fenics.Mesh) – The mesh under investigation.

Returns:

The minimum mesh quality according to the measure used.

Return type:

float

cashocs.geometry.compute_boundary_distance(mesh, boundaries=None, boundary_idcs=None, tol=0.1, max_iter=10)[source]#

Computes (an approximation of) the distance to the boundary.

The function iteratively solves the Eikonal equation to compute the distance to the boundary.

The user can specify which boundaries are considered for the distance computation by specifying the parameters boundaries and boundary_idcs. Default is to consider all boundaries.

Parameters:

mesh (fenics.Mesh) – The dolfin mesh object, representing the computational domain
boundaries (fenics.MeshFunction | None) – A meshfunction for the boundaries, which is needed in case specific boundaries are targeted for the distance computation (while others are ignored), default is None (all boundaries are used).
boundary_idcs (List[int | str] | None) – A list of indices which indicate, which parts of the boundaries should be used for the distance computation, default is None (all boundaries are used).
tol (float) – A tolerance for the iterative solution of the eikonal equation. Default is 1e-1.
max_iter (int) – Number of iterations for the iterative solution of the eikonal equation. Default is 10.

Returns:

A fenics function representing an approximation of the distance to the boundary.

Return type:

fenics.Function

cashocs.geometry.compute_mesh_quality(mesh, quality_type='min', quality_measure='skewness')[source]#

This computes the mesh quality of a given mesh.

Parameters:

mesh (fenics.Mesh) – The mesh whose quality shall be computed.
quality_type (str) – The type of measurement for the mesh quality, either minimum quality or average quality over all mesh cells, default is ‘min’.
quality_measure (str) – The type of quality measure which is used to compute the quality measure, default is ‘skewness’

Returns:

The quality of the mesh, in the interval \([0,1]\), where 0 is the worst, and 1 the best possible quality.

Return type:

float

cashocs.geometry.generate_measure(idx, measure)[source]#

Generates a measure based on indices.

Generates a fenics.MeasureSum or _EmptyMeasure object corresponding to measure and the subdomains / boundaries specified in idx. This is a convenient shortcut to writing dx(1) + dx(2) + dx(3) in case many measures are involved.

Parameters:

idx (List[int]) – A list of indices for the boundary / volume markers that define the (new) measure.
measure (fenics.Measure) – The corresponding UFL measure.

Returns:

The corresponding sum of the measures or an empty measure.

Return type:

fenics.Measure | _EmptyMeasure

Examples

Here, we create a wrapper for the surface measure on the top and bottom of the unit square:

import fenics
import cashocs

mesh, _, boundaries, dx, ds, _ = cashocs.regular_mesh(25)
top_bottom_measure = cashocs.geometry.generate_measure([3,4], ds)
fenics.assemble(1*top_bottom_measure)

cashocs.geometry.interval_mesh(n=10, start=0.0, end=1.0, partitions=None, comm=None)[source]#

Creates an 1D interval mesh starting at x=0 to x=length.

This function creates a uniform mesh of a 1D interval, starting at the start and ending at end. The resulting mesh uses n sub-intervals to discretize the geometry. The boundary markers are as follows:

1 corresponds to \(x=start\)

2 corresponds to \(x=end\)

Parameters:

n (int) – Number of elements for discretizing the interval, default is 10
start (float) – The start of the interval, default is 0.0
end (float) – The end of the interval, default is 1.0
partitions (Optional[List[float]]) – Points in the interval at which a partition in subdomains should be made. The resulting volume measure is sorted ascendingly according to the sub-intervals defined in partitions (starting at 1). Defaults to None.
comm (Optional[MPI.Comm]) – MPI communicator that is to be used for creating the mesh.

Returns:

A tuple (mesh, subdomains, boundaries, dx, ds, dS), where mesh is the imported FEM mesh, subdomains is a mesh function for the subdomains, boundaries is a mesh function for the boundaries, dx is a volume measure, ds is a surface measure, and dS is a measure for the interior facets.

Return type:

_typing.MeshTuple

cashocs.geometry.regular_box_mesh(n=10, start_x=0.0, start_y=0.0, start_z=None, end_x=1.0, end_y=1.0, end_z=None, diagonal='right', comm=None)[source]#

Creates a mesh corresponding to a rectangle or cube.

This function creates a uniform mesh of either a rectangle or a cube, with specified start (S_) and end points (E_). The resulting mesh uses n elements along the shortest direction and accordingly many along the longer ones. The resulting domain is

\[\begin{split}\begin{alignedat}{2} &[start_x, end_x] \times [start_y, end_y] \quad &&\text{ in } 2D, \\ &[start_x, end_x] \times [start_y, end_y] \times [start_z, end_z] \quad &&\text{ in } 3D. \end{alignedat}\end{split}\]

The boundary markers are ordered as follows:

1 corresponds to \(x=start_x\).

2 corresponds to \(x=end_x\).

3 corresponds to \(y=start_y\).

4 corresponds to \(y=end_y\).

5 corresponds to \(z=start_z\) (only in 3D).

6 corresponds to \(z=end_z\) (only in 3D).

Parameters:

n (int) – Number of elements in the shortest coordinate direction.
start_x (float) – Start of the x-interval.
start_y (float) – Start of the y-interval.
start_z (Optional[float]) – Start of the z-interval, mesh is 2D if this is None (default is None).
end_x (float) – End of the x-interval.
end_y (float) – End of the y-interval.
end_z (Optional[float]) – End of the z-interval, mesh is 2D if this is None (default is None).
diagonal (Literal['right', 'left', 'left/right', 'right/left', 'crossed']) – This defines the type of diagonal used to create the box mesh in 2D. This can be one of "right", "left", "left/right", "right/left" or "crossed".
comm (Optional[MPI.Comm]) – MPI communicator that is to be used for creating the mesh.

Returns:

Return type:

_typing.MeshTuple

cashocs.geometry.regular_mesh(n=10, length_x=1.0, length_y=1.0, length_z=None, diagonal='right', comm=None)[source]#

Creates a mesh corresponding to a rectangle or cube.

This function creates a uniform mesh of either a rectangle or a cube, starting at the origin and having length specified in length_x, length_y, and length_z. The resulting mesh uses n elements along the shortest direction and accordingly many along the longer ones. The resulting domain is

\[\begin{split}\begin{alignedat}{2} &[0, length_x] \times [0, length_y] \quad &&\text{ in } 2D, \\ &[0, length_x] \times [0, length_y] \times [0, length_z] \quad &&\text{ in } 3D. \end{alignedat}\end{split}\]

The boundary markers are ordered as follows:

1 corresponds to \(x=0\).

2 corresponds to \(x=length_x\).

3 corresponds to \(y=0\).

4 corresponds to \(y=length_y\).

5 corresponds to \(z=0\) (only in 3D).

6 corresponds to \(z=length_z\) (only in 3D).

Parameters:

n (int) – Number of elements in the shortest coordinate direction.
length_x (float) – Length in x-direction.
length_y (float) – Length in y-direction.
length_z (Optional[float]) – Length in z-direction, if this is None, then the geometry will be two-dimensional (default is None).
diagonal (Literal['left', 'right', 'left/right', 'right/left', 'crossed']) – This defines the type of diagonal used to create the box mesh in 2D. This can be one of "right", "left", "left/right", "right/left" or "crossed".
comm (Optional[MPI.Comm]) – MPI communicator that is to be used for creating the mesh.

Returns:

Return type:

_typing.MeshTuple

Modules

`cashocs.geometry.boundary_distance`	Compute the distance to the boundary.
`cashocs.geometry.deformations`	Management of mesh deformations.
`cashocs.geometry.measure`	Extension of integration measures.
`cashocs.geometry.mesh`	Basic mesh generation.
`cashocs.geometry.mesh_handler`	Management of finite element meshes.
`cashocs.geometry.mesh_testing`	Testing of mesh quality.
`cashocs.geometry.quality`	Mesh quality computation.