Miscellaneous classes, functions and types. More...

Namespaces
namespace	petsc
	PETSc error handling helpers shared across DOLFINx's PETSc wrappers.

Classes
class	IndexMap
	Distribution of a global index range [0, N) across MPI ranks. More...
class	Scatterer
	A Scatterer supports the scattering and gathering of distributed data that is associated with a common::IndexMap, using MPI. More...
class	TimeLogger
	Time logger maintaining data collected by Timer, if registered. More...
class	Timer
	Timer for measuring and logging elapsed time durations. More...

Concepts
concept	LocalIndexRange
	Concept for a contiguous list of process-local indices, e.g. the row or column indices passed to a matrix set function.

Enumerations
enum class	IndexMapOrder : bool { preserve = true , any = false }
	Control ghost-index ordering in sub-index maps. More...

Functions
std::vector< std::int32_t >	compute_owned_indices (std::span< const std::int32_t > indices, const IndexMap &map)
	Return selected indices owned by the calling rank.
std::tuple< std::int64_t, std::vector< std::int32_t >, std::vector< std::vector< std::int64_t > >, std::vector< std::vector< int > > >	stack_index_maps (const std::vector< std::pair< std::reference_wrapper< const IndexMap >, int > > &maps)
	Compute layout data for a concatenated index map.
std::vector< std::int32_t >	num_sharing_ranks (const IndexMap &map, std::span< const std::int32_t > indices, int bs)
	Number of ranks that share each of the given local indices.
std::tuple< IndexMap, std::vector< std::int32_t >, bool >	create_sub_index_map (const IndexMap &imap, std::span< const std::int32_t > indices, IndexMapOrder order=IndexMapOrder::any)
	Create an index map from a subset of an existing map.
std::tuple< std::vector< int >, std::vector< int >, std::vector< std::int32_t > >	compute_sharing_neighbourhood (const IndexMap &imap)
	Compute the symmetric neighbourhood of ranks that share an owned or ghost index with the caller.
constexpr std::array< std::int64_t, 2 >	local_range (int index, std::int64_t N, int size)
	Partition a global range [0, N - 1] across callers into non-overlapping sub-partitions of almost equal size. Returns the local partition for the caller. The local partition range.
template<class Container>
std::vector< std::int32_t >	num_sharing_ranks (const IndexMap &map, const Scatterer< Container > &sc, std::span< const std::int32_t > indices, int bs)
	Number of ranks that share each of the given local indices, reusing an existing Scatterer.
template<std::ranges::input_range U, std::ranges::input_range V>
std::pair< std::vector< typename U::value_type >, std::vector< typename V::value_type > >	sort_unique (const U &indices, const V &values)
	Sort two arrays based on the values in array indices.
template<class T>
std::size_t	hash_local (const T &x)
	Compute a hash of a given object.
template<class T>
std::size_t	hash_global (MPI_Comm comm, const T &x)
	Compute a hash for a distributed (MPI) object.

Detailed Description

Miscellaneous classes, functions and types.

Generic tools.

This namespace provides utility type functions for managing subsystems, convenience classes and library-wide typedefs.

Enumeration Type Documentation

◆ IndexMapOrder

enum class IndexMapOrder : bool

strong

Control ghost-index ordering in sub-index maps.

Enumerator
preserve	Preserve the ordering of ghost indices.
any	Allow arbitrary ghost-index ordering.

Function Documentation

◆ compute_owned_indices()

std::vector< int32_t > compute_owned_indices	(	std::span< const std::int32_t >	indices,
		const IndexMap &	map )

Return selected indices owned by the calling rank.

Includes locally owned entries in indices and entries selected as ghosts on other ranks.

For example, on two ranks, suppose rank 0 owns global indices [0, 1] and has global index 2 as local ghost index 2, while rank 1 owns global indices [2, 3] and has global index 1 as local ghost index 2. If both ranks pass local index [2], the results are [1] on rank 0 and [0] on rank 1: each owns the global index selected as a ghost by the other rank.

Note: Collective

Parameters

[in]	indices	Sorted unique local indices (owned or ghost) in [0, map.size_local() + map.num_ghosts()).
[in]	map	The index map.

Precondition: indices is sorted, unique, and in range. This condition is checked in Developer builds; callers must ensure it in Release builds.

Returns: Local indices owned by the calling rank.

Exceptions

std::invalid_argument If the indices precondition is violated in a Developer build.

◆ compute_sharing_neighbourhood()

