Mesh (`dolfinx::mesh`)#

Under development

namespace mesh#

Mesh data structures and algorithms on meshes.

Representations of meshes and support for operations on meshes.

Enums

enum class CellType : std::int8_t#

Cell type identifier.

Values:

enumerator point#

enumerator interval#

enumerator triangle#

enumerator tetrahedron#

enumerator quadrilateral#

enumerator pyramid#

enumerator prism#

enumerator hexahedron#

enum class DiagonalType#

Enum for different diagonal types.

Values:

enumerator left#

enumerator right#

enumerator crossed#

enumerator shared_facet#

enumerator left_right#

enumerator right_left#

enum class GhostMode : std::uint8_t#

Enum for different partitioning ghost modes.

Values:

enumerator none#

enumerator shared_facet#

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(std::string_view cell)#

Get the cell type from a cell string

Parameters:: cell – [in] Cell shape string
Returns:: The cell type

inline int cell_dim(CellType type)#: Return topological dimension of cell type.

inline 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] Cell type.
index – [in] Facet index (relative to the cell).

Returns:

Type of facet for this cell at this index.

inline CellType cell_entity_type(CellType type, int d, int index)#: Return type of cell for entity of dimension d at given entity index.

graph::AdjacencyList<int> get_entity_vertices(CellType type, int dim)#: List of entities, where entity (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.

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:: 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 lower-dimensional 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, graph::AnyPartitionFunction partitioner = {}, GhostMode ghost_mode = GhostMode::none, const graph::Reorder &reorder_fn = graph::Reorder{})#

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

Note

Collective.

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. See graph::AnyPartitionFunction.
ghost_mode – [in] Ghost mode of the created mesh, passed to partitioner if it holds a graph::partition_fn or a graph::hybrid_partition_fn. Defaults to GhostMode::none.
reorder_fn – [in] Function for (locally) reordering cells

Returns:

Mesh

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 graph::AnyPartitionFunction &partitioner = {}, GhostMode ghost_mode = GhostMode::none, const graph::Reorder &reorder_fn = graph::Reorder{})#

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

Note

Collective.

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. See graph::AnyPartitionFunction.
ghost_mode – [in] Ghost mode of the created mesh, as for the more general ::create_box.
reorder_fn – [in] Function for (locally) reordering cells

Returns:

Mesh

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, graph::AnyPartitionFunction partitioner, DiagonalType diagonal = DiagonalType::right, int gdim = 2, GhostMode ghost_mode = GhostMode::none, const graph::Reorder &reorder_fn = graph::Reorder{})#

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

Note

Collective.

Parameters:

comm – [in] MPI communicator to build the mesh on.
p – [in] Bottom-left and top-right 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. See graph::AnyPartitionFunction.
diagonal – [in] Direction of diagonals
gdim – [in] Geometric dimension. Must be >= 2. Coordinates are embedded in the first 2 components; remaining components are zero.
ghost_mode – [in] Ghost mode of the created mesh, passed to partitioner if it holds a graph::partition_fn or a graph::hybrid_partition_fn. Defaults to GhostMode::none.
reorder_fn – [in] Function for (locally) reordering cells

Returns:

Mesh

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, int gdim = 2)#

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

Note

Collective.

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
gdim – [in] Geometric dimension. Must be >= 2. Coordinates are embedded in the first 2 components; remaining components are zero.

Returns:

Mesh

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, graph::AnyPartitionFunction partitioner = {}, int gdim = 1, const graph::Reorder &reorder_fn = graph::Reorder{})#

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.

Note

Collective.

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. See graph::AnyPartitionFunction.
gdim – [in] Geometric dimension. Must be >= 1. The interval lies along the first coordinate axis; remaining components are zero.
reorder_fn – [in] Function for (locally) reordering cells

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, const 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

Collective.

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 degree-of-freedom map (using global indices) for cells on this process. nodes is a sorted and unique list of the indices in xdofs.
x – [in] 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 processes with a lower rank than the caller.
dim – [in] Geometric dimension (1, 2, or 3).
reorder_fn – [in] Function for re-ordering the degree-of-freedom map associated with the geometry data.

Pre:

topology, elements and dim must be consistent across all ranks.

Pre:

nodes must be sorted.

Returns:

A mesh geometry.

