Topology stores the topology of a mesh, consisting of mesh entities and connectivity (incidence relations for the mesh entities). More...

#include <Topology.h>

Public Member 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.
	Topology (const Topology &topology)=default
	Copy constructor.
	Topology (Topology &&topology)=default
	Move constructor.
	~Topology ()=default
	Destructor.
Topology &	operator= (const Topology &topology)=delete
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.
CellType	cell_type () const
	Cell type.
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.
std::shared_ptr< const common::IndexMap >	index_map (int dim) const
	Get the IndexMap that describes the parallel distribution of the mesh entities.
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.
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.
const std::vector< std::uint32_t > &	get_cell_permutation_info () const
	Get the cell permutation information.
void	create_cell_orientations (std::optional< std::span< const std::int8_t > > orientations=std::nullopt)
	Compute or set a per-cell marker for a consistent orientation of a surface mesh.
std::vector< std::int8_t >	cell_orientations () const
	Get the orientation of each cell relative to the orientation of its surface (see create_cell_orientations).
bool	has_cell_orientations () const noexcept
	Check if a cell orientation has been computed or set (see create_cell_orientations).
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.
std::vector< CellType >	cell_types () const
	Get the types of cells in the topology.
const std::vector< std::int32_t > &	interprocess_facets (int index) const
	List of inter-process facets of a given type.
const std::vector< std::int32_t > &	interprocess_facets () const
	List of inter-process facets.
bool	create_entities (int dim, int num_threads=1)
	Create entities of given topological dimension.
void	create_connectivity (int d0, int d1)
	Create connectivity between given pair of dimensions, d0 -> d1.
void	create_entity_permutations (int dim, int num_threads=1)
	Compute entity permutations and reflections.
void	create_cell_permutations (int num_threads=1)
	Compute the packed per-cell permutation info.
MPI_Comm	comm () const
	Mesh MPI communicator.

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

Detailed Description

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.

Constructor & Destructor Documentation

◆ Topology()

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

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

Member Function Documentation

◆ cell_orientations()

std::vector< std::int8_t > cell_orientations ( ) const

Get the orientation of each cell relative to the orientation of its surface (see create_cell_orientations).

Returns: For each owned and ghost cell, in local cell order, -1 if its orientation is reversed and 1 otherwise. All are 1 if no orientation has been computed or set (see has_cell_orientations).

Exceptions

std::runtime_error	If create_cell_permutations has not been called.
std::out_of_range	If there is more than one cell type.

◆ cell_type()

CellType cell_type ( ) const

Cell type.

This function is for topologies with one cell type only.

Returns: Cell type that the topology is for.

◆ cell_types()

std::vector< CellType > cell_types ( ) const

Get the types of cells in the topology.

Returns: The cell types

◆ comm()

MPI_Comm comm ( ) const

Mesh MPI communicator.

Returns: Communicator on which the topology is distributed.

◆ connectivity() [1/2]

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

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

◆ connectivity() [2/2]

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

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

◆ create_cell_orientations()

void create_cell_orientations ( std::optional< std::span< const std::int8_t > > orientations = std::nullopt )

Compute or set a per-cell marker for a consistent orientation of a surface mesh.

The cells are not modified. A marker is stored for each cell in the cell permutation info, where elements whose basis depends on the cell orientation consume it.

On a manifold mesh, whose topological dimension is less than its geometric dimension, the contravariant Piola map scales by the pseudo-determinant \(\sqrt{\det(J^T J)}\) of the Jacobian \(J\). It is positive by construction, so it cannot encode an orientation. Instead, the vertex order of each cell fixes its normal, and elements mapped by the contravariant Piola map (e.g. Raviart-Thomas, Brezzi-Douglas-Marini) are conforming only between cells whose normals agree. A function space with such an element can therefore only be created on a manifold mesh once an orientation has been computed or set with this call (see has_cell_orientations). Lagrange and Nédélec spaces do not need it.

If no orientation is given, one is computed from the vertex orders alone (see compute_cell_orientations), which additionally creates the edges it is computed across and their orientations relative to the cells. Which of its two orientations each connected surface gets is then arbitrary, and depends on the partitioning. Pass orientations instead when a consistent orientation is already known, e.g. the outward normal of a closed surface; it is stored in the same way, but is not checked for consistency between neighbouring cells, and needs none of the above entities. On a mesh whose cells are consistently ordered, passing all 1 keeps each cell's own vertex order.

