This class represents the distribution index arrays across processes. An index array is a contiguous collection of N+1 indices [0, 1, . . ., N] that are distributed across M processes. On a given process, the IndexMap stores a portion of the index set using local indices [0, 1, . . . , n], and a map from the local indices to a unique global index. More...

#include <IndexMap.h>

Public Member Functions
	IndexMap (MPI_Comm comm, std::int32_t local_size)
	Create an non-overlapping index map. More...

	IndexMap (MPI_Comm comm, std::int32_t local_size, const std::span< const std::int64_t > &ghosts, const std::span< const int > &owners)
	Create an overlapping (ghosted) index map. More...

	IndexMap (MPI_Comm comm, std::int32_t local_size, const std::array< std::vector< int >, 2 > &src_dest, const std::span< const std::int64_t > &ghosts, const std::span< const int > &owners)
	Create an overlapping (ghosted) index map. More...

	IndexMap (const IndexMap &map)=delete

	IndexMap (IndexMap &&map)=default
	Move constructor.

	~IndexMap ()=default
	Destructor.

IndexMap &	operator= (IndexMap &&map)=default
	Move assignment.

IndexMap &	operator= (const IndexMap &map)=delete

std::array< std::int64_t, 2 >	local_range () const noexcept
	Range of indices (global) owned by this process.

std::int32_t	num_ghosts () const noexcept
	Number of ghost indices on this process.

std::int32_t	size_local () const noexcept
	Number of indices owned by on this process.

std::int64_t	size_global () const noexcept
	Number indices across communicator.

const std::vector< std::int64_t > &	ghosts () const noexcept
	Local-to-global map for ghosts (local indexing beyond end of local range)

MPI_Comm	comm () const
	Return the MPI communicator that the map is defined on. More...

void	local_to_global (const std::span< const std::int32_t > &local, const std::span< std::int64_t > &global) const
	Compute global indices for array of local indices. More...

void	global_to_local (const std::span< const std::int64_t > &global, const std::span< std::int32_t > &local) const
	Compute local indices for array of global indices. More...

std::vector< std::int64_t >	global_indices () const
	Build list of indices with global indexing. More...

const std::vector< int > &	owners () const
	The ranks that own each ghost index. More...

std::pair< IndexMap, std::vector< std::int32_t > >	create_submap (const std::span< const std::int32_t > &indices) const
	Create new index map from a subset of indices in this index map. More...

graph::AdjacencyList< int >	index_to_dest_ranks () const
	Compute map from each local (owned) index to the set of ranks that have the index as a ghost. More...

std::vector< std::int32_t >	shared_indices () const
	Build a list of owned indices that are ghosted by another rank. More...

const std::vector< int > &	src () const noexcept
	Ordered set of MPI ranks that own caller's ghost indices. More...

const std::vector< int > &	dest () const noexcept
	Ordered set of MPI ranks that ghost indices owned by caller. More...

bool	overlapped () const noexcept
	Check if index map has overlaps (ghosts on any rank). More...

Detailed Description

This class represents the distribution index arrays across processes. An index array is a contiguous collection of N+1 indices [0, 1, . . ., N] that are distributed across M processes. On a given process, the IndexMap stores a portion of the index set using local indices [0, 1, . . . , n], and a map from the local indices to a unique global index.

Constructor & Destructor Documentation

◆ IndexMap() [1/3]

IndexMap	(	MPI_Comm	comm,
		std::int32_t	local_size
	)

Create an non-overlapping index map.

Note: Collective

Parameters

[in]	comm	The MPI communicator
[in]	local_size	Local size of the index map, i.e. the number of owned entries

◆ IndexMap() [2/3]

IndexMap	(	MPI_Comm	comm,
		std::int32_t	local_size,
		const std::span< const std::int64_t > &	ghosts,
		const std::span< const int > &	owners
	)

Create an overlapping (ghosted) index map.

This constructor uses a 'consensus' algorithm to determine the ranks that ghost indices that are owned by the caller. This requires non-trivial MPI communication. If the ranks that ghost indices owned by the caller are known, it more efficient to use the constructor that takes these ranks as an argument.

Note: Collective

Parameters

[in]	comm	The MPI communicator
[in]	local_size	Local size of the index map, i.e. the number of owned entries
[in]	ghosts	The global indices of ghost entries
[in]	owners	Owner rank (on global communicator) of each entry in `ghosts`

◆ IndexMap() [3/3]

