dolfinx::mesh Namespace Reference

Mesh data structures and algorithms on meshes. More...

Classes
class	Geometry
	Geometry stores the geometry imposed on a mesh. More...
class	Mesh
	A Mesh consists of a set of connected and numbered mesh topological entities, and geometry data. More...
class	MeshTags
	MeshTags associate values with mesh topology entities. More...
class	Topology
	Topology stores the topology of a mesh, consisting of mesh entities and connectivity (incidence relations for the mesh entities). More...

Concepts
concept	MarkerFn
	Requirements on function for geometry marking.

Typedefs
using	CellPartitionFunction
	Signature for the cell partitioning function. The function should compute the destination rank for cells currently on this rank.

Enumerations
enum class	CellType : int {   point = 1 , interval = 2 , triangle = 3 , tetrahedron = 4 ,   quadrilateral = -4 , pyramid = -5 , prism = -6 , hexahedron = -8 }
	Cell type identifier.
enum class	DiagonalType {   left , right , crossed , shared_facet ,   left_right , right_left }
	Enum for different diagonal types.
enum class	GhostMode : int { none , shared_facet , shared_vertex }
	Enum for different partitioning ghost modes.

Functions
std::string	to_string (CellType type)
CellType	to_type (const std::string &cell)
CellType	cell_entity_type (CellType type, int d, int index)
	Return type of cell for entity of dimension d at given entity index.
CellType	cell_facet_type (CellType type, int index)
graph::AdjacencyList< int >	get_entity_vertices (CellType type, int dim)
graph::AdjacencyList< int >	get_sub_entities (CellType type, int dim0, int dim1)
int	cell_dim (CellType type)
	Return topological dimension of cell type.
int	cell_num_entities (CellType type, int dim)
bool	is_simplex (CellType type)
int	num_cell_vertices (CellType type)
std::map< std::array< int, 2 >, std::vector< std::set< int > > >	cell_entity_closure (CellType cell_type)
basix::cell::type	cell_type_to_basix_type (CellType celltype)
	Convert a cell type to a Basix cell type.
CellType	cell_type_from_basix_type (basix::cell::type celltype)
	Get a cell type from a Basix cell type.
template<std::floating_point T = double>
Mesh< T >	create_box (MPI_Comm comm, MPI_Comm subcomm, std::array< std::array< T, 3 >, 2 > p, std::array< std::int64_t, 3 > n, CellType celltype, CellPartitionFunction partitioner=nullptr)
	Create a uniform mesh::Mesh over rectangular prism spanned by the two points p.
template<std::floating_point T = double>
Mesh< T >	create_box (MPI_Comm comm, std::array< std::array< T, 3 >, 2 > p, std::array< std::int64_t, 3 > n, CellType celltype, const CellPartitionFunction &partitioner=nullptr)
	Create a uniform mesh::Mesh over rectangular prism spanned by the two points p.
template<std::floating_point T = double>
Mesh< T >	create_rectangle (MPI_Comm comm, std::array< std::array< T, 2 >, 2 > p, std::array< std::int64_t, 2 > n, CellType celltype, CellPartitionFunction partitioner, DiagonalType diagonal=DiagonalType::right)
	Create a uniform mesh::Mesh over the rectangle spanned by the two points p.
template<std::floating_point T = double>
Mesh< T >	create_rectangle (MPI_Comm comm, std::array< std::array< T, 2 >, 2 > p, std::array< std::int64_t, 2 > n, CellType celltype, DiagonalType diagonal=DiagonalType::right)
	Create a uniform mesh::Mesh over the rectangle spanned by the two points p.
template<std::floating_point T = double>
Mesh< T >	create_interval (MPI_Comm comm, std::int64_t n, std::array< T, 2 > p, mesh::GhostMode ghost_mode=mesh::GhostMode::none, CellPartitionFunction partitioner=nullptr)
	Interval mesh of the 1D line [a, b].
template<typename U >
Geometry< typename std::remove_reference_t< typename U::value_type > >	create_geometry (const Topology &topology, const std::vector< fem::CoordinateElement< std::remove_reference_t< typename U::value_type > > > &elements, std::span< const std::int64_t > nodes, std::span< const std::int64_t > xdofs, const U &x, int dim, std::function< std::vector< int >(const graph::AdjacencyList< std::int32_t > &)> reorder_fn=nullptr)
	Build Geometry from input data.
template<typename U >
Geometry< typename std::remove_reference_t< typename U::value_type > >	create_geometry (const Topology &topology, const fem::CoordinateElement< std::remove_reference_t< typename U::value_type > > &element, std::span< const std::int64_t > nodes, std::span< const std::int64_t > xdofs, const U &x, int dim, std::function< std::vector< int >(const graph::AdjacencyList< std::int32_t > &)> reorder_fn=nullptr)
	Build Geometry from input data.
std::tuple< graph::AdjacencyList< std::int32_t >, std::vector< std::int64_t >, std::size_t, std::vector< std::int32_t > >	build_local_dual_graph (std::span< const CellType > celltypes, const std::vector< std::span< const std::int64_t > > &cells)
	Compute the local part of the dual graph (cell-cell connections via facets) and facets with only one attached cell.
graph::AdjacencyList< std::int64_t >	build_dual_graph (MPI_Comm comm, std::span< const CellType > celltypes, const std::vector< std::span< const std::int64_t > > &cells)
	Build distributed mesh dual graph (cell-cell connections via facets) from minimal mesh data.
template<typename T >
MeshTags< T >	create_meshtags (std::shared_ptr< const Topology > topology, int dim, const graph::AdjacencyList< std::int32_t > &entities, std::span< const T > values)
	Create MeshTags from arrays.
