Mesh (dolfinx::mesh
)
Under development

namespace mesh
Mesh data structures and algorithms on meshes.
Representations of meshes and support for operations on meshes.
Typedefs

using CellPartitionFunction = 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.
Note
Cells can have multiple destination ranks, when ghosted.
 Param comm:
[in] MPI Communicator
 Param nparts:
[in] Number of partitions
 Param cell_types:
[in] Cell types in the mesh
 Param cells:
[in] 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. Highorder ‘nodes’, e.g. midside points, should not be included.
 Return:
Destination ranks for each cell on this process
Enums

enum class CellType : int
Cell type identifier.
Values:

enumerator point

enumerator interval

enumerator triangle

enumerator tetrahedron

enumerator quadrilateral

enumerator pyramid

enumerator prism

enumerator hexahedron

enumerator point
Functions

std::string to_string(CellType type)
Get the cell string type for a cell type
 Parameters:
type – [in] The cell type
 Returns:
The cell type string

CellType to_type(const std::string &cell)
Get the cell type from a cell string
 Parameters:
cell – [in] Cell shape string
 Returns:
The cell type

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)
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:
type – [in] The cell type
index – [in] The facet index
 Returns:
The type of facet for this cell at this index

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

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

int cell_num_entities(CellType type, int dim)
Number of entities of dimension dim
 Parameters:
dim – [in] Entity dimension
type – [in] Cell type
 Returns:
Number of entities in cell

bool is_simplex(CellType type)
Check if cell is a simplex
 Parameters:
type – [in] Cell type
 Returns:
True is the cell type is a simplex

int num_cell_vertices(CellType type)
Number vertices for a cell type
 Parameters:
type – [in] Cell type
 Returns:
The number of cell vertices

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 lowerdimensional entities attached to a cell entity. Map from entity {dim_e, entity_e} to closure{sub_dim, (sub_entities)}

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
.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 be6*n[0]*n[1]*n[2]
cells. For hexahedra the number of cells will ben[0]*n[1]*n[2]
. Parameters:
comm – [in] MPI communicator to distribute the mesh on.
subcomm – [in] 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
.p – [in] Corner of the box.
n – [in] Number of cells in each direction.
celltype – [in] Cell shape.
partitioner – [in] Partitioning function for distributing cells across MPI ranks.
 Returns:

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 be6*n[0]*n[1]*n[2]
cells. For hexahedra the number of cells will ben[0]*n[1]*n[2]
. Parameters:
comm – [in] MPI communicator to distribute the mesh on.
p – [in] Corner of the box.
n – [in] Number of cells in each direction.
celltype – [in] Cell shape.
partitioner – [in] Partitioning function for distributing cells across MPI ranks.
 Returns:

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 be2*n[0]*n[1]
cells. For quadrilaterals the number of cells will ben[0]*n[1]
. Parameters:
comm – [in] MPI communicator to build the mesh on.
p – [in] Bottomleft and topright corners of the rectangle.
n – [in] Number of cells in each direction.
celltype – [in] Cell shape.
partitioner – [in] Partitioning function for distributing cells across MPI ranks.
diagonal – [in] Direction of diagonals
 Returns:

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 be2*n[0]*n[1]
cells. For quadrilaterals the number of cells will ben[0]*n[1]
. Parameters:
comm – [in] MPI communicator to build the mesh on
p – [in] Two corner points
n – [in] Number of cells in each direction
celltype – [in] Cell shape
diagonal – [in] Direction of diagonals
 Returns:

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 ben
and the total number of vertices will ben + 1
. Parameters:
comm – [in] MPI communicator to build the mesh on.
n – [in] Number of cells.
p – [in] End points of the interval.
ghost_mode – [in] ghost mode of the created mesh, defaults to none
partitioner – [in] Partitioning function for distributing cells across MPI ranks.
 Returns:
A mesh.

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.
Note
Experimental new interface for multiple cmap/dofmap
 Parameters:
topology – [in] Mesh topology.
elements – [in] List of elements that defines the geometry map for each cell type.
nodes – [in] Geometry node global indices for cells on this process.
xdofs – [in] Geometry degreeoffreedom map (using global indices) for cells on this process.
nodes
is a sorted and unique list of the indices inxdofs
.x – [in] The node coordinates (rowmajor, with shape
(num_nodes, dim)
. The global index of each node isi + / rank_offset
, wherei
is the local row index inx
andrank_offset
is the sum ofx
rows on all processed with a lower rank than the caller.dim – [in] Geometric dimension (1, 2, or 3).
reorder_fn – [in] Function for reordering the degreeoffreedom map associated with the geometry data.
 Pre:
Must be sorted.
 Returns:
A mesh geometry.

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:
topology – [in] Mesh topology.
element – [in] Element that defines the geometry map for each cell.
nodes – [in] Geometry node global indices for cells on this process. Must be sorted.
xdofs – [in] Geometry degreeoffreedom map (using global indices) for cells on this process.
nodes
is a sorted and unique list of the indices inxdofs
.x – [in] The node coordinates (rowmajor, with shape
(num_nodes, dim)
. The global index of each node isi + / rank_offset
, wherei
is the local row index inx
andrank_offset
is the sum ofx
rows on all processed with a lower rank than the caller.dim – [in] Geometric dimension (1, 2, or 3).
reorder_fn – [in] Function for reordering the degreeoffreedom map associated with the geometry data.
 Returns:
A mesh geometry.

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 (cellcell connections via facets) and facets with only one attached cell.
Each row of the returned data (2) contains
[v0, ... v_(n1), x, .., / x]
, wherev_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 type0
andm
cells of type1
, then cells of type0
are numbered0..(n1)
and cells of type1
are numberedn..(n+m1)
respectively, in the returned dual graph. Parameters:
celltypes – [in] List of cell types.
cells – [in] Lists of cell vertices (stored as flattened lists, one for each cell type).
 Returns:
Local dual graph
Facets, defined by their vertices, that are shared by only one cell on this rank. The logically 2D array is flattened (rowmajor).
The number of columns for the facet data array (2).
The attached cell (local index) to each returned facet in (2).

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 (cellcell connections via facets) from minimal mesh data.
The computed dual graph is typically passed to a graph partitioner.
Note
Collective function
Note
cells
andcelltypes
must have the same size. Parameters:
comm – [in] The MPI communicator
celltypes – [in] List of cell types
cells – [in] Collections of cells, defined by the cell vertices from which to build the dual graph, as flattened arrays for each cell type in
celltypes
.
 Returns:
The dual graph
Create MeshTags from arrays.
Note
Entities that do not exist on this rank are ignored.
Warning
entities
must not contain duplicate entities. Parameters:
topology – [in] Mesh topology that the tags are associated with.
dim – [in] Topological dimension of tagged entities.
entities – [in] Local vertex indices for tagged entities.
values – [in] Tag values for each entity in
entities
. The length ofvalues
must be equal to number of rows inentities
.

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 nonLagrange elements.
The facet rotation and reflection data is encoded so that:
n % 2
gives the number of reflections to applyn // 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 indexfacet_index
of the cell with indexcell_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.The cell permutation data contains information about the entities of each cell, relative to a lowtohigh ordering. This data is packed so that a 32bit 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

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:
comm – [in] Communicator across which the topology is distributed.
cells – [in] 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 incells
, wheren
is given by the length ofghost_owners
.original_cell_index – [in] Original global index associated with each cell.
ghost_owners – [in] Owning rank of each ghost cell (ghost cells are always at the end of the list of
cells
).cell_type – [in] A vector with cell shapes.
boundary_vertices – [in] Vertices on the ‘exterior’ (boundary) of the local topology. These vertices might appear on other processes.
 Returns:
A distributed 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.
 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 interprocess boundary.
 Returns:

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 inentities
, map from entities of dimensiondim
in new subtopology to entities intopology
, and map from vertices in new subtopology to vertices intopology
.

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.
Note
If an entity cannot be found on this rank, 1 is returned as the index.
Warning
This function may be removed in the future.
 Parameters:
topology – [in] The mesh topology
dim – [in] Topological dimension of the entities
entities – [in] The mesh entities defined by their vertices
 Returns:
The index of the ith entity in
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 entitytovertex connectivity
(dim, 0)
, and celltoentity connectivity(tdim, dim)
.Computed entities are oriented such that their local (to the process) orientation agrees with their global orientation
 Parameters:
comm – [in] MPI Communicator
topology – [in] Mesh topology
dim – [in] The dimension of the entities to create
index – [in] Index of entity in dimension
dim
as listed inTopology::entity_types(dim)
.
 Returns:
Tuple of (cellentity connectivity, entityvertex 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.

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:
topology – [in] The topology
d0 – [in] The dimension and index of the entities
d1 – [in] 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.

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 (codimension 1) is one that is connected globally to only one cell of codimension 0).
Note
Collective
 Parameters:
topology – [in] Mesh topology
 Returns:
Sorted list of owned facet indices that are exterior facets of the mesh.

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:
cell_type – [in] The cell shape
layout – [in] The layout of geometry ‘degreesoffreedom’ on the reference cell
cells – [in] 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 midside and other higherorder nodes being removed from the input
cell
.

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:
mesh – [in] Mesh that the entities belong to.
entities – [in] Indices (local to process) of entities to compute
h
for.dim – [in] Topological dimension of the entities.
 Returns:
Greatest distance between any two vertices,
h[i]
corresponds to the entityentities[i]
.

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 rowmajor.

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 rowmajor.

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:
mesh – [in] Mesh to mark entities on.
dim – [in] Topological dimension of the entities to be considered.
marker – [in] Marking function, returns
true
for a point that is ‘marked’, andfalse
otherwise.
 Returns:
List of marked entity indices, including any ghost indices (indices local to the process)

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 degreesoffreedom, e.g. using fem::locate_dofs_topological, the function that uses the data returned by this function must typically perform some parallel communication.
 Parameters:
mesh – [in] Mesh to mark entities on.
dim – [in] Topological dimension of the entities to be considered. Must be less than the topological dimension of the mesh.
marker – [in] Marking function, returns
true
for a point that is ‘marked’, andfalse
otherwise.
 Returns:
List of marked entity indices (indices local to the process)

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:
mesh – [in] The mesh.
dim – [in] Topological dimension of the entities of interest.
entities – [in] Entity indices (local to process).
permute – [in] If
true
, permute the DOFs such that they are consistent with the orientation ofdim
dimensional mesh entities. This requirescreate_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 rowmajor. The indexindices[i, j]
is the position in the geometry array of thej
th vertex of theentity[i]
. Pre:
The mesh connectivities
dim > mesh.topology().dim()
andmesh.topology().dim() > dim
must have been computed. Otherwise an exception is thrown.

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

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:
topology – [in] The topology
entities – [in] List of indices of topological dimension
d0
d0 – [in] Topological dimension
d1 – [in] Topological dimension
 Returns:
List of entities of topological dimension
d1
that are incident to entities inentities
(topological dimensiond0
)

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 redistribution of cells is done.
 Parameters:
comm – [in] Communicator to build the mesh on.
commt – [in] Communicator that the topology data (
cells
) is distributed on. This should beMPI_COMM_NULL
for ranks that should not participate in computing the topology partitioning.cells – [in] 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 higherorder cells, other cells ‘nodes’ will be included. See dolfinx::io::cells for examples of the Basix ordering.element – [in] Coordinate element for the cells.
commg – [in] Communicator for geometry
x – [in] Geometry data (‘node’ coordinates). Rowmajor storage. The global index of the
i
th node (row) inx
is taken asi
plus the process offset oncomm
, The offset is the sum ofx
rows on all processed with a lower rank than the caller.xshape – [in] Shape of the
x
data.partitioner – [in] 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
.

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 mixedtopology 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 redistribution 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:
comm – [in] Communicator to build the mesh on.
commt – [in] Communicator that the topology data (
cells
) is distributed on. This should beMPI_COMM_NULL
for ranks that should not participate in computing the topology partitioning.cells – [in] 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 higherorder cells, other cells ‘nodes’ will be included. See dolfinx::io::cells for examples of the Basix ordering.
elements – [in] Coordinate elements for the cells, one for each cell type in the mesh. In parallel, these must be the same on all processes.
commg – [in] Communicator for geometry
x – [in] Geometry data (‘node’ coordinates). Rowmajor storage. The global index of the
i
th node (row) inx
is taken asi
plus the process offset oncomm
, The offset is the sum ofx
rows on all processed with a lower rank than the caller.xshape – [in] Shape of the
x
data.partitioner – [in] 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
.

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:
comm – [in] MPI communicator to build the mesh on.
cells – [in] Cells on the calling process. See create_mesh for a detailed description.
elements – [in] Coordinate elements for the cells.
x – [in] Geometry data (‘node’ coordinates). See create_mesh for a detailed description.
xshape – [in] The shape of
x
. It should be(num_points, gdim)
.ghost_mode – [in] The requested type of cell ghosting/overlap
 Returns:
A mesh distributed on the communicator
comm
.

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 subgeometry from a mesh and a subset of mesh entities to be included. A subgeometry 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:
mesh – [in] The full mesh.
dim – [in] Topological dimension of the subtopology.
subentity_to_entity – [in] Map from subtopology entity to the entity in the parent topology.
 Returns:
A subgeometry and a map from subgeometry coordinate degreeoffreedom to the coordinate degreeoffreedom in
geometry
.

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:
mesh – [in] The mesh
dim – [in] Entity dimension
entities – [in] 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.

template<std::floating_point T>
class Geometry  #include <Geometry.h>
Geometry stores the geometry imposed on a mesh.
Public Functions
Constructor of object that holds mesh geometry data.
 Parameters:
index_map – [in] Index map associated with the geometry dofmap
dofmap – [in] The geometry (point) dofmap. For a cell, it gives the position in the point array of each local geometry node
element – [in] Element that describes the cell geometry map.
x – [in] The point coordinates. The shape is
(num_points, 3)
and the storage is rowmajor.dim – [in] The geometric dimension (
0 < dim <= 3
).input_global_indices – [in] The ‘global’ input index of each point, commonly from a mesh input file.
Constructor of object that holds mesh geometry data.
 Parameters:
index_map – [in] Index map associated with the geometry dofmap
dofmaps – [in] The geometry (point) dofmaps. For a cell, it gives the position in the point array of each local geometry node
elements – [in] Elements that describes the cell geometry maps.
x – [in] The point coordinates. The shape is
(num_points, 3)
and the storage is rowmajor.dim – [in] The geometric dimension (
0 < dim <= 3
).input_global_indices – [in] The ‘global’ input index of each point, commonly from a mesh input file.

~Geometry() = default
Destructor.

inline int dim() const
Return dimension of the Euclidean coordinate system.

inline MDSPAN_IMPL_STANDARD_NAMESPACE::mdspan<const std::int32_t, MDSPAN_IMPL_STANDARD_NAMESPACE::dextents<std::size_t, 2>> dofmap() const
DofMap for the geometry.
 Returns:
A 2D array with shape [num_cells, dofs_per_cell]

inline MDSPAN_IMPL_STANDARD_NAMESPACE::mdspan<const std::int32_t, MDSPAN_IMPL_STANDARD_NAMESPACE::dextents<std::size_t, 2>> dofmap(std::int32_t i) const
The dofmap associated with the
i
th coordinate map in the geometry. Parameters:
i – Index
 Returns:
A 2D array with shape [num_cells, dofs_per_cell]

inline std::shared_ptr<const common::IndexMap> index_map() const
Index map.
 Returns:
The index map for the geometry dofs

inline std::span<const value_type> x() const
Access geometry degreesoffreedom data (const version).
 Returns:
The flattened rowmajor geometry data, where the shape is (num_points, 3)

inline std::span<value_type> x()
Access geometry degreesoffreedom data (nonconst version).
 Returns:
The flattened rowmajor geometry data, where the shape is (num_points, 3)

inline const fem::CoordinateElement<value_type> &cmap() const
The element that describes the geometry map.
 Returns:
The coordinate/geometry element

inline const fem::CoordinateElement<value_type> &cmap(std::int32_t i) const
The element that describe the
i
th geometry map. Parameters:
i – Index of the coordinate element
 Returns:
Coordinate element

inline const std::vector<std::int64_t> &input_global_indices() const
Global user indices.

template<std::floating_point T>
class Mesh  #include <Mesh.h>
A Mesh consists of a set of connected and numbered mesh topological entities, and geometry data.
 Template Parameters:
The – floating point type for representing the geometry.
Public Functions
Create a mesh.

~Mesh() = default
Destructor.

Mesh &operator=(Mesh &&mesh) = default
Assignment move operator
 Parameters:
mesh – Another Mesh object

inline std::shared_ptr<Topology> topology()
Get mesh topology.
 Returns:
The topology object associated with the mesh.

inline std::shared_ptr<const Topology> topology() const
Get mesh topology (const version)
 Returns:
The topology object associated with the mesh.

inline std::shared_ptr<Topology> topology_mutable() const
Get mesh topology if one really needs the mutable version
 Returns:
The topology object associated with the mesh.

inline Geometry<T> &geometry()
Get mesh geometry.
 Returns:
The geometry object associated with the mesh
Public Members

std::string name = "mesh"
Name.

template<typename T>
class MeshTags  #include <MeshTags.h>
MeshTags associate values with mesh topology entities.
The entity index (local to process) identifies the entity. MeshTags is a sparse data storage class; it allows tags to be associated with an arbitrary subset of mesh entities. An entity can have only one associated tag.
 Template Parameters:
Type –
Public Functions
Create a MeshTag from entities of given dimension on a mesh.
 Parameters:
topology – [in] Mesh topology on which the tags are associated.
dim – [in] Topological dimension of mesh entities to tag.
indices – [in] List of entity indices (indices local to the process).
values – [in] List of values for each index in indices. The size must be equal to the size of
indices
.
 Pre:
indices
must be sorted and unique.

~MeshTags() = default
Destructor.

inline std::vector<std::int32_t> find(const T value) const
Find all entities with a given tag value.
 Parameters:
value – [in] The value
 Returns:
Indices of tagged entities. The indices are sorted.

inline std::span<const std::int32_t> indices() const
Indices of tagged topology entities (localtoprocess). The indices are sorted.

inline int dim() const
Return topological dimension of tagged entities.
Public Members

std::string name = "mesh_tags"
Name.

class Topology
 #include <Topology.h>
Topology stores the topology of a mesh, consisting of mesh entities and connectivity (incidence relations for the mesh entities).
A mesh entity e may be identified globally as a pair
e = (dim, i)
, where dim is the topological dimension and i is the index of the entity within that topological dimension. Todo:
Rework memory management and associated API. Currently, there is no clear caching policy implemented and no way of discarding cached data.
Public Functions

Topology(MPI_Comm comm, CellType cell_type)
Empty Topology constructor.
 Parameters:
comm – MPI communicator
cell_type – Type of cell

Topology(MPI_Comm comm, const std::vector<CellType> &cell_type)
Create empty mesh topology with multiple cell types.
Warning
Experimental
 Parameters:
comm – MPI communicator
cell_type – List of cell types

~Topology() = default
Destructor.

int dim() const noexcept
Return the topological dimension of the mesh.
Set the IndexMap for dimension dim.
 Todo:
Merge with set_connectivity
Warning
This is experimental and likely to change
Set the IndexMap for the
i
th celltype of dimension dim. Todo:
Merge with set_connectivity
Warning
This is experimental and likely to change
 Parameters:
dim – Topological dimension
i – Index of cell type within dimension
dim
. Cell types for each dimension can be obtained withentity_types(dim)
.map – Map to set

std::shared_ptr<const common::IndexMap> index_map(int dim) const
Get the IndexMap that described the parallel distribution of the mesh entities.
 Parameters:
dim – [in] Topological dimension
 Returns:
Index map for the entities of dimension
dim
. Returnsnullptr
if index map has not been set.

std::vector<std::shared_ptr<const common::IndexMap>> index_maps(std::int8_t dim) const
Warning
Experimental
 Parameters:
dim – Topological dimension
 Returns:
List of index maps, one for each cell type

std::shared_ptr<const graph::AdjacencyList<std::int32_t>> connectivity(int d0, int d1) const
Return connectivity from entities of dimension d0 to entities of dimension d1. Assumes only one entity type per dimension.
 Parameters:
d0 – [in]
d1 – [in]
 Returns:
The adjacency list that for each entity of dimension d0 gives the list of incident entities of dimension d1. Returns
nullptr
if connectivity has not been computed.

std::shared_ptr<const graph::AdjacencyList<std::int32_t>> connectivity(std::pair<std::int8_t, std::int8_t> d0, std::pair<std::int8_t, std::int8_t> d1) const
Return the connectivity from entities of topological dimension d0 to dimension d1. The entity type, and incident entity type are each described by a pair (dim, index). The index within a topological dimension
dim
, is that of the cell type given inentity_types(dim)
. Parameters:
d0 – Pair of (topological dimension of entities, index of “entity type” within topological dimension)
d1 – Pair of (topological dimension of indicent entities, index of incident “entity type” within topological dimension)
 Returns:
AdjacencyList of connectivity from entity type in d0 to entity types in d1, or nullptr if not yet computed.
Set connectivity for given pair of topological dimensions.
 Todo:
Merge with set_index_map
Set connectivity for given pair of entity types, defined by dimension and index, as listed in
entity_types()
. General version for mixed topology. Connectivity from d0 to d1.Warning
Experimental
 Parameters:
c – Connectivity AdjacencyList
d0 – Pair of (topological dimension of entities, index of “entity type” within topological dimension)
d1 – Pair of (topological dimension of indicent entities, index of incident “entity type” within topological dimension)

const std::vector<std::uint32_t> &get_cell_permutation_info() const
Returns the permutation information.

const std::vector<std::uint8_t> &get_facet_permutations() const
Get the numbers that encode the number of permutations to apply to facets.
The permutations are encoded so that:
n % 2
gives the number of reflections to applyn // 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 indexfacet_index
of the cell with indexcell_index
.Note
An exception is raised if the permutations have not been computed
 Returns:
The encoded permutation info

std::vector<CellType> entity_types(std::int8_t dim) const
Get the entity types in the topology for a given dimension.
 Parameters:
dim – Topological dimension
 Returns:
List of entity types

std::int32_t create_entities(int dim)
Create entities of given topological dimension.
 Parameters:
dim – [in] Topological dimension
 Returns:
Number of newly created entities, returns 1 if entities already existed

void create_connectivity(int d0, int d1)
Create connectivity between given pair of dimensions,
d0 / > d1
. Parameters:
d0 – [in] Topological dimension
d1 – [in] Topological dimension

void create_entity_permutations()
Compute entity permutations and reflections.

const std::vector<std::int32_t> &interprocess_facets() const
List of interprocess facets.
“Interprocess” facets are facets that are connected (1) to a cell that is owned by the calling process (rank) and (2) to a cell that is owned by another process.
 Pre:
Interprocess facets are available only if facet topology has been computed.

const std::vector<std::int32_t> &interprocess_facets(std::int8_t index) const
List of interprocess facets, if facet topology has been computed, for the facet type in
Topology::entity_types
identified by index. Parameters:
index – Index of facet type
Public Members

std::vector<std::vector<std::int64_t>> original_cell_index
Original cell index for each cell type.

namespace impl
Functions

template<std::floating_point T>
std::tuple<std::vector<T>, std::vector<std::int64_t>> create_interval_cells(std::array<T, 2> p, std::int64_t n)

template<std::floating_point T>
Mesh<T> build_tri(MPI_Comm comm, std::array<std::array<T, 2>, 2> p, std::array<std::int64_t, 2> n, const CellPartitionFunction &partitioner, DiagonalType diagonal)

template<std::floating_point T>
Mesh<T> build_quad(MPI_Comm comm, const std::array<std::array<T, 2>, 2> p, std::array<std::int64_t, 2> n, const CellPartitionFunction &partitioner)

template<std::floating_point T>
std::vector<T> create_geom(MPI_Comm comm, std::array<std::array<T, 3>, 2> p, std::array<std::int64_t, 3> n)

template<std::floating_point T>
Mesh<T> build_tet(MPI_Comm comm, MPI_Comm subcomm, std::array<std::array<T, 3>, 2> p, std::array<std::int64_t, 3> n, const CellPartitionFunction &partitioner)

template<std::floating_point T>
Mesh<T> build_hex(MPI_Comm comm, MPI_Comm subcomm, std::array<std::array<T, 3>, 2> p, std::array<std::int64_t, 3> n, const CellPartitionFunction &partitioner)

template<std::floating_point T>
Mesh<T> build_prism(MPI_Comm comm, MPI_Comm subcomm, std::array<std::array<T, 3>, 2> p, std::array<std::int64_t, 3> n, const CellPartitionFunction &partitioner)

template<std::floating_point T>
mesh::Mesh<T> build_hex(MPI_Comm comm, MPI_Comm subcomm, std::array<std::array<T, 3>, 2> p, std::array<std::int64_t, 3> n, const CellPartitionFunction &partitioner)

template<typename T>
void reorder_list(std::span<T> list, std::span<const std::int32_t> nodemap) Reorder an adjacency list of fixed degree.

template<std::floating_point T>
std::tuple<std::vector<std::int32_t>, std::vector<T>, std::vector<std::int32_t>> compute_vertex_coords_boundary(const mesh::Mesh<T> &mesh, int dim, std::span<const std::int32_t> facets) The coordinates of ‘vertices’ for for entities of a give dimension that are attached to specified facets.
 Parameters:
mesh – [in] Mesh to compute the vertex coordinates for
dim – [in] Topological dimension of the entities
facets – [in] List of facets on the meh boundary
 Pre:
The provided facets must be on the boundary of the mesh.
 Returns:
(0) Entities attached to the boundary facets, (1) vertex coordinates (shape is
(3, num_vertices)
) and (2) map from vertex in the full mesh to the position (column) in the vertex coordinates array (set to 1 if vertex in full mesh is not in the coordinate array).

template<std::floating_point T>
std::pair<std::vector<T>, std::array<std::size_t, 2>> compute_vertex_coords(const mesh::Mesh<T> &mesh) The coordinates for all ‘vertices’ in the mesh
 Parameters:
mesh – [in] Mesh to compute the vertex coordinates for
 Returns:
The vertex coordinates. The shape is
(3, num_vertices)
and the jth column hold the coordinates of vertex j.

template<std::floating_point T>

using CellPartitionFunction = 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)>