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

◆ 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_type()

◆ cell_types()

◆ comm()

◆ connectivity() [1/2]

◆ connectivity() [2/2]

◆ create_cell_permutations()

◆ create_connectivity()

◆ create_entities()

◆ create_entity_permutations()

◆ entity_types()

◆ get_cell_permutation_info()

◆ get_entity_permutations()

◆ index_map()

◆ index_maps()

◆ interprocess_facets() [1/2]

◆ interprocess_facets() [2/2]