std::tuple<graph::AdjacencyList<std::int32_t>, std::vector<std::int64_t>, int, std::vector<std::int32_t>> build_local_dual_graph(std::span<const CellType> celltypes, const std::vector<std::span<const std::int64_t>> &cells, std::optional<std::int32_t> max_facet_to_cell_links, int num_threads)#

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

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 negative value (all padding values will be equal). The vertex global indices are sorted for each facet.

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.

Note

Facet (2) and cell (4) data will contain multiple entries for the same facet for branching meshes with max_facet_to_cell_links>2 to account for all facet cell connectivies.

Parameters:

celltypes – [in] List of cell types.
cells – [in] Lists of cell vertices (stored as flattened lists, one for each cell type).
max_facet_to_cell_links – [in] Bound on the number of cells a facet needs to be connected to be considered matched, i.e. a matched facet is not connected any cells on other processes. All facets connected to less than max_facet_to_cell_links cells are considered unmatched and parallel communication will check for further connections. Equal to 2 for non-branching manifold meshes. Passing std::nullopt (no upper bound) corresponds to max_facet_to_cell_links=∞, i.e. every facet is considered unmatched.
num_threads – [in] Number of threads to use. Must be greater than 0.

Returns:

Local dual graph
Facets, defined by their sorted vertices, that are shared by fewer than max_facet_to_cell_links cells on this rank. The logically 2D array is flattened (row-major).
Facet data array (2) number of columns
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, std::optional<std::int32_t> max_facet_to_cell_links, int num_threads = 1)#

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.

Note

cells and celltypes must have the same size.

Note

The assumption in build_local_dual_graph on how unmatched facets are identified will not allow for T-joints (or any other higher branching) across process boundaries to be picked up by the dual graph. If the joints do not live on the process boundary this is not a problem.

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.
max_facet_to_cell_links – [in] Bound on the number of cells a facet needs to be connected to be considered matched, i.e. a matched facet is not connected any cells on other processes. All facets connected to less than max_facet_to_cell_links cells are considered unmatched and parallel communication will check for further connections. Defaults to 2, which covers non-branching manifold meshes. Passing std::nullopt (no upper bound) corresponds to max_facet_to_cell_links=∞, i.e. every facet is considered unmatched.
num_threads – [in] Number of threads to use. Must be greater than 0.

Returns:

The dual graph.

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, std::string name = "mesh_tags")#

Create MeshTags from arrays.

Note

Entities that do not exist on this rank are ignored. Ghost entities matched by vertices are retained, so returned indices may include ghosts.

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 of values must be equal to number of rows in entities.
name – [in] Name of the meshtags.

std::vector<std::uint8_t> compute_entity_permutations(const Topology &topology, int dim, int num_threads)#

Compute the permutation to apply to each cell-local entity of a given dimension.

The permutation 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 * entities_per_cell + entity_index] contains the permutation data for the entity with index entity_index of cell cell_index. This data passed to FFCx kernels, where it is used to permute quadrature points on sub-entity integrals when data from more than one cell incident to the entity is used.

See also

compute_cell_permutations, which packs the orientations of all of a cell’s sub-entities into one integer per cell, for correcting element DOFs rather than quadrature points.

Parameters:

topology – [in] Mesh topology.
dim – [in] Topological dimension of the entities to permute. Must satisfy 0 <= dim < topology.dim(). Vertices (dim == 0) have no orientation, so an empty vector is returned for them.
num_threads – [in] Number of threads to use.

Returns:

Permutation of each cell-local entity of dimension dim, flattened row-wise.

std::vector<std::uint32_t> compute_cell_permutations(const Topology &topology, int num_threads)#

Compute the packed per-cell permutation data.

Required by elements whose DOF transformations are not the identity. Where those transformations are permutations, e.g. higher-order Lagrange, the correction is applied once to the dofmap when it is built; otherwise, e.g. N1curl and Raviart-Thomas, the correction is applied to the element tensor on each cell at assembly time.

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)

Note

Not collective.

Parameters:

topology – [in] Mesh topology.
num_threads – [in] Number of threads to use. Must be >= 1.

Throws:

std::invalid_argument – If num_threads < 1.
std::runtime_error – If topology is a mixed-topology mesh (more than one 3D cell type).

Pre:

All entities of dimension < topology.dim() must already exist (see Topology::create_entities).

Returns:

Facet permutation and cell permutations, covering both owned and ghost cells.

Topology create_topology(MPI_Comm comm, const std::vector<CellType> &cell_types, 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, int num_threads)#

Create a mesh topology.

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

Note

Collective.

Parameters:

comm – [in] Communicator across which the topology will be distributed.
cell_types – [in] List of cell types in the topology.
cells – [in] Cell topology (list of vertices for each cell) for each cell type using global indices for the vertices. The cell type for cells[i] is cell_types[i], using row-major storage and where the row cells[i][j] is the vertices for cell j of cell type i. Each cells[i] 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[i], where n is given by the length of ghost_owners[i].
original_cell_index – [in] Input cell index for each cell type, e.g. the cell index in an input file. This index remains associated with the cell after any re-ordering and parallel (re)distribution.
ghost_owners – [in] Owning rank for ghost cells (ghost cells are at end of each list of cells).
boundary_vertices – [in] Vertices on the ‘exterior’ (boundary) of the local topology. These vertices might appear on other processes.
num_threads – [in] Number of threads to use. Must be >= 1.

Returns:

A distributed mesh 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, int num_threads)#

Create a mesh topology for a single cell type.

This function provides a simplified interface to ::create_topology for the case that a mesh has one cell type only,

Note

Collective.

Parameters:

comm – [in] Communicator across which the topology will be 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 in cells, where n is given by the length of ghost_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.
num_threads – [in] Number of threads to use. Must be >= 1.

Returns:

A distributed mesh topology.

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.

Note

Collective.

Parameters:

topology – [in] Original (parent) topology.
dim – [in] Topological dimension of the entities in the new topology.
entities – [in] 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.

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:

topology – [in] Mesh topology.
dim – [in] Topological dimension of the entities.
entities – [in] Mesh entities defined by their vertices.

Returns:

Index of the ith entity in entities, If an entity cannot be found on this rank, -1 is returned as the index.

std::vector<std::vector<std::int32_t>> compute_mixed_cell_pairs(const Topology &topology, mesh::CellType facet_type)#

Compute a list of cell-cell connections for each possible combination in the topology which have the same connecting facet type.

Todo:: Remove redundant data.

Note

All facet-cell connectivity and cell-facet connectivity must be computed beforehand in the topology.

Parameters:

topology – [in] A mesh topology
facet_type – [in] Type of facet connection between cells

Returns:

A list for each possible cell-cell connection, arranged in the ordering given by cell_types() in the topology. i.e. if the cell types are tet, prism, hex, and the facet_type is quadrilateral, then the lists returned are: tet-tet (empty), tet-prism (empty), tet-hex (empty), prism-tet (empty), prism-prism, prism-hex, hex-tet (empty), hex-prism, hex-hex. Note there are empty lists for the invalid cases, and also that there is currently redundant data, since the transpose is also computed, i.e. prism-hex as well as hex-prism. Each list contains a flattened array with data in the order (cell0, local facet0, cell1, local facet1) for each connection between cells.

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(const Topology &topology, int dim, CellType entity_type, int num_threads = 1)#

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

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

Note

Collective.

Parameters:

topology – [in] Mesh topology.
dim – [in] Dimension of the entities to create.
entity_type – [in] Entity type in dimension dim to create. Entity type must be in the list returned by Topology::entity_types.
num_threads – [in] Number of threads to use for entity creation. Must be >= 1.

Returns:

Tuple of (cell->entity connectivity, entity->vertex connectivity, index map for created entities, list of interprocess entities). Interprocess entities lie on the “true” boundary between owned cells of each process. If dim is 0, or if entities of type entity_type already exist, then {std::vector(), nullptr, nullptr, std::vector()} is returned.

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

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

Note

Not collective.

Parameters:

topology – [in] The topology
d0 – [in] Dimension and index of the entities, (dim0, i).
d1 – [in] Dimension and index of the incident entities, (dim1, j).

Pre:

Entities of dimension d0[0] and d1[0] must already exist (see Topology::create_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, int facet_type_idx)#

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

Not collective.

Parameters:

topology – [in] Mesh topology.
facet_type_idx – [in] The index of the facet type in Topology::entity_types(facet_dim)

Pre:

topology.create_connectivity(tdim - 1, tdim) and topology.create_entities(tdim - 1) (which populates the interprocess facets used to distinguish an exterior facet from an inter-process one) must already have been called.

Returns:

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

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

Not collective.

Parameters:: topology – [in] Mesh topology.
Pre:: topology.create_connectivity(tdim - 1, tdim) and topology.create_entities(tdim - 1) (which populates the interprocess facets used to distinguish an exterior facet from an inter-process one) must already have been called.
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] Cell shape.
layout – [in] Layout of geometry ‘degrees-of-freedom’ 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 mid-side and other higher-order nodes being removed from the input cell.

bool is_vertex_dof_layout(CellType cell_type, const fem::ElementDofLayout &layout)#

Check if ::extract_topology is the identity operation for a dof layout, i.e. the cell ‘nodes’ are exactly the cell vertices, in vertex order (‘P1 geometry’).

When this holds, cell node data can be used directly as cell topology, without the copy that ::extract_topology performs.

Parameters:

cell_type – [in] Cell shape.
layout – [in] Layout of geometry ‘degrees-of-freedom’ on the reference cell.

Returns:

true if the cell ‘nodes’ are the 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 geometry nodes of the mesh entities (h).

Note

For a straight-sided (affine) mesh the geometry nodes of an entity are exactly its vertices. For a curved (higher-order) mesh all geometry nodes of the entity are used, not only its vertices.

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 geometry nodes, h[i] corresponds to the entity entities[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 row-major.

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.

The midpoint is the mean of all geometry nodes of the entity. For a straight-sided (affine) mesh this is the mean of its vertices; for a curved (higher-order) mesh it also includes the non-vertex geometry nodes.

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

template<std::floating_point T, MarkerFn<T> U> std::vector<std::int32_t> locate_entities(const Mesh<T> &mesh, int dim, U marker, int entity_type_idx)#

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.

Note

Collective.

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’, and false otherwise.
entity_type_idx – [in] The index of the entity type in Topology::entity_types(dim)

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

Note

Collective.

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’, and false 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

Collective.

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:

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’, and false otherwise.

Returns:

Sorted list of marked entity indices (indices local to the process); may include ghost entities attached to an owned boundary facet.

template<std::floating_point T> std::pair<std::vector<std::int32_t>, std::array<std::size_t, 2>> 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.

Note

A discontinuous geometry has no coordinate degrees-of-freedom associated with sub-entities of a cell, so only dim == mesh.topology().dim() is supported for such a mesh.

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 of dim-dimensional mesh entities.

Returns:

Geometry DOFs associated with the closure of each entity in entities and the shape. 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].

Pre:

Mesh connectivities dim -> mesh.topology().dim() and mesh.topology().dim() -> dim must have been computed, and, if permute is true, mesh.topology().create_cell_permutations() must have been called. Otherwise std::runtime_error is thrown.

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

Compute incident entities.

Parameters:

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

Returns:

Sorted, unique list of entities of topological dimension d1 that are incident to entities in entities (topological dimension d0); may include ghost entities.

template<typename U> Mesh<typename std::remove_reference_t<typename U::value_type>> create_mesh(MPI_Comm comm, MPI_Comm commt, 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 graph::Partitioner &partitioner, GhostMode ghost_mode, std::optional<std::int32_t> max_facet_to_cell_links, int num_threads, const graph::Reorder &reorder_fn = graph::Reorder{})#

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

The input cells and geometry data can be distributed across the calling ranks, but must be not duplicated across ranks.

The function partitioner computes the parallel distribution, i.e. the destination rank for each cell. If it is not callable, no redistribution is performed.

Note

Collective.

Parameters:

comm – [in] Communicator to build the mesh on.
commt – [in] 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.
cells – [in] Cells, grouped by cell type with cells[i] being the cells of the same type. Cells are defined by their ‘nodes’ (using global indices) following the Basix ordering, and for each cell type concatenated to form a flattened list. For lowest-order cells this will be just the cell vertices. For higher-order geometry cells, other cell ‘nodes’ will be included. See io::cells for examples of the Basix ordering.
elements – [in] Coordinate elements for the cells, where elements[i] is the coordinate element for the cells in cells[i]. The list of elements must be the same on all calling parallel ranks.
commg – [in] Communicator for geometry.
x – [in] Geometry data (‘node’ coordinates). Row-major storage. The global index of the ith node (row) in x is taken as i plus the parallel rank offset (on comm), where the offset is the sum of x rows on all lower ranks than the caller.
xshape – [in] Shape of the x data.
partitioner – [in] Partitioner that computes the owning rank for each cell in cells, together with the node weights it is called with (one entry per cell in cells, flattened across cell types in the same order as cells; if std::nullopt, cells are treated as having equal weight). If partitioner.fn is not callable, cells are not redistributed. If it holds a graph::geom_partition_fn or a graph::hybrid_partition_fn, this function computes the centroid of each cell in cells (from x) and supplies them, see graph::AnyPartitionFunction.
ghost_mode – [in] Ghost mode of the created mesh, passed to partitioner if it holds a graph::partition_fn or a graph::hybrid_partition_fn. Has no effect if it holds a graph::geom_partition_fn, which can never ghost.
max_facet_to_cell_links – [in] Bound on the number of cells a facet can be connected to.
num_threads – [in] Number threads to use in mesh construction. Must be >= 1.
reorder_fn – [in] Function that reorders (locally) cells that are owned by this process.

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, 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 graph::Partitioner &partitioner, GhostMode ghost_mode, std::optional<std::int32_t> max_facet_to_cell_links, int num_threads, const graph::Reorder &reorder_fn = graph::Reorder{})#

Create a distributed mesh with a single cell type from mesh data and 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.

This constructor provides a simplified interface to the more general ::create_mesh constructor, which supports meshes with more than one cell type.

Note

Collective.

Parameters:

comm – [in] Communicator to build the mesh on.
commt – [in] 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.
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 higher-order 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). Row-major storage. The global index of the ith node (row) in x is taken as i plus the process offset on comm. The offset is the sum of x rows on all processes with a lower rank than the caller.
xshape – [in] Shape of the x data.
partitioner – [in] Partitioner that computes the owning rank for each cell, together with the node weights it is called with (one entry per cell in cells; if std::nullopt, cells are treated as having equal weight). If partitioner.fn is not callable, cells are not redistributed. See the more general ::create_mesh for the graph::geom_partition_fn and graph::hybrid_partition_fn alternatives.
ghost_mode – [in] Ghost mode of the created mesh, as for the more general ::create_mesh.
max_facet_to_cell_links – [in] Bound on the number of cells a facet can be connected to.
num_threads – [in] Number threads to use in mesh construction. Must be >= 1.
reorder_fn – [in] Function that reorders (locally) cells that are owned by this process.

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>> &element, const U &x, std::array<std::size_t, 2> xshape, GhostMode ghost_mode, std::optional<std::int32_t> max_facet_to_cell_links = 2)#

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.

Note

Collective.

Parameters:

comm – [in] MPI communicator to build the mesh on.
cells – [in] Cells on the calling process. See ::create_mesh for a detailed description.
element – [in] Coordinate element for the cells.
x – [in] Geometry data (‘node’ coordinates). See ::create_mesh for a detailed description.
xshape – [in] Shape of x. It should be (num_points, gdim).
ghost_mode – [in] Required type of cell ghosting/overlap.
max_facet_to_cell_links – [in] Bound on the number of cells a facet can be connected to.

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 sub-geometry from a mesh and a subset of mesh entities to be included.

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

Note

Collective.

Parameters:

mesh – [in] The full mesh.
dim – [in] Topological dimension of the sub-topology.
subentity_to_entity – [in] 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.

template<std::floating_point T> std::tuple<Mesh<T>, EntityMap, EntityMap, 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] Dimension entities in mesh that will be cells in the sub-mesh.
entities – [in] Indices of entities in mesh to include in the sub-mesh.

Returns:

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

template<typename T> MeshTags<T> transfer_meshtags_to_submesh(const MeshTags<T> &tags, std::shared_ptr<const dolfinx::mesh::Topology> submesh_topology, const EntityMap &cell_map, const EntityMap &vertex_map)#

Transfer a meshtags object from a parent to a submesh.

Note

The cell_map/vertex_map order matches the (entity_map, vertex_map) order that ::create_submesh returns, so its result can be unpacked and passed straight through.

Parameters:

tags – [in] The meshtags object on the parent mesh.
submesh_topology – [in] The topology of the submesh.
cell_map – [in] Map from submesh cell to parent mesh entity.
vertex_map – [in] Map from submesh vertex to parent mesh vertex.

Returns:

A meshtags object on the submesh.

template<std::floating_point T> class Geometry#

#include <Geometry.h>

Geometry stores the geometry imposed on a mesh.

Public Types

using value_type = T #: Value type.

Public Functions

template<typename U, typename V, typename W> inline Geometry(std::shared_ptr<const common::IndexMap> index_map, U &&dofmaps, const std::vector<fem::CoordinateElement<typename std::remove_reference_t<typename V::value_type>>> &elements, V &&x, int dim, W &&input_global_indices)#

Constructor of object that holds mesh geometry data.

The geometry ‘degree-of-freedom map’ is a logically rectangular array (row-major) where each row corresponds to a cell, and the columns are the indices in the coordinate array of the cell coordinate degree-of-freedom. For each cell type there is a geometry degree-of-freedom map.

Parameters:

index_map – [in] Index map associated with the geometry degrees-of-freedom.
dofmaps – [in] The geometry (point) dofmaps for each cell type in the mesh. For a cell of a given type, the dofmap gives the position in the point array of each local geometry node of the cell. Each cell type has its own dofmap. Each dofmap uses row-major storage.
elements – [in] Elements that describe cell geometry maps. element[i] is the coordinate element associated with dofmaps[i].
x – [in] Point coordinates. The shape is (num_points, 3) and the storage is row-major.
dim – [in] The geometric dimension (0 < dim <= 3).
input_global_indices – [in] ‘Global’ input index of each point, commonly from a mesh input file.

Geometry(const Geometry&) = default#: Copy constructor.

Geometry(Geometry&&) = default#: Move constructor.

~Geometry() = default#: Destructor.

Geometry &operator=(Geometry&&) = default#: Move assignment.

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

inline md::mdspan<const std::int32_t, md::dextents<std::size_t, 2>> dofmap() const#

DofMap for the geometry.

Deprecated:: Use dofmaps().front() instead.

Returns:: A 2D array with shape (num_cells, dofs_per_cell).

inline std::vector<md::mdspan<const std::int32_t, md::dextents<std::size_t, 2>>> dofmaps() const#

Degree-of-freedom map associated with each coordinate map element in the geometry.

Returns:: A list of dofmap arrays, each with shape (num_cells, dofs_per_cell).

inline std::shared_ptr<const common::IndexMap> index_map() const#

Index map for the geometry ‘degrees-of-freedom’.

Returns:: Index map for the geometry dofs.

inline std::span<const value_type> x() const#

Access geometry degrees-of-freedom data (const version).

Returns:: The flattened row-major geometry data, where the shape is (num_points, 3).

inline std::span<value_type> x()#

Access geometry degrees-of-freedom data (non-const version).

Returns:: The flattened row-major geometry data, where the shape is (num_points, 3).

inline const std::vector<fem::CoordinateElement<value_type>> &cmaps() const#

The elements that describes the geometry map.

Returns:: The coordinate/geometry elements.

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:: T – Floating point type for representing the geometry.

Public Types

using geometry_type = Geometry<T>#: Value type.

Public Functions

template<typename V> inline Mesh(MPI_Comm comm, std::shared_ptr<Topology> topology, V &&geometry)#

Create a Mesh.

Note

This constructor is not normally called by users. User code will normally use ::create_mesh.

Note

Collective.

Parameters:

comm – [in] MPI Communicator.
topology – [in] Mesh topology.
geometry – [in] Mesh geometry.

Mesh(const Mesh &mesh) = default#

Copy constructor

Note

Collective.

Parameters:: mesh – [in] Mesh to be copied

Mesh(Mesh &&mesh) = default#

Move constructor

Parameters:: mesh – Mesh to be moved.

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

inline const Geometry<T> &geometry() const#

Get mesh geometry (const version).

Returns:: The geometry object associated with the mesh.

inline MPI_Comm comm() const#

Mesh MPI communicator.

Returns:: The communicator on which the mesh is distributed.

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:: T – Type of the tag value associated with each entity.

Public Functions