The result can be read back with cell_orientations. On cells whose vertex order disagrees with it, such elements negate their basis in every later assembly, interpolation and evaluation. Reversing all cells of a surface negates the basis functions and, with them, the degrees-of-freedom, so the field they represent is unchanged.

Warning: Changing the orientation after creating spaces whose basis depends on it invalidates existing Function data on them, as their degrees-of-freedom are not corrected.

Note: Collective. The two branches do different collective work, so orientations must be engaged on every rank or on none.

Precondition: orientations is engaged on every rank or on none.; A ghost cell has the same orientation as on its owner.

Parameters

[in] orientations For each owned and ghost cell, in local cell order, -1 if its orientation is reversed relative to its vertex order and 1 otherwise. If std::nullopt, a consistent orientation is computed instead.

Exceptions

std::invalid_argument	If the topological dimension is not 2, or orientations does not have one entry per owned and ghost cell.
std::runtime_error	If no orientation is given and the surface is not orientable, e.g. a Möbius strip, or an edge is shared by more than two cells.
std::out_of_range	If there is more than one cell type.

◆ create_cell_permutations()

void create_cell_permutations ( int num_threads = 1 )

Compute the packed per-cell permutation info.

Encodes, for each cell, the orientation of every sub-entity of that cell relative to a low-to-high ordering of global vertex indices, packed into one 32-bit integer per cell. See ::get_cell_permutation_info for the bit layout.

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.

Does nothing if the cell permutations have already been computed.

Parameters

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

See also: create_entity_permutations, which gives the orientations of one entity dimension unpacked, for permuting quadrature points.

◆ create_connectivity()

void create_connectivity	(	int	d0,
		int	d1 )

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

Note: Collective.

Parameters

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

◆ create_entities()

bool create_entities	(	int	dim,
		int	num_threads = 1 )

Create entities of given topological dimension.

Note: Collective.

Parameters

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

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

◆ create_entity_permutations()

void create_entity_permutations	(	int	dim,
		int	num_threads = 1 )

Compute entity permutations and reflections.

Note: Collective.

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.

Parameters

[in]	dim	Topological dimension of the entities, e.g. dim() - 1 for facets. Must satisfy 0 <= dim < dim(). Vertices have no orientation, so their permutations are empty.
[in]	num_threads	Number of threads to use. Must be >= 1.

See also: create_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.

◆ entity_types()

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

Entity types in the topology for a given dimension.

Parameters

[in] dim Topological dimension.

Returns: Entity types.

◆ get_cell_permutation_info()

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

Get the cell permutation information.

Exceptions

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

◆ get_entity_permutations()

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

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

Returns: The encoded permutation info.

Exceptions

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

◆ has_cell_orientations()

bool has_cell_orientations ( ) const

noexcept

Check if a cell orientation has been computed or set (see create_cell_orientations).

Function spaces whose basis depends on the cell orientation can only be created once it has.

Returns: True if the cell orientation has been computed or set.

◆ index_map()

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

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

Parameters

[in] dim Topological dimension

Returns: Index map for the entities of dimension dim.

Exceptions

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

◆ index_maps()

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

[in] dim 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.

◆ interprocess_facets() [1/2]

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.

Precondition: Inter-process facets are available only if facet topology has been computed.

◆ interprocess_facets() [2/2]

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

[in] index Index of facet type, following the order given by ::entity_types.

Returns: Indices of the inter-process facets.

The documentation for this class was generated from the following files:

/__w/dolfinx/dolfinx/cpp/dolfinx/mesh/Topology.h
/__w/dolfinx/dolfinx/cpp/dolfinx/mesh/Topology.cpp

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Topology()

Member Function Documentation

◆ cell_orientations()

◆ cell_type()

◆ cell_types()

◆ comm()

◆ connectivity() [1/2]

◆ connectivity() [2/2]

◆ create_cell_orientations()

◆ create_cell_permutations()

◆ create_connectivity()

◆ create_entities()

◆ create_entity_permutations()

◆ entity_types()

◆ get_cell_permutation_info()

◆ get_entity_permutations()

◆ has_cell_orientations()

◆ index_map()

◆ index_maps()

◆ interprocess_facets() [1/2]

◆ interprocess_facets() [2/2]