std::pair< std::vector< std::uint8_t >, std::vector< std::uint32_t > >	compute_entity_permutations (const Topology &topology)
Topology	create_topology (MPI_Comm comm, std::span< const std::int64_t > cells, std::span< const std::int64_t > original_cell_index, std::span< const int > ghost_owners, CellType cell_type, std::span< const std::int64_t > boundary_vertices)
	Create a mesh topology.
Topology	create_topology (MPI_Comm comm, const std::vector< CellType > &cell_type, std::vector< std::span< const std::int64_t > > cells, std::vector< std::span< const std::int64_t > > original_cell_index, std::vector< std::span< const int > > ghost_owners, std::span< const std::int64_t > boundary_vertices)
	Create a topology of mixed cell type.
std::tuple< Topology, std::vector< int32_t >, std::vector< int32_t > >	create_subtopology (const Topology &topology, int dim, std::span< const std::int32_t > entities)
	Create a topology for a subset of entities of a given topological dimension.
std::vector< std::int32_t >	entities_to_index (const Topology &topology, int dim, std::span< const std::int32_t > entities)
	Get entity indices for entities defined by their vertices.
std::tuple< std::vector< std::shared_ptr< graph::AdjacencyList< std::int32_t > > >, std::shared_ptr< graph::AdjacencyList< std::int32_t > >, std::shared_ptr< common::IndexMap >, std::vector< std::int32_t > >	compute_entities (MPI_Comm comm, const Topology &topology, int dim, int index)
	Compute mesh entities of given topological dimension by computing entity-to-vertex connectivity (dim, 0), and cell-to-entity connectivity (tdim, dim).
std::array< std::shared_ptr< graph::AdjacencyList< std::int32_t > >, 2 >	compute_connectivity (const Topology &topology, std::pair< std::int8_t, std::int8_t > d0, std::pair< std::int8_t, std::int8_t > d1)
	Compute connectivity (d0 -> d1) for given pair of entity types, given by topological dimension and index, as found in Topology::entity_types()
std::vector< std::int32_t >	exterior_facet_indices (const Topology &topology)
	Compute the indices of all exterior facets that are owned by the caller.
std::vector< std::int64_t >	extract_topology (CellType cell_type, const fem::ElementDofLayout &layout, std::span< const std::int64_t > cells)
	Extract topology from cell data, i.e. extract cell vertices.
template<std::floating_point T>
std::vector< T >	h (const Mesh< T > &mesh, std::span< const std::int32_t > entities, int dim)
	Compute greatest distance between any two vertices of the mesh entities (h).
template<std::floating_point T>
std::vector< T >	cell_normals (const Mesh< T > &mesh, int dim, std::span< const std::int32_t > entities)
	Compute normal to given cell (viewed as embedded in 3D)
template<std::floating_point T>
std::vector< T >	compute_midpoints (const Mesh< T > &mesh, int dim, std::span< const std::int32_t > entities)
	Compute the midpoints for mesh entities of a given dimension.
template<std::floating_point T, MarkerFn< T > U>
std::vector< std::int32_t >	locate_entities (const Mesh< T > &mesh, int dim, U marker)
	Compute indices of all mesh entities that evaluate to true for the provided geometric marking function.
template<std::floating_point T, MarkerFn< T > U>
std::vector< std::int32_t >	locate_entities_boundary (const Mesh< T > &mesh, int dim, U marker)
	Compute indices of all mesh entities that are attached to an owned boundary facet and evaluate to true for the provided geometric marking function.
template<std::floating_point T>
std::vector< std::int32_t >	entities_to_geometry (const Mesh< T > &mesh, int dim, std::span< const std::int32_t > entities, bool permute=false)
	Compute the geometry degrees of freedom associated with the closure of a given set of cell entities.
CellPartitionFunction	create_cell_partitioner (mesh::GhostMode ghost_mode=mesh::GhostMode::none, const graph::partition_fn &partfn=&graph::partition_graph)
std::vector< std::int32_t >	compute_incident_entities (const Topology &topology, std::span< const std::int32_t > entities, int d0, int d1)
	Compute incident indices.
template<typename U >
Mesh< typename std::remove_reference_t< typename U::value_type > >	create_mesh (MPI_Comm comm, MPI_Comm commt, std::span< const std::int64_t > cells, const fem::CoordinateElement< typename std::remove_reference_t< typename U::value_type > > &element, MPI_Comm commg, const U &x, std::array< std::size_t, 2 > xshape, const CellPartitionFunction &partitioner)
	Create a distributed mesh from mesh data using a provided graph partitioning function for determining the parallel distribution of the mesh.
template<typename U >
Mesh< typename std::remove_reference_t< typename U::value_type > >	create_mesh (MPI_Comm comm, MPI_Comm commt, const std::vector< std::span< const std::int64_t > > &cells, const std::vector< fem::CoordinateElement< typename std::remove_reference_t< typename U::value_type > > > &elements, MPI_Comm commg, const U &x, std::array< std::size_t, 2 > xshape, const CellPartitionFunction &partitioner)
	Create a distributed mixed-topology mesh from mesh data using a provided graph partitioning function for determining the parallel distribution of the mesh.
template<typename U >
Mesh< typename std::remove_reference_t< typename U::value_type > >	create_mesh (MPI_Comm comm, std::span< const std::int64_t > cells, const fem::CoordinateElement< std::remove_reference_t< typename U::value_type > > &elements, const U &x, std::array< std::size_t, 2 > xshape, GhostMode ghost_mode)
	Create a distributed mesh from mesh data using the default graph partitioner to determine the parallel distribution of the mesh.
