IndexMap Class Reference

Distribution of a global index range [0, N) across MPI ranks. More...

#include <IndexMap.h>

Public Member Functions
	IndexMap (MPI_Comm comm, std::int32_t local_size)
	Create a non-overlapping index map.
	IndexMap (MPI_Comm comm, std::int32_t local_size, std::span< const std::int64_t > ghosts, std::span< const int > owners, int tag=static_cast< int >(dolfinx::MPI::tag::consensus_nbx))
	Create an overlapping (ghosted) index map.
	IndexMap (MPI_Comm comm, std::int32_t local_size, const std::array< std::vector< int >, 2 > &src_dest, std::span< const std::int64_t > ghosts, std::span< const int > owners)
	Create an overlapping (ghosted) index map.
	IndexMap (const IndexMap &map)=delete
	IndexMap (IndexMap &&map)=default
	Move constructor.
	~IndexMap ()=default
	Destructor.
IndexMap &	operator= (const IndexMap &map)=delete
IndexMap &	operator= (IndexMap &&map)=default
	Move assignment.
std::array< std::int64_t, 2 >	local_range () const noexcept
	Return the global range of owned indices.
std::int32_t	num_ghosts () const noexcept
	Return the number of ghost indices.
std::int32_t	size_local () const noexcept
	Return the number of owned indices.
std::int64_t	size_global () const noexcept
	Return the total number of indices across the communicator.
std::span< const std::int64_t >	ghosts () const noexcept
	Return global indices of ghosts in local ghost-index order.
MPI_Comm	comm () const
	Return the communicator that the map is defined on.
void	local_to_global (std::span< const std::int32_t > local, std::span< std::int64_t > global) const
	Compute global indices for local indices.
void	global_to_local (std::span< const std::int64_t > global, std::span< std::int32_t > local) const
	Compute local indices for global indices.
std::vector< std::int64_t >	global_indices () const
	Return global indices for all local entries, including ghosts.
std::span< const int >	owners () const noexcept
	Return ranks that own ghost entries.
std::pair< std::vector< int >, std::vector< std::int32_t > >	index_to_dest_ranks (int tag=static_cast< int >(dolfinx::MPI::tag::consensus_nbx)) const
	Compute sharing ranks for each local index.
std::vector< std::int32_t >	shared_indices () const
	Return owned indices ghosted by another rank.
std::span< const int >	src () const noexcept
	Return sorted unique ranks that own the caller's ghosts.
std::span< const int >	dest () const noexcept
	Return sorted unique ranks that ghost entries owned by the caller.
std::vector< std::int32_t >	weights_src () const
	Count the caller's ghosts owned by each source rank.
std::vector< std::int32_t >	weights_dest () const
	Count the caller's owned entries ghosted by each destination rank.
std::array< std::vector< int >, 2 >	rank_type (int split_type) const
	Return neighbours in the caller's MPI split-type group.

Detailed Description

Distribution of a global index range [0, N) across MPI ranks.

Each rank owns a contiguous global range. Local indices in [0, size_local()) address owned entries; remaining local indices address ghost entries.

Constructor & Destructor Documentation

IndexMap() [1/3]

IndexMap	(	MPI_Comm	comm,
		std::int32_t	local_size )

Create a non-overlapping index map.

For example, if rank 0 has local_size = 2 and rank 1 has local_size = 3, the layout is:

rank 0: local [0, 1]    -> global [0, 1]
rank 1: local [0, 1, 2] -> global [2, 3, 4]

Note

Collective

Parameters

[in]	comm	Communicator that the index map is distributed across.
[in]	local_size	Number of owned entries. Must be non-negative.

Precondition

Every rank in this collective call supplies a non-negative local_size. A violation on only some ranks may deadlock in Release builds.

local_size is non-negative; this is always checked locally (no MPI communication).

Exceptions

std::invalid_argument

If local_size is negative.

IndexMap() [2/3]

IndexMap	(	MPI_Comm	comm,
		std::int32_t	local_size,
		std::span< const std::int64_t >	ghosts,
		std::span< const int >	owners,
		int	tag = static_cast<int>(dolfinx::MPI::tag::consensus_nbx) )

Create an overlapping (ghosted) index map.

Uses a consensus algorithm to determine ranks that ghost entries owned by the caller. Use the explicit source/destination constructor when these ranks are known.

For example, a two-rank map with one ghost on each rank has layout: Here, | separates owned and ghost entries.

rank 0: local [0, 1] | [2] -> global [0, 1] | [2] (owner 1)
rank 1: local [0, 1] | [2] -> global [2, 3] | [1] (owner 0)

Note

Collective

Parameters

[in]	comm	Communicator that the index map is distributed across.
[in]	local_size	Number of owned entries. Must be non-negative.
[in]	ghosts	Unique global indices of ghost entries.
[in]	owners	Non-self rank (on comm) that owns each entry in ghosts.
[in]	tag	Tag used in non-blocking MPI calls in the consensus algorithm.

Note

Use a distinct tag for overlapping consensus calls. All ranks in one collective call must use the same tag. An MPI barrier before and after the call is an alternative.

Precondition

Every rank in this collective call satisfies the locally checked preconditions below. A violation on only some ranks may deadlock in Release builds.