template<typename U, typename V> inline MeshTags(std::shared_ptr<const Topology> topology, int dim, U &&indices, V &&values, std::string name = "mesh_tags")#

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.
name – [in] Name of the meshtags.

Pre:

indices must be sorted and unique.

MeshTags(const MeshTags &tags) = default#: Copy constructor.

MeshTags(MeshTags &&tags) = default#: Move constructor.

~MeshTags() = default#: Destructor.

MeshTags &operator=(const MeshTags &tags) = default#: Copy assignment.

MeshTags &operator=(MeshTags &&tags) = default#: Move assignment.

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 (local-to-process, in [0, size_local + num_ghosts); may include ghost entities). The indices are sorted.

inline std::span<const T> values() const#: Values attached to topology entities.

inline int dim() const#: Return topological dimension of tagged entities.

inline std::shared_ptr<const Topology> topology() const#: Return topology.

inline const std::string &name() const#: Return name.

inline void name(std::string name)#: Set name.

class EntityMap#

#include <EntityMap.h>

A bidirectional map relating entities in one topology to another.

Public Functions

template<typename U> inline EntityMap(std::shared_ptr<const Topology> topology, std::shared_ptr<const Topology> sub_topology, int dim, U &&sub_topology_to_topology)#

Constructor of a bidirectional map relating entities of dimension dim in topology and sub_topology.

Template Parameters:

U –

Parameters:

topology – A mesh topology.
sub_topology – Topology of another mesh. This must be a “sub-topology” of topology, i.e. every entity in sub_topology must also exist in topology.
dim – Topological dimension of the entities.
sub_topology_to_topology – List of entities in topology where sub_topology_to_topology[i] is the index in topology corresponding to entity i in sub_topology.

Pre:

sub_topology_to_topology entries must be distinct.

EntityMap(const EntityMap &map) = default#: Copy constructor.

EntityMap(EntityMap &&map) = default#: Move constructor.

~EntityMap() = default#: Destructor.

EntityMap &operator=(EntityMap &&map) = default#: Move assignment.

int dim() const#

Get the topological dimension of the entities related by this EntityMap.

Returns:: The topological dimension.

std::shared_ptr<const Topology> topology() const#

Get the (parent) topology.

Returns:: The parent topology.

std::shared_ptr<const Topology> sub_topology() const#

Get the sub-topology.

Returns:: The sub-topology.

inline std::vector<std::int32_t> sub_topology_to_topology(CellRange auto &&entities, bool inverse) const#

Map entities between the sub-topology and the parent topology.

If inverse is false, this function maps a list of this->dim()-dimensional entities from this->sub_topology() to the corresponding entities in this->topology(). If inverse is true, it performs the inverse mapping: from this->topology() to this->sub_topology(). Entities that do not exist in the sub-topology are marked as -1.

Note

If inverse is true, this function recomputes the inverse map on every call (it is not cached), which may be expensive if called repeatedly.

Parameters:

entities – List of entity indices in the source topology.
inverse – If false, maps from this->sub_topology() to this->topology(). If true, maps from this->topology() to this->sub_topology().

Returns:

A list of mapped entity indices. Entities that do not exist in the target topology are marked as -1.

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, the caching policy is not clear.

Public Functions

Topology(std::vector<CellType> cell_types, std::shared_ptr<const common::IndexMap> vertex_map, std::vector<std::shared_ptr<const common::IndexMap>> cell_maps, std::vector<std::shared_ptr<graph::AdjacencyList<std::int32_t>>> cells, const std::optional<std::vector<std::vector<std::int64_t>>> &original_cell_index = std::nullopt, int num_threads = 1)#

Create a mesh topology.

A Topology represents the connectivity of a mesh. Mesh entities, i.e. vertices, edges, faces and cells, are defined in terms of their vertices. Connectivity represents the relationships between entities, e.g. the cells that are connected to a given edge in the mesh.

Parameters:

cell_types – [in] Types of cells.
vertex_map – [in] Index map describing the distribution of mesh vertices.
cell_maps – [in] Index maps describing the distribution of mesh cells for each cell type in cell_types.
cells – [in] Cell-to-vertex connectivities for each cell type in cell_types.
original_cell_index – [in] Original indices for each cell in cells.
num_threads – [in] Number of threads to use. Must be >= 1.

Topology(const Topology &topology) = default#: Copy constructor.