template<std::floating_point T>
std::pair< Geometry< T >, std::vector< int32_t > >	create_subgeometry (const Mesh< T > &mesh, int dim, std::span< const std::int32_t > subentity_to_entity)
	Create a sub-geometry from a mesh and a subset of mesh entities to be included. A sub-geometry is simply a Geometry object containing only the geometric information for the subset of entities. The entities may differ in topological dimension from the original mesh.
template<std::floating_point T>
std::tuple< Mesh< T >, std::vector< std::int32_t >, std::vector< std::int32_t >, std::vector< std::int32_t > >	create_submesh (const Mesh< T > &mesh, int dim, std::span< const std::int32_t > entities)
	Create a new mesh consisting of a subset of entities in a mesh.

Detailed Description

Mesh data structures and algorithms on meshes.

Representations of meshes and support for operations on meshes.

Typedef Documentation

CellPartitionFunction

using CellPartitionFunction

Initial value:

 std::function<graph::AdjacencyList<std::int32_t>(
    MPI_Comm comm, int nparts, const std::vector<CellType>& cell_types,
    const std::vector<std::span<const std::int64_t>>& cells)>

Signature for the cell partitioning function. The function should compute the destination rank for cells currently on this rank.

Parameters

[in]	comm	MPI Communicator
[in]	nparts	Number of partitions
[in]	cell_types	Cell types in the mesh
[in]	cells	Lists of cells of each cell type. cells[i] is a flattened row major 2D array of shape (num_cells, num_cell_vertices) for cell_types[i] on this process, containing the global indices for the cell vertices. Each cell can appear only once across all processes. The cell vertex indices are not necessarily contiguous globally, i.e. the maximum index across all processes can be greater than the number of vertices. High-order 'nodes', e.g. mid-side points, should not be included.

Returns

Destination ranks for each cell on this process

Note

Cells can have multiple destination ranks, when ghosted.

Function Documentation

build_dual_graph()

graph::AdjacencyList< std::int64_t > build_dual_graph	(	MPI_Comm	comm,
		std::span< const CellType >	celltypes,
		const std::vector< std::span< const std::int64_t > > &	cells )

Build distributed mesh dual graph (cell-cell connections via facets) from minimal mesh data.

The computed dual graph is typically passed to a graph partitioner.

Note

Collective function

Parameters

[in]	comm	The MPI communicator
[in]	celltypes	List of cell types
[in]	cells	Collections of cells, defined by the cell vertices from which to build the dual graph, as flattened arrays for each cell type in celltypes.

Note

cells and celltypes must have the same size.

Returns

The dual graph

build_local_dual_graph()

std::tuple< graph::AdjacencyList< std::int32_t >, std::vector< std::int64_t >, std::size_t, std::vector< std::int32_t > > build_local_dual_graph	(	std::span< const CellType >	celltypes,
		const std::vector< std::span< const std::int64_t > > &	cells )

Compute the local part of the dual graph (cell-cell connections via facets) and facets with only one attached cell.

Parameters

[in]	celltypes	List of cell types.
[in]	cells	Lists of cell vertices (stored as flattened lists, one for each cell type).

Returns

1. Local dual graph
2. Facets, defined by their vertices, that are shared by only one cell on this rank. The logically 2D array is flattened (row-major).
3. The number of columns for the facet data array (2).
4. The attached cell (local index) to each returned facet in (2).

Each row of the returned data (2) contains [v0, ... v_(n-1), x, .., / x], where v_i is a vertex global index, x is a padding value (all padding values will be equal).

Note

The cells of each cell type are numbered locally consecutively, i.e. if there are n cells of type 0 and m cells of type 1, then cells of type 0 are numbered 0..(n-1) and cells of type 1 are numbered n..(n+m-1) respectively, in the returned dual graph.

cell_entity_closure()

std::map< std::array< int, 2 >, std::vector< std::set< int > > > cell_entity_closure

(

CellType

cell_type

)

Closure entities for a cell, i.e., all lower-dimensional entities attached to a cell entity. Map from entity {dim_e, entity_e} to closure{sub_dim, (sub_entities)}

cell_facet_type()

mesh::CellType cell_facet_type	(	CellType	type,
		int	index )

Return facet type of cell For simplex and hypercube cell types, this is independent of the facet index, but for prism and pyramid, it can be triangle or quadrilateral.

Parameters

[in]	type	The cell type
[in]	index	The facet index

Returns

The type of facet for this cell at this index

cell_normals()

template<std::floating_point T>

std::vector< T > cell_normals	(	const Mesh< T > &	mesh,
		int	dim,
		std::span< const std::int32_t >	entities )

Compute normal to given cell (viewed as embedded in 3D)

Returns

The entity normals. The shape is (entities.size(), 3) and the storage is row-major.

cell_num_entities()

int cell_num_entities	(	CellType	type,
		int	dim )

Number of entities of dimension dim

Parameters

[in]	dim	Entity dimension
[in]	type	Cell type

Returns

Number of entities in cell

compute_connectivity()

std::array< std::shared_ptr< graph::AdjacencyList< std::int32_t > >, 2 > compute_connectivity	(	const Topology &	topology,
		std::pair< std::int8_t, std::int8_t >	d0,
		std::pair< std::int8_t, std::int8_t >	d1 )

Compute connectivity (d0 -> d1) for given pair of entity types, given by topological dimension and index, as found in Topology::entity_types()

Parameters

