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

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

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

◆ 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

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ IndexMapOrder

Function Documentation

◆ compute_owned_indices()

◆ create_sub_index_map()

◆ hash_global()

◆ hash_local()

◆ local_range()

◆ sort_unique()

◆ stack_index_maps()