IndexMap	(	MPI_Comm	comm,
		std::int32_t	local_size,
		const std::array< std::vector< int >, 2 > &	src_dest,
		const std::span< const std::int64_t > &	ghosts,
		const std::span< const int > &	owners
	)

Create an overlapping (ghosted) index map.

This constructor is optimised for the case where the 'source' (ranks that own indices ghosted by the caller) and 'destination' ranks (ranks that ghost indices owned by the caller) are already available. It allows the complex computation of the destination ranks from owners.

Note: Collective

Parameters

[in]	comm	The MPI communicator
[in]	local_size	Local size of the index map, i.e. the number
[in]	src_dest	Lists of [0] src and [1] dest ranks. The list in each must be sorted and not contain duplicates. `src` ranks are owners of the indices in `ghosts`. `dest` ranks are the rank that ghost indices owned by the caller.
[in]	ghosts	The global indices of ghost entries
[in]	owners	Owner rank (on global communicator) of each entry in `ghosts`

Member Function Documentation

◆ comm()

MPI_Comm comm ( ) const

Return the MPI communicator that the map is defined on.

Returns: Communicator

◆ create_submap()

std::pair< IndexMap, std::vector< std::int32_t > > create_submap ( const std::span< const std::int32_t > & indices ) const

Create new index map from a subset of indices in this index map.

The order of the owned indices is preserved, with new map effectively a 'compressed' map.

Parameters

[in] indices Local indices in the map that should appear in the new index map. All indices must be owned, i.e. indices must be less than this->size_local().

Precondition: indices must be sorted and contain no duplicates.

Returns: The (i) new index map and (ii) a map from the ghost position in the new map to the ghost position in the original (this) map

◆ dest()

const std::vector< int > & dest ( ) const

noexcept

Ordered set of MPI ranks that ghost indices owned by caller.

Typically used when creating neighbourhood communicators.

Returns: MPI ranks than own ghost indices. The ranks are unique and sorted.

◆ global_indices()

std::vector< std::int64_t > global_indices ( ) const

Build list of indices with global indexing.

Returns: The global index for all local indices (0, 1, 2, ...) on this process, including ghosts

◆ global_to_local()

void global_to_local	(	const std::span< const std::int64_t > &	global,
		const std::span< std::int32_t > &	local
	)		const

Compute local indices for array of global indices.

Parameters

[in]	global	Global indices
[out]	local	The local of the corresponding global index in 'global'. Returns -1 if the local index does not exist on this process.

◆ index_to_dest_ranks()

graph::AdjacencyList< int > index_to_dest_ranks ( ) const

Compute map from each local (owned) index to the set of ranks that have the index as a ghost.

Todo:: Aim to remove this function?

Returns: shared indices

◆ local_to_global()

void local_to_global	(	const std::span< const std::int32_t > &	local,
		const std::span< std::int64_t > &	global
	)		const

Compute global indices for array of local indices.

Parameters

[in]	local	Local indices
[out]	global	The global indices

◆ overlapped()

bool overlapped ( ) const

noexcept

Check if index map has overlaps (ghosts on any rank).

The return value of this function is determined by which constructor was used to create the index map.

Returns: True if index map has overlaps on any ranks, otherwise false.

◆ owners()

const std::vector<int>& owners ( ) const

inline

The ranks that own each ghost index.

Returns: List of ghost owners. The owning rank of the ith ghost index is owners()[i].

◆ shared_indices()

std::vector< std::int32_t > shared_indices ( ) const

Build a list of owned indices that are ghosted by another rank.

Returns: The local index of owned indices that are ghosts on other rank(s). The indicies are unique and sorted.

◆ src()

const std::vector< int > & src ( ) const

noexcept

Ordered set of MPI ranks that own caller's ghost indices.

Typically used when creating neighbourhood communicators.

Returns: MPI ranks than own ghost indices. The ranks are unique and sorted.

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

/__w/dolfinx/dolfinx/cpp/dolfinx/common/IndexMap.h
/__w/dolfinx/dolfinx/cpp/dolfinx/common/IndexMap.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ IndexMap() [1/3]

◆ IndexMap() [2/3]

◆ IndexMap() [3/3]

Member Function Documentation

◆ comm()

◆ create_submap()

◆ dest()

◆ global_indices()

◆ global_to_local()

◆ index_to_dest_ranks()

◆ local_to_global()

◆ overlapped()

◆ owners()

◆ shared_indices()

◆ src()