[in]	topology	The topology
[in]	d0	The dimension and index of the entities
[in]	d1	The dimension and index of the incident entities

Returns

The connectivities [(d0 -> d1), (d1 -> d0)] if they are computed. If (d0, d1) already exists then a nullptr is returned. If (d0, d1) is computed and the computation of (d1, d0) was required as part of computing (d0, d1), the (d1, d0) is returned as the second entry. The second entry is otherwise nullptr.

compute_entities()

std::tuple< std::vector< std::shared_ptr< graph::AdjacencyList< std::int32_t > > >, std::shared_ptr< graph::AdjacencyList< std::int32_t > >, std::shared_ptr< common::IndexMap >, std::vector< std::int32_t > > compute_entities	(	MPI_Comm	comm,
		const Topology &	topology,
		int	dim,
		int	index )

Compute mesh entities of given topological dimension by computing entity-to-vertex connectivity (dim, 0), and cell-to-entity connectivity (tdim, dim).

Computed entities are oriented such that their local (to the process) orientation agrees with their global orientation

Parameters

[in]	comm	MPI Communicator
[in]	topology	Mesh topology
[in]	dim	The dimension of the entities to create
[in]	index	Index of entity in dimension dim as listed in Topology::entity_types(dim).

Returns

Tuple of (cell-entity connectivity, entity-vertex connectivity, index map, list of interprocess entities). Interprocess entities lie on the "true" boundary between owned cells of each process. If the entities already exists, then {nullptr, nullptr, nullptr, std::vector()} is returned.

compute_entity_permutations()

std::pair< std::vector< std::uint8_t >, std::vector< std::uint32_t > > compute_entity_permutations

(

const Topology &

topology

)

Compute (1) facet rotation and reflection data, and (2) cell permutation data. This information is used in the assembly of (1) facet integrals and (2) most non-Lagrange elements.

1. The facet rotation and reflection data is encoded so that:

   • n % 2 gives the number of reflections to apply
   • n // 2 gives the number of rotations to apply

   The data is stored in a flattened 2D array, so that data[cell_index * / facets_per_cell + facet_index] contains the facet with index facet_index of the cell with index cell_index. This data passed to FFCx kernels, where it is used to permute the quadrature points on facet integrals when data from the cells on both sides of the facet is used.

2. The cell permutation data contains information about the entities of each cell, relative to a low-to-high ordering. This data is packed so that a 32-bit int is used for each cell. For 2D cells, one bit is used for each edge, to represent whether or not the edge is reversed: the least significant bit is for edge 0, the next for edge 1, etc. For 3D cells, three bits are used for each face, and for each edge: the least significant bit says whether or not face 0 is reflected, the next 2 bits say how many times face 0 is rotated; the next three bits are for face 1, then three for face 2, etc; after all the faces, there is 1 bit for each edge to say whether or not they are reversed.

   For example, if a quadrilateral has cell permutation info ....0111 then (from right to left):

   • edge 0 is reflected (1)
   • edge 1 is reflected (1)
   • edge 2 is reflected (1)
   • edge 3 is not permuted (0)

   and if a tetrahedron has cell permutation info ....011010010101001000 then (from right to left):

   • face 0 is not permuted (000)
   • face 1 is reflected (001)
   • face 2 is rotated twice then reflected (101)
   • face 3 is rotated once (010)
   • edge 0 is not permuted (0)
   • edge 1 is reflected (1)
   • edge 2 is not permuted (0)
   • edge 3 is reflected (1)
   • edge 4 is reflected (1)
   • edge 5 is not permuted (0)

   This data is used to correct the direction of vector function on permuted facets.

Returns

Facet permutation and cells permutations

compute_incident_entities()

std::vector< std::int32_t > compute_incident_entities	(	const Topology &	topology,
		std::span< const std::int32_t >	entities,
		int	d0,
		int	d1 )

Compute incident indices.

Parameters

[in]	topology	The topology
[in]	entities	List of indices of topological dimension d0
[in]	d0	Topological dimension
[in]	d1	Topological dimension

Returns

List of entities of topological dimension d1 that are incident to entities in entities (topological dimension d0)

compute_midpoints()

template<std::floating_point T>

std::vector< T > compute_midpoints	(	const Mesh< T > &	mesh,
		int	dim,
		std::span< const std::int32_t >	entities )

Compute the midpoints for mesh entities of a given dimension.

Returns

The entity midpoints. The shape is (entities.size(), 3) and the storage is row-major.

create_box() [1/2]

template<std::floating_point T = double>

Mesh< T > create_box	(	MPI_Comm	comm,
		MPI_Comm	subcomm,
		std::array< std::array< T, 3 >, 2 >	p,
		std::array< std::int64_t, 3 >	n,
		CellType	celltype,
		CellPartitionFunction	partitioner = nullptr )

Create a uniform mesh::Mesh over rectangular prism spanned by the two points p.

The order of the two points is not important in terms of minimum and maximum coordinates. The total number of vertices will be (n[0] + / 1)*(n[1] + 1)*(n[2] + 1). For tetrahedra there will be will be 6*n[0]*n[1]*n[2] cells. For hexahedra the number of cells will be n[0]*n[1]*n[2].

Parameters

[in]	comm	MPI communicator to distribute the mesh on.
[in]	subcomm	MPI communicator to construct and partition the mesh topology on. If the process should not be involved in the topology creation and partitioning then this communicator should be MPI_COMM_NULL.
[in]	p	Corner of the box.
[in]	n	Number of cells in each direction.
[in]	celltype	Cell shape.
[in]	partitioner	Partitioning function for distributing cells across MPI ranks.

Returns