Topology(Topology &&topology) = default#: Move constructor.

~Topology() = default#: Destructor.

Topology &operator=(Topology &&topology) = default#: Move assignment.

int dim() const noexcept#: Topological dimension of the mesh.

const std::vector<CellType> &entity_types(int dim) const#

Entity types in the topology for a given dimension.

Parameters:: dim – [in] Topological dimension.
Returns:: Entity types.

CellType cell_type() const#

Cell type.

This function is for topologies with one cell type only.

Returns:: Cell type that the topology is for.

std::vector<std::shared_ptr<const common::IndexMap>> index_maps(int dim) const#

Get the index maps that describe the parallel distribution of the mesh entities of a given topological dimension.

Parameters:: dim – [in] Topological dimension.
Returns:: Index maps for entities of dimension dim. Entity types with no map are dropped, so the result is empty or has one entry per entity type in entity_types(dim) order; it is not indexable positionally by entity-type index if any map is missing.

std::shared_ptr<const common::IndexMap> index_map(int dim) const#

Get the IndexMap that describes the parallel distribution of the mesh entities.

Parameters:: dim – [in] Topological dimension
Throws:: std::out_of_range – If entities of dimension dim have not been created (call create_entities(dim) first), or if there is more than one entity type of dimension dim (call index_maps instead).
Returns:: Index map for the entities of dimension dim.

std::shared_ptr<const graph::AdjacencyList<std::int32_t>> connectivity(std::array<int, 2> d0, std::array<int, 2> d1) const#

Get 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 in entity_types(dim).

Parameters:

d0 – [in] Pair of (topological dimension of entities, index of “entity type” within topological dimension).
d1 – [in] Pair of (topological dimension of 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.

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] Topological dimension.
d1 – [in] Topological dimension.

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.

const std::vector<std::uint32_t> &get_cell_permutation_info() const#

Get the cell permutation information.

Throws:

std::runtime_error – If create_entity_permutations has not been called.
std::out_of_range – If there is more than one cell type (see Topology::index_map).

const std::vector<std::uint8_t> &get_entity_permutations(int dim) const#

Get the numbers that encode the permutation to apply to each cell-local entity of a given dimension.

The permutations are 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 * entities_per_cell + entity_index] contains the permutation of the cell-local entity entity_index of cell with local index cell_index.

Parameters:

dim – [in] Topological dimension of the entities. Vertices have no orientation, so their permutations are empty.

Throws:

std::runtime_error – If create_entity_permutations has not been called for dim.
std::out_of_range – If there is more than one facet type (see Topology::index_map).

Returns:

The encoded permutation info.

std::vector<CellType> cell_types() const#

Get the types of cells in the topology.

Returns:: The cell types

const std::vector<std::int32_t> &interprocess_facets(int index) const#

List of inter-process facets of a given type.

“Inter-process” 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.

Facets must have been computed for inter-process facet data to be available.

Parameters:: index – [in] Index of facet type, following the order given by ::entity_types.
Returns:: Indices of the inter-process facets.

const std::vector<std::int32_t> &interprocess_facets() const#

List of inter-process facets.

“Inter-process” 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:: Inter-process facets are available only if facet topology has been computed.

bool create_entities(int dim, int num_threads = 1)#

Create entities of given topological dimension.

Note

Collective.

Parameters:

dim – [in] Topological dimension of entities to compute.
num_threads – [in] Number of threads to use. Must be >= 1.

Returns:

True if entities are created, false if entities already existed.

void create_connectivity(int d0, int d1)#

Create connectivity between given pair of dimensions, d0 -> d1.

Note

Collective.

Parameters:

d0 – [in] Topological dimension.
d1 – [in] Topological dimension.

void create_entity_permutations(int dim, int num_threads = 1)#

Compute entity permutations and reflections.

A permutation records how an entity is oriented as seen from a cell, relative to a low-to-high ordering of the entity’s global vertex indices. It is passed to FFCx kernels as quadrature_permutation, so that cells sharing an entity agree on the order of the quadrature points on it. Which dimension is needed is a property of the integral, not of the element: an interior facet integral needs dim() - 1, a ridge integral dim() - 2.

Does nothing if the permutations for dim have already been computed.

Mesh (dolfinx::mesh)#

Mesh (`dolfinx::mesh`)#