std::tuple< std::vector< int >, std::vector< int >, std::vector< std::int32_t > > compute_sharing_neighbourhood ( const IndexMap & imap )

Compute the symmetric neighbourhood of ranks that share an owned or ghost index with the caller.

A rank shares a local index with the caller if it also holds the index, as owner or ghost. For an owned index, the sharing ranks are the ranks that ghost it. For a ghost index, they are its owner and the other ranks that ghost it; the latter need not be in IndexMap::src or IndexMap::dest.

The in-neighbourhood IndexMap::src (owners of the caller's ghosts) and the out-neighbourhood IndexMap::dest (ranks ghosting the caller's owned indices) differ in general. Sharing is symmetric: rank a shares an index with rank b if and only if b shares it with a. The returned ranks can therefore be both the sources and the destinations of a neighbourhood communicator.

Example on four ranks, where | separates owned and ghost entries:

rank 0: local [0, 1]    | [2]    -> global [0, 1]    | [2]    (owner 1)
rank 1: local [0, 1, 2] | [3]    -> global [2, 3, 4] | [6]    (owner 2)
rank 2: local [0, 1]    | [2]    -> global [5, 6]    | [2]    (owner 1)
rank 3: local [0]       | [1, 2] -> global [7]       | [1, 5] (owners 0, 2)

The return values are:

        src     dest    unique_ranks  data          offsets
rank 0: [1]     [3]     [1, 2, 3]     [2, 0, 1]     [0, 0, 1, 3]
rank 1: [2]     [0, 2]  [0, 2]        [0, 1, 1]     [0, 2, 2, 2, 3]
rank 2: [1]     [1, 3]  [0, 1, 3]     [2, 1, 0, 1]  [0, 1, 2, 4]
rank 3: [0, 2]  []      [0, 2]        [0, 1]        [0, 0, 1, 2]

Ranks 0 and 2 share global index 2, which both ghost, although neither is in the other's IndexMap::src or IndexMap::dest. Rank 3 is in IndexMap::dest of ranks 0 and 2, but its own IndexMap::dest is empty. On rank 0, local index 1 occupies entry [offsets[1], offsets[2]) = [0, 1) of data, whose value 2 is the position of rank 3 in unique_ranks.

Note: Collective.

Parameters

[in] imap Index map.

Returns: (0) unique_ranks: sorted ranks, other than the caller, that share at least one index with the caller. (1) data and (2) offsets: adjacency list from each local index to the ranks sharing it, given as positions in (0). offsets has imap.size_local() + imap.num_ghosts() + 1 entries, and the ranks sharing local index i occupy [offsets[i], offsets[i + 1]) of data. data() of (0) is not null, as required by some MPI implementations, even if (0) is empty.

◆ create_sub_index_map()

std::tuple< IndexMap, std::vector< std::int32_t >, bool > create_sub_index_map	(	const IndexMap &	imap,
		std::span< const std::int32_t >	indices,
		IndexMapOrder	order = IndexMapOrder::any )

Create an index map from a subset of an existing map.

Note: Collective

Parameters

[in]	imap	Parent map to create a new sub-map from.
[in]	indices	Local indices in imap (owned and ghost) to include in the new index map.
[in]	order	Control the order in which ghost indices appear in the new map.

Precondition: indices contains unique local indices in range. This condition is checked in Developer builds; callers must ensure it in Release builds.

Returns: (0) New index map, (1) corresponding local indices in imap, and (2) whether any index acquired a new owner in the submap. An index selected only by ghosting ranks, and not by its owner, is given a new owner in the submap; (2) reports whether this happened.

Note: (2) is rank-local and is not reduced: it can be true on some ranks and false on others. A caller that requires ownership to be preserved must reduce it (e.g. MPI_Allreduce with MPI_LOR) before acting on it, since throwing on only some ranks would leave the others in a subsequent collective.

Exceptions

std::invalid_argument If the indices precondition is violated in a Developer build.

◆ hash_global()

template<class T>

std::size_t hash_global	(	MPI_Comm	comm,
		const T &	x )

Compute a hash for a distributed (MPI) object.

A hash is computed on each process for the local part of the object. Then, a hash of the std::vector containing each local hash key in rank order is returned.

Note: Collective

Parameters

[in]	comm	The communicator on which to compute the hash.
[in]	x	The object to compute a hash of.

Returns: The hash values.

◆ hash_local()

template<class T>

std::size_t hash_local ( const T & x )