Mesh

create_box() [2/2]

template<std::floating_point T = double>

Mesh< T > create_box	(	MPI_Comm	comm,
		std::array< std::array< T, 3 >, 2 >	p,
		std::array< std::int64_t, 3 >	n,
		CellType	celltype,
		const CellPartitionFunction &	partitioner = nullptr )

Create a uniform mesh::Mesh over rectangular prism spanned by the two points p.

The order of the two points is not important in terms of minimum and maximum coordinates. The total number of vertices will be (n[0] + / 1)*(n[1] + 1)*(n[2] + 1). For tetrahedra there will be will be 6*n[0]*n[1]*n[2] cells. For hexahedra the number of cells will be n[0]*n[1]*n[2].

Parameters

[in]	comm	MPI communicator to distribute the mesh on.
[in]	p	Corner of the box.
[in]	n	Number of cells in each direction.
[in]	celltype	Cell shape.
[in]	partitioner	Partitioning function for distributing cells across MPI ranks.

Returns

Mesh

create_cell_partitioner()

mesh::CellPartitionFunction create_cell_partitioner	(	mesh::GhostMode	ghost_mode = mesh::GhostMode::none,
		const graph::partition_fn &	partfn = &graph::partition_graph )

Create a function that computes destination rank for mesh cells in this rank by applying the default graph partitioner to the dual graph of the mesh

Returns

Function that computes the destination ranks for each cell

create_geometry() [1/2]

template<typename U >

Geometry< typename std::remove_reference_t< typename U::value_type > > create_geometry	(	const Topology &	topology,
		const fem::CoordinateElement< std::remove_reference_t< typename U::value_type > > &	element,
		std::span< const std::int64_t >	nodes,
		std::span< const std::int64_t >	xdofs,
		const U &	x,
		int	dim,
		std::function< std::vector< int >(const graph::AdjacencyList< std::int32_t > &)>	reorder_fn = nullptr )

Build Geometry from input data.

This function should be called after the mesh topology is built and 'node' coordinate data has been distributed to the processes where it is required.

Parameters