local_size is non-negative and ghosts and owners have equal length; these are always checked locally (no MPI communication). Ghosts must also be unique and non-negative, owners must be valid non-self ranks, and each ghost must be globally owned by its declared rank; these further conditions are checked in Developer builds only, and callers must ensure them in Release builds.

Exceptions

std::invalid_argument

If local_size is negative, if ghosts and owners differ in length, or if another ghost data precondition is violated in a Developer build.

IndexMap() [3/3]

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

Create an overlapping (ghosted) index map.

Use this constructor when source ranks (owners of the caller's ghosts) and destination ranks (ranks ghosting the caller's entries) are known.

For example, a two-rank map with one ghost on each rank has layout: Here, | separates owned and ghost entries.

rank 0: local [0, 1] | [2] -> global [0, 1] | [2] (owner 1)
rank 1: local [0, 1] | [2] -> global [2, 3] | [1] (owner 0)

Rank 0 has source rank 1 and destination rank 1, and conversely for rank 1.

Note

Collective

Parameters

[in]	comm	Communicator that the index map is distributed across.
[in]	local_size	Number of owned entries. Must be non-negative.
[in]	src_dest	Lists of (0) source and (1) destination ranks. Both lists must be sorted, unique and contain valid ranks. Source ranks must be exactly the unique owners of ghosts; destination ranks must be the ranks that ghost entries owned by the caller.
[in]	ghosts	Unique global indices of ghost entries.
[in]	owners	Non-self rank (on comm) that owns each entry in ghosts.

Precondition

Every rank in this collective call satisfies the locally checked preconditions below. A violation on only some ranks may deadlock in Release builds.

local_size is non-negative and ghosts and owners have equal length; these are always checked locally (no MPI communication). Ghosts must also be unique and non-negative, owners must be valid non-self ranks, and each ghost must be globally owned by its declared rank. For every pair of ranks (a, b), b must be in a's source list if and only if a is in b's destination list. These further conditions are checked in Developer builds only, and callers must ensure them in Release builds.

Exceptions

std::invalid_argument

If local_size is negative, if ghosts and owners differ in length, or if another ghost data precondition is violated in a Developer build.

Member Function Documentation

comm()

MPI_Comm comm

(

)

const

Return the communicator that the map is defined on.

Returns

Communicator

global_to_local()

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

Compute local indices for global indices.

Parameters

[in]	global	Global indices.
[out]	local	Local indices. Must have the same size as global. Entries without a local index are set to -1.

Exceptions

std::invalid_argument

If global and local differ in size.

index_to_dest_ranks()

std::pair< std::vector< int >, std::vector< std::int32_t > > index_to_dest_ranks

(

int

tag = static_cast<int>(dolfinx::MPI::tag::consensus_nbx)

)

const

Compute sharing ranks for each local index.

Note

Collective

Parameters

[in]

tag

Tag to pass to MPI calls.

Note

See IndexMap(MPI_Comm, std::int32_t, std::span<const std::int64_t>, std::span<const int>, int) for tag requirements.

Returns

(0) Sharing-rank data and (1) offsets. Ranks sharing local index i occupy [offsets[i], offsets[i + 1]).

local_to_global()

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

Compute global indices for local indices.

Parameters

[in]	local	Local indices in [0, size_local() + num_ghosts()).
[out]	global	Global indices. Must have at least the size of local.

Precondition

local is in range. This condition is checked in Developer builds; callers must ensure it in Release builds.

Exceptions

std::invalid_argument	If global is smaller than local.
std::out_of_range	If the local precondition is violated in a Developer build.

owners()

std::span< const int > owners ( ) const

inlinenoexcept

Return ranks that own ghost entries.

Returns

Owner ranks aligned with ghosts().

rank_type()

std::array< std::vector< int >, 2 > rank_type

(

int

split_type

)

const

Return neighbours in the caller's MPI split-type group.

Forms a communicator with MPI_Comm_split_type and restricts the caller's destination and source ranks to the resulting group. The destination ranks ghost entries owned by the caller; the source ranks own ghosts held by the caller. For example, with MPI_COMM_TYPE_SHARED, this identifies neighbouring ranks on the same shared-memory domain.

Note

Collective on comm().

Parameters

[in]

split_type

MPI split type passed to MPI_Comm_split_type, e.g. MPI_COMM_TYPE_SHARED.

Returns

(0) Destination ranks and (1) source ranks in the split-type group. Ranks are numbered on comm(), rather than on the split communicator.

shared_indices()

std::vector< std::int32_t > shared_indices

(

)

const

Return owned indices ghosted by another rank.

Note

Collective

Returns

Sorted unique local indices.

weights_dest()

std::vector< std::int32_t > weights_dest

(

)

const

Count the caller's owned entries ghosted by each destination rank.

The returned vector is aligned with dest(). Each value is the number of local owned entries ghosted by the corresponding destination rank.

Note

Collective

Returns

Number of entries ghosted by each destination rank.

weights_src()

std::vector< std::int32_t > weights_src

(

)

const

Count the caller's ghosts owned by each source rank.

The returned vector is aligned with src(). Each value is the number of local ghost entries whose owner is the corresponding source rank.

Returns

Number of ghosts owned by each source rank.

---

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