Compute a hash of a given object.

The hash is computed using Boost container hash (https://www.boost.org/doc/libs/release/libs/container_hash/).

Parameters

[in] x The object to compute a hash of.

Returns: The hash values.

◆ local_range()

std::array< std::int64_t, 2 > local_range	(	int	index,
		std::int64_t	N,
		int	size )

constexpr

Partition a global range [0, N - 1] across callers into non-overlapping sub-partitions of almost equal size. Returns the local partition for the caller. The local partition range.

Partitions [0, N) into size non-overlapping partitions [n_(i0}, n_(i1)), where i is index and n_(i1) == n_((i+1)0).

Parameters

[in]	index	Index of the partition to compute.
[in]	N	Global range to partition.
[in]	size	Number of partitions into which to partition N.

◆ num_sharing_ranks() [1/2]

template<class Container>

std::vector< std::int32_t > num_sharing_ranks	(	const IndexMap &	map,
		const Scatterer< Container > &	sc,
		std::span< const std::int32_t >	indices,
		int	bs )

Number of ranks that share each of the given local indices, reusing an existing Scatterer.

Equivalent to the IndexMap overload, but avoids building a Scatterer, which duplicates MPI communicators.

Note: Collective. Arguments must be locally valid on every rank. Invalid input on only some ranks may deadlock.

Parameters

[in]	map	Index map describing the parallel layout.
[in]	sc	Scatterer for map.
[in]	indices	Local indices, which may include ghosts. An index refers to block i / bs of map.
[in]	bs	Block size relating indices to the blocks of map.

Returns: Number of sharing ranks, one entry per entry of indices.

Exceptions

std::invalid_argument	If bs is less than one.
std::out_of_range	If an entry of indices is not a local index of map.

◆ num_sharing_ranks() [2/2]

std::vector< std::int32_t > num_sharing_ranks	(	const IndexMap &	map,
		std::span< const std::int32_t >	indices,
		int	bs )

Number of ranks that share each of the given local indices.

A rank shares an index if it owns it or ghosts it, so the count is one for an index that is not on a subdomain boundary, and the sum of the counts over all ranks that hold an index is the same on each of them.

Note: Collective. Arguments must be locally valid on every rank. Invalid input on only some ranks may deadlock.

Parameters

[in]	map	Index map describing the parallel layout.
[in]	indices	Local indices, which may include ghosts. An index refers to block i / bs of map.
[in]	bs	Block size relating indices to the blocks of map.

Returns: Number of sharing ranks, one entry per entry of indices.

Exceptions

std::invalid_argument	If bs is less than one.
std::out_of_range	If an entry of indices is not a local index of map.

Note: An overload taking an existing Scatterer is declared in Scatterer.h, and avoids building one here.

◆ sort_unique()

template<std::ranges::input_range U, std::ranges::input_range V>

std::pair< std::vector< typename U::value_type >, std::vector< typename V::value_type > > sort_unique	(	const U &	indices,
		const V &	values )

Sort two arrays based on the values in array indices.

Any duplicate indices and the corresponding value are removed. In the case of duplicates, the entry with the smallest value is retained.

Parameters

[in]	indices	Array of indices.
[in]	values	Array of values.

Returns: Sorted (indices, values), with sorting based on indices.

◆ stack_index_maps()

std::tuple< std::int64_t, std::vector< std::int32_t >, std::vector< std::vector< std::int64_t > >, std::vector< std::vector< int > > > stack_index_maps ( const std::vector< std::pair< std::reference_wrapper< const IndexMap >, int > > & maps )

Compute layout data for a concatenated index map.

Locally owned entries remain owned by the caller. Ghost entries are grouped by input map in maps.

Note: Collective. Maps with a block size are unrolled.

Parameters

[in] maps Non-empty pairs of index maps and positive block sizes. All maps must use the same communicator.

Precondition: All ranks supply corresponding maps in the same order.

Returns: (0) Global offset on the calling rank, (1) local offsets for owned entries in each map, (2) global ghost indices for each map, and (3) their owner ranks.

Namespaces

Classes

Concepts

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ IndexMapOrder

Function Documentation

◆ compute_owned_indices()

◆ compute_sharing_neighbourhood()

◆ create_sub_index_map()

◆ hash_global()

◆ hash_local()

◆ local_range()

◆ num_sharing_ranks() [1/2]

◆ num_sharing_ranks() [2/2]

◆ sort_unique()

◆ stack_index_maps()