[in]	topology	Mesh topology.
[in]	element	Element that defines the geometry map for each cell.
[in]	nodes	Geometry node global indices for cells on this process. Must be sorted.
[in]	xdofs	Geometry degree-of-freedom map (using global indices) for cells on this process. nodes is a sorted and unique list of the indices in xdofs.
[in]	x	The node coordinates (row-major, with shape (num_nodes, dim). The global index of each node is i + / rank_offset, where i is the local row index in x and rank_offset is the sum of x rows on all processed with a lower rank than the caller.
[in]	dim	Geometric dimension (1, 2, or 3).
[in]	reorder_fn	Function for re-ordering the degree-of-freedom map associated with the geometry data.

Returns

A mesh geometry.

create_geometry() [2/2]

template<typename U >

Geometry< typename std::remove_reference_t< typename U::value_type > > create_geometry	(	const Topology &	topology,
		const std::vector< fem::CoordinateElement< std::remove_reference_t< typename U::value_type > > > &	elements,
		std::span< const std::int64_t >	nodes,
		std::span< const std::int64_t >	xdofs,
		const U &	x,
		int	dim,
		std::function< std::vector< int >(const graph::AdjacencyList< std::int32_t > &)>	reorder_fn = nullptr )

Build Geometry from input data.

This function should be called after the mesh topology is built and 'node' coordinate data has been distributed to the processes where it is required.

Parameters

[in]	topology	Mesh topology.
[in]	elements	List of elements that defines the geometry map for each cell type.
[in]	nodes	Geometry node global indices for cells on this process.

Precondition

Must be sorted.

Parameters

[in]	xdofs	Geometry degree-of-freedom map (using global indices) for cells on this process. nodes is a sorted and unique list of the indices in xdofs.
[in]	x	The node coordinates (row-major, with shape (num_nodes, dim). The global index of each node is i + / rank_offset, where i is the local row index in x and rank_offset is the sum of x rows on all processed with a lower rank than the caller.
[in]	dim	Geometric dimension (1, 2, or 3).
[in]	reorder_fn	Function for re-ordering the degree-of-freedom map associated with the geometry data.

Note

Experimental new interface for multiple cmap/dofmap

Returns

A mesh geometry.

create_interval()

template<std::floating_point T = double>

Mesh< T > create_interval	(	MPI_Comm	comm,
		std::int64_t	n,
		std::array< T, 2 >	p,
		mesh::GhostMode	ghost_mode = mesh::GhostMode::none,
		CellPartitionFunction	partitioner = nullptr )

Interval mesh of the 1D line [a, b].

Given n cells in the axial direction, the total number of intervals will be n and the total number of vertices will be n + 1.

Parameters

[in]	comm	MPI communicator to build the mesh on.
[in]	n	Number of cells.
[in]	p	End points of the interval.
[in]	ghost_mode	ghost mode of the created mesh, defaults to none
[in]	partitioner	Partitioning function for distributing cells across MPI ranks.

Returns

A mesh.

create_mesh() [1/3]

template<typename U >

Mesh< typename std::remove_reference_t< typename U::value_type > > create_mesh	(	MPI_Comm	comm,
		MPI_Comm	commt,
		const std::vector< std::span< const std::int64_t > > &	cells,
		const std::vector< fem::CoordinateElement< typename std::remove_reference_t< typename U::value_type > > > &	elements,
		MPI_Comm	commg,
		const U &	x,
		std::array< std::size_t, 2 >	xshape,
		const CellPartitionFunction &	partitioner )

Create a distributed mixed-topology mesh from mesh data using a provided graph partitioning function for determining the parallel distribution of the mesh.

From mesh input data that is distributed across processes, a distributed mesh::Mesh is created. If the partitioning function is not callable, i.e. it does not store a callable function, no re-distribution of cells is done.

Note

This is an experimental specialised version of create_mesh for mixed topology meshes, and does not include cell reordering.

Parameters

[in]	comm	Communicator to build the mesh on.
[in]	commt	Communicator that the topology data (cells) is distributed on. This should be MPI_COMM_NULL for ranks that should not participate in computing the topology partitioning.
[in]	cells	Cells on the calling process, as a list of lists, one list for each cell type (or an empty list if there are no cells of that type on this process). The cells are defined by their 'nodes' (using global indices) following the Basix ordering, and concatenated to form a flattened list. For lowest order cells this will be just the cell vertices. For higher-order cells, other cells 'nodes' will be included. See dolfinx::io::cells for examples of the Basix ordering.
[in]	elements	Coordinate elements for the cells, one for each cell type in the mesh. In parallel, these must be the same on all processes.
[in]	commg	Communicator for geometry
[in]	x	Geometry data ('node' coordinates). Row-major storage. The global index of the ith node (row) in x is taken as i plus the process offset oncomm, The offset is the sum of x rows on all processed with a lower rank than the caller.
[in]	xshape	Shape of the x data.
[in]	partitioner	Graph partitioner that computes the owning rank for each cell. If not callable, cells are not redistributed.

Returns

A mesh distributed on the communicator comm.

create_mesh() [2/3]

template<typename U >

Mesh< typename std::remove_reference_t< typename U::value_type > > create_mesh	(	MPI_Comm	comm,
		MPI_Comm	commt,
		std::span< const std::int64_t >	cells,
		const fem::CoordinateElement< typename std::remove_reference_t< typename U::value_type > > &	element,
		MPI_Comm	commg,
		const U &	x,
		std::array< std::size_t, 2 >	xshape,
		const CellPartitionFunction &	partitioner )

Create a distributed mesh from mesh data using a provided graph partitioning function for determining the parallel distribution of the mesh.

From mesh input data that is distributed across processes, a distributed mesh::Mesh is created. If the partitioning function is not callable, i.e. it does not store a callable function, no re-distribution of cells is done.

Parameters

[in]	comm	Communicator to build the mesh on.
[in]	commt	Communicator that the topology data (cells) is distributed on. This should be MPI_COMM_NULL for ranks that should not participate in computing the topology partitioning.
[in]	cells	Cells on the calling process. Each cell (node in the AdjacencyList) is defined by its 'nodes' (using global indices) following the Basix ordering. For lowest order cells this will be just the cell vertices. For higher-order cells, other cells 'nodes' will be included. See dolfinx::io::cells for examples of the Basix ordering.
[in]	element	Coordinate element for the cells.
[in]	commg	Communicator for geometry
[in]	x	Geometry data ('node' coordinates). Row-major storage. The global index of the ith node (row) in x is taken as i plus the process offset oncomm, The offset is the sum of x rows on all processed with a lower rank than the caller.
[in]	xshape	Shape of the x data.
[in]	partitioner	Graph partitioner that computes the owning rank for each cell. If not callable, cells are not redistributed.

Returns

A mesh distributed on the communicator comm.

create_mesh() [3/3]

template<typename U >

Mesh< typename std::remove_reference_t< typename U::value_type > > create_mesh	(	MPI_Comm	comm,
		std::span< const std::int64_t >	cells,
		const fem::CoordinateElement< std::remove_reference_t< typename U::value_type > > &	elements,
		const U &	x,
		std::array< std::size_t, 2 >	xshape,
		GhostMode	ghost_mode )

Create a distributed mesh from mesh data using the default graph partitioner to determine the parallel distribution of the mesh.

This function takes mesh input data that is distributed across processes and creates a mesh::Mesh, with the mesh cell distribution determined by the default cell partitioner. The default partitioner is based on graph partitioning.

Parameters

[in]	comm	MPI communicator to build the mesh on.
[in]	cells	Cells on the calling process. See create_mesh for a detailed description.
[in]	elements	Coordinate elements for the cells.
[in]	x	Geometry data ('node' coordinates). See create_mesh for a detailed description.
[in]	xshape	The shape of x. It should be (num_points, gdim).
[in]	ghost_mode	The requested type of cell ghosting/overlap

Returns

A mesh distributed on the communicator comm.

create_meshtags()

template<typename T >

MeshTags< T > create_meshtags	(	std::shared_ptr< const Topology >	topology,
		int	dim,
		const graph::AdjacencyList< std::int32_t > &	entities,
		std::span< const T >	values )

Create MeshTags from arrays.

Parameters

[in]	topology	Mesh topology that the tags are associated with.
[in]	dim	Topological dimension of tagged entities.
[in]	entities	Local vertex indices for tagged entities.
[in]	values	Tag values for each entity in entities. The length of values must be equal to number of rows in entities.

Note

Entities that do not exist on this rank are ignored.

Warning

entities must not contain duplicate entities.

create_rectangle() [1/2]

template<std::floating_point T = double>

Mesh< T > create_rectangle	(	MPI_Comm	comm,
		std::array< std::array< T, 2 >, 2 >	p,
		std::array< std::int64_t, 2 >	n,
		CellType	celltype,
		CellPartitionFunction	partitioner,
		DiagonalType	diagonal = DiagonalType::right )

Create a uniform mesh::Mesh over the rectangle spanned by the two points p.

The order of the two points is not important in terms of minimum and maximum coordinates. The total number of vertices will be (n[0] + / 1)*(n[1] + 1). For triangles there will be will be 2*n[0]*n[1] cells. For quadrilaterals the number of cells will be n[0]*n[1].

Parameters

[in]	comm	MPI communicator to build the mesh on.
[in]	p	Bottom-left and top-right corners of the rectangle.
[in]	n	Number of cells in each direction.
[in]	celltype	Cell shape.
[in]	partitioner	Partitioning function for distributing cells across MPI ranks.
[in]	diagonal	Direction of diagonals

Returns

Mesh

create_rectangle() [2/2]

template<std::floating_point T = double>

Mesh< T > create_rectangle	(	MPI_Comm	comm,
		std::array< std::array< T, 2 >, 2 >	p,
		std::array< std::int64_t, 2 >	n,
		CellType	celltype,
		DiagonalType	diagonal = DiagonalType::right )

Create a uniform mesh::Mesh over the rectangle spanned by the two points p.

The order of the two points is not important in terms of minimum and maximum coordinates. The total number of vertices will be (n[0] + / 1)*(n[1] + 1). For triangles there will be will be 2*n[0]*n[1] cells. For quadrilaterals the number of cells will be n[0]*n[1].

Parameters

[in]	comm	MPI communicator to build the mesh on
[in]	p	Two corner points
[in]	n	Number of cells in each direction
[in]	celltype	Cell shape
[in]	diagonal	Direction of diagonals

Returns

Mesh

create_subgeometry()

template<std::floating_point T>

std::pair< Geometry< T >, std::vector< int32_t > > create_subgeometry	(	const Mesh< T > &	mesh,
		int	dim,
		std::span< const std::int32_t >	subentity_to_entity )

Create a sub-geometry from a mesh and a subset of mesh entities to be included. A sub-geometry is simply a Geometry object containing only the geometric information for the subset of entities. The entities may differ in topological dimension from the original mesh.

Parameters

[in]	mesh	The full mesh.
[in]	dim	Topological dimension of the sub-topology.
[in]	subentity_to_entity	Map from sub-topology entity to the entity in the parent topology.

Returns

A sub-geometry and a map from sub-geometry coordinate degree-of-freedom to the coordinate degree-of-freedom in geometry.

create_submesh()

template<std::floating_point T>

std::tuple< Mesh< T >, std::vector< std::int32_t >, std::vector< std::int32_t >, std::vector< std::int32_t > > create_submesh	(	const Mesh< T > &	mesh,
		int	dim,
		std::span< const std::int32_t >	entities )

Create a new mesh consisting of a subset of entities in a mesh.

Parameters

[in]	mesh	The mesh
[in]	dim	Entity dimension
[in]	entities	List of entity indices in mesh to include in the new mesh

Returns

The new mesh, and maps from the new mesh entities, vertices, and geometry to the input mesh entities, vertices, and geometry.

create_subtopology()

std::tuple< Topology, std::vector< int32_t >, std::vector< int32_t > > create_subtopology	(	const Topology &	topology,
		int	dim,
		std::span< const std::int32_t >	entities )

Create a topology for a subset of entities of a given topological dimension.

Parameters

topology	Original (parent) topology.
dim	Topological dimension of the entities in the new topology.
entities	Indices of entities in topology to include in the new topology.

Returns

New topology of dimension dim with all entities in entities, map from entities of dimension dim in new sub-topology to entities in topology, and map from vertices in new sub-topology to vertices in topology.

create_topology() [1/2]

Topology create_topology	(	MPI_Comm	comm,
		const std::vector< CellType > &	cell_type,
		std::vector< std::span< const std::int64_t > >	cells,
		std::vector< std::span< const std::int64_t > >	original_cell_index,
		std::vector< std::span< const int > >	ghost_owners,
		std::span< const std::int64_t >	boundary_vertices )

Create a topology of mixed cell type.

Parameters

comm	MPI Communicator
cell_type	List of cell types
cells	Lists of cells, using vertex indices, flattened, for each cell type.
original_cell_index	Input cell index for each cell type
ghost_owners	Owning rank for ghost cells (at end of each list of cells).
boundary_vertices	Vertices of undetermined ownership on external or inter-process boundary.

Returns

create_topology() [2/2]

Topology create_topology	(	MPI_Comm	comm,
		std::span< const std::int64_t >	cells,
		std::span< const std::int64_t >	original_cell_index,
		std::span< const int >	ghost_owners,
		CellType	cell_type,
		std::span< const std::int64_t >	boundary_vertices )

Create a mesh topology.

This function creates a Topology from cells that have been distributed to the processes that own or ghost the cell.

Parameters

[in]	comm	Communicator across which the topology is distributed.
[in]	cells	Cell topology (list of vertices for each cell) using global indices for the vertices. It contains cells that have been distributed to this rank, e.g. via a graph partitioner. It must also contain all ghost cells via facet, i.e. cells that are on a neighboring process and which share a facet with a local cell. Ghost cells are the last n entries in cells, where n is given by the length of ghost_owners.
[in]	original_cell_index	Original global index associated with each cell.
[in]	ghost_owners	Owning rank of each ghost cell (ghost cells are always at the end of the list of cells).
[in]	cell_type	A vector with cell shapes.
[in]	boundary_vertices	Vertices on the 'exterior' (boundary) of the local topology. These vertices might appear on other processes.

Returns

A distributed mesh topology

entities_to_geometry()

template<std::floating_point T>

std::vector< std::int32_t > entities_to_geometry	(	const Mesh< T > &	mesh,
		int	dim,
		std::span< const std::int32_t >	entities,
		bool	permute = false )

Compute the geometry degrees of freedom associated with the closure of a given set of cell entities.

Parameters

[in]	mesh	The mesh.
[in]	dim	Topological dimension of the entities of interest.
[in]	entities	Entity indices (local to process).
[in]	permute	If true, permute the DOFs such that they are consistent with the orientation of dim-dimensional mesh entities. This requires create_entity_permutations to be called first.

Returns

The geometry DOFs associated with the closure of each entity in entities. The shape is (num_entities, num_xdofs_per_entity) and the storage is row-major. The index indices[i, j] is the position in the geometry array of the j-th vertex of the entity[i].

Precondition

The mesh connectivities dim -> mesh.topology().dim() and mesh.topology().dim() -> dim must have been computed. Otherwise an exception is thrown.

entities_to_index()

std::vector< std::int32_t > entities_to_index	(	const Topology &	topology,
		int	dim,
		std::span< const std::int32_t >	entities )

Get entity indices for entities defined by their vertices.

Warning

This function may be removed in the future.

Parameters

[in]	topology	The mesh topology
[in]	dim	Topological dimension of the entities
[in]	entities	The mesh entities defined by their vertices

Returns

The index of the ith entity in entities

Note

If an entity cannot be found on this rank, -1 is returned as the index.

exterior_facet_indices()

std::vector< std::int32_t > exterior_facet_indices

(

const Topology &

topology

)

Compute the indices of all exterior facets that are owned by the caller.

An exterior facet (co-dimension 1) is one that is connected globally to only one cell of co-dimension 0).

Note

Collective

Parameters

[in]

topology

Mesh topology

Returns

Sorted list of owned facet indices that are exterior facets of the mesh.

extract_topology()

std::vector< std::int64_t > extract_topology	(	CellType	cell_type,
		const fem::ElementDofLayout &	layout,
		std::span< const std::int64_t >	cells )

Extract topology from cell data, i.e. extract cell vertices.

Parameters

[in]	cell_type	The cell shape
[in]	layout	The layout of geometry 'degrees-of-freedom' on the reference cell
[in]	cells	List of 'nodes' for each cell using global indices. The layout must be consistent with layout.

Returns

Cell topology. The global indices will, in general, have 'gaps' due to mid-side and other higher-order nodes being removed from the input cell.

get_entity_vertices()

graph::AdjacencyList< int > get_entity_vertices	(	CellType	type,
		int	dim )

Return list of entities, where entities(e, k) is the local vertex index for the kth vertex of entity e of dimension dim

get_sub_entities()

graph::AdjacencyList< int > get_sub_entities	(	CellType	type,
		int	dim0,
		int	dim1 )

Get entities of dimension dim1 and that make up entities of dimension dim0

h()

template<std::floating_point T>

std::vector< T > h	(	const Mesh< T > &	mesh,
		std::span< const std::int32_t >	entities,
		int	dim )

Compute greatest distance between any two vertices of the mesh entities (h).

Parameters

[in]	mesh	Mesh that the entities belong to.
[in]	entities	Indices (local to process) of entities to compute h for.
[in]	dim	Topological dimension of the entities.

Returns

Greatest distance between any two vertices, h[i] corresponds to the entity entities[i].

is_simplex()

bool is_simplex

(

CellType

type

)

Check if cell is a simplex

Parameters

[in]

type

Cell type

Returns

True is the cell type is a simplex

locate_entities()

template<std::floating_point T, MarkerFn< T > U>

std::vector< std::int32_t > locate_entities	(	const Mesh< T > &	mesh,
		int	dim,
		U	marker )

Compute indices of all mesh entities that evaluate to true for the provided geometric marking function.

An entity is considered marked if the marker function evaluates to true for all of its vertices.

Parameters

[in]	mesh	Mesh to mark entities on.
[in]	dim	Topological dimension of the entities to be considered.
[in]	marker	Marking function, returns true for a point that is 'marked', and false otherwise.

Returns

List of marked entity indices, including any ghost indices (indices local to the process)

locate_entities_boundary()

template<std::floating_point T, MarkerFn< T > U>

std::vector< std::int32_t > locate_entities_boundary	(	const Mesh< T > &	mesh,
		int	dim,
		U	marker )

Compute indices of all mesh entities that are attached to an owned boundary facet and evaluate to true for the provided geometric marking function.

An entity is considered marked if the marker function evaluates to true for all of its vertices.

Note

For vertices and edges, in parallel this function will not necessarily mark all entities that are on the exterior boundary. For example, it is possible for a process to have a vertex that lies on the boundary without any of the attached facets being a boundary facet. When used to find degrees-of-freedom, e.g. using fem::locate_dofs_topological, the function that uses the data returned by this function must typically perform some parallel communication.

Parameters

[in]	mesh	Mesh to mark entities on.
[in]	dim	Topological dimension of the entities to be considered. Must be less than the topological dimension of the mesh.
[in]	marker	Marking function, returns true for a point that is 'marked', and false otherwise.

Returns

List of marked entity indices (indices local to the process)

num_cell_vertices()

int num_cell_vertices

(

CellType

type

)

Number vertices for a cell type

Parameters

[in]

type

Cell type

Returns

The number of cell vertices

to_string()

std::string to_string

(

CellType

type

)

Get the cell string type for a cell type

Parameters

[in]

type

The cell type

Returns

The cell type string

to_type()

mesh::CellType to_type

(

const std::string &

cell

)

Get the cell type from a cell string

Parameters

[in]

cell

Cell shape string

Returns

The cell type