A Communicator which possesses an additional virtual topology and supports neighborhood collectives (on the topology). A virtual topology can be defined by a communication graph: each MPI rank corresponds to a vertex in the graph and an edge (i,j) defines a (directed) communication link from rank i to rank j. Such a topolgy can be used to model frequent (sparse) communication patterns and there are specialized (neighborhood) collective operations, e.g., MPI_Neighbor_alltoall etc., exploiting this structure. More...

#include <topology_communicator.hpp>

Inheritance diagram for kamping::TopologyCommunicator< DefaultContainerType, Plugins >:

[legend]

Collaboration diagram for kamping::TopologyCommunicator< DefaultContainerType, Plugins >:

[legend]

Public Types
template<typename... Args>
using	default_container_type = DefaultContainerType<Args...>
	Type of the default container type to use for containers created inside operations of this communicator.

Public Types inherited from kamping::Communicator< DefaultContainerType, Plugins >
template<typename... Args>
using	default_container_type = DefaultContainerType<Args...>
	Type of the default container type to use for containers created inside operations of this communicator.

Public Member Functions
size_t	in_degree () const
	Returns the in degree of the process' rank, i.e. the number of in-going edges/communication links towards the rank.

int	in_degree_signed () const
	Returns the in degree of the process' rank, i.e. the number of in-going edges/communication links towards the rank.

size_t	out_degree () const
	Returns the out degree of the process' rank, i.e. the number of out-going edges/communication links starting at the rank.

int	out_degree_signed () const
	Returns the out degree of the process' rank, i.e. the number of out-going edges/communication links starting at the rank.

template<typename... Args>
auto	neighbor_alltoall (Args... args) const
	Wrapper for `MPI_Neighbor_alltoall`.

Public Member Functions inherited from kamping::Communicator< DefaultContainerType, Plugins >
	Communicator ()
	Default constructor not specifying any MPI communicator and using `MPI_COMM_WORLD` by default.

	Communicator (MPI_Comm comm, bool take_ownership=false)
	Constructor where an MPI communicator has to be specified.

	Communicator (MPI_Comm comm, int root, bool take_ownership=false)
	Constructor where an MPI communicator and the default root have to be specified.

	Communicator (Communicator const &other)
	Copy constructor that duplicates the MPI_Comm and takes ownership of the newly created one in the copy.

	Communicator (Communicator &&other)
	Move constructor.

virtual	~Communicator ()
	Destructor that frees the contained `MPI_Comm` if it is owned by the Communicator.

Communicator &	operator= (Communicator &&other)
	Move assignment operator.

Communicator &	operator= (Communicator const &other)
	Copy assignment operator. Behaves according to the copy constructor.

void	swap (Communicator &other)
	Swaps the Communicator with another Communicator.

void	abort (int errorcode=1) const
	Terminates MPI execution environment (on all processes in this Communicator). Beware of MPI implementations who might terminate all processes, whether they are in this communicator or not.

int	rank_signed () const
	Rank of the current MPI process in the communicator as `int`.

size_t	rank () const
	Rank of the current MPI process in the communicator as `size_t`.

int	size_signed () const
	Number of MPI processes in this communicator as `int`.

size_t	size () const
	Number of MPI processes in this communicator as `size_t`.

size_t	num_numa_nodes () const
	Number of NUMA nodes (different shared memory regions) in this communicator. This operation is expensive (communicator splitting and communication). You should cache the result if you need it multiple times.

std::string	processor_name () const
	Get this 'processor's' name using `MPI_Get_processor_name`.

MPI_Comm	mpi_communicator () const
	MPI communicator corresponding to this communicator.

MPI_Comm	disown_mpi_communicator ()
	Disowns the wrapped MPI_Comm, i.e. it will not be freed in the destructor.

void	default_tag (int const default_tag)
	Set a new default tag used in point to point communication. The initial value is 0.

int	default_tag () const
	Default tag used in point to point communication. The initial value is 0.

void	root (int const new_root)
	Set a new root for MPI operations that require a root.

void	root (size_t const new_root)
	Set a new root for MPI operations that require a root.

size_t	root () const
	Default root for MPI operations that require a root as `size_t`.

int	root_signed () const
	Default root for MPI operations that require a root as `int`.

bool	is_root (int const root) const
	Check if this rank is the root rank.

bool	is_root (size_t const root) const
	Check if this rank is the root rank.

bool	is_root () const
	Check if this rank is the root rank.

Communicator	split (int const color, int const key=0) const
	Split the communicator in different colors.

Communicator	split_by_type (int const type) const
	Split the communicator by the specified type (e.g., shared memory)

Communicator	split_to_shared_memory () const
	Split the communicator into NUMA nodes.

Group	group () const
	Return the group associated with this communicator.

template<typename Ranks >
Communicator	create_subcommunicators (Ranks const &ranks_in_own_group) const
	Create subcommunicators.

Communicator	create_subcommunicators (RankRanges const &rank_ranges) const
	Create (sub-)communicators using a sparse representation for the ranks contained in the subcommunicators.

CommunicatorComparisonResult	compare (Communicator const &other_comm) const
	Compare this communicator with another given communicator. Uses `MPI_Comm_compare` internally.

int	convert_rank_to_communicator (int const rank, Communicator const &other_comm) const
	Convert a rank from this communicator to the rank in another communicator.

int	convert_rank_from_communicator (int const rank, Communicator const &other_comm) const
	Convert a rank from another communicator to the rank in this communicator.

size_t	rank_shifted_checked (int const distance) const
	Computes a rank that is `distance` ranks away from this MPI thread's current rank and checks if this is valid rank in this communicator.

size_t	rank_shifted_cyclic (int const distance) const
	Computes a rank that is some ranks apart from this MPI thread's rank modulo the communicator's size.

bool	is_valid_rank (int const rank) const
	Checks if a rank is a valid rank for this communicator, i.e., if the rank is in [0, size).

bool	is_valid_rank (size_t const rank) const
	Checks if a rank is a valid rank for this communicator, i.e., if the rank is in [0, size).

void	mpi_error_hook (int const error_code, std::string const &callee) const
	If `error_code != MPI_SUCCESS`, searchs the plugins for a public `mpi_error_handler(const int error_code, std::string& callee)` member. Searches the plugins front to back and calls the first handler found. If no handler is found, calls the default error hook. If error code is `MPI_SUCCESS`, does nothing.

void	mpi_error_default_handler (int const error_code, std::string const &function_name) const
	Default MPI error callback. Depending on `KASSERT_EXCEPTION_MODE` either throws a MpiErrorException if `error_code` != `MPI_SUCCESS` or fails an assertion.

template<typename... Args>
void	send (Args... args) const

template<typename... Args>
void	bsend (Args... args) const
	Convenience wrapper for MPI_Bsend. Calls kamping::Communicator::send() with the appropriate send mode set.

template<typename... Args>
void	ssend (Args... args) const
	Convenience wrapper for MPI_Ssend. Calls kamping::Communicator::send() with the appropriate send mode set.

template<typename... Args>
void	rsend (Args... args) const
	Convenience wrapper for MPI_Rsend. Calls kamping::Communicator::send() with the appropriate send mode set.

template<typename... Args>
auto	isend (Args... args) const

template<typename... Args>
auto	ibsend (Args... args) const
	Convenience wrapper for MPI_Ibsend. Calls kamping::Communicator::isend() with the appropriate send mode set.

template<typename... Args>
auto	issend (Args... args) const
	Convenience wrapper for MPI_Issend. Calls kamping::Communicator::isend() with the appropriate send mode set.

template<typename... Args>
auto	irsend (Args... args) const
	Convenience wrapper for MPI_Irsend. Calls kamping::Communicator::isend() with the appropriate send mode set.

template<typename... Args>
auto	probe (Args... args) const

template<typename... Args>
auto	iprobe (Args... args) const

template<typename recv_value_type_tparam = kamping::internal::unused_tparam, typename... Args>
auto	recv (Args... args) const

template<typename recv_value_type_tparam , typename... Args>
auto	recv_single (Args... args) const
	Convience wrapper for receiving single values via `MPI_Recv`.

template<typename recv_value_type_tparam = kamping::internal::unused_tparam, typename... Args>
auto	try_recv (Args... args) const

template<typename recv_value_type_tparam = kamping::internal::unused_tparam, typename... Args>
auto	irecv (Args... args) const

template<typename... Args>
auto	alltoall (Args... args) const
	Wrapper for `MPI_Alltoall`.

template<typename... Args>
auto	alltoall_inplace (Args... args) const
	Wrapper for the in-place version of Communicator::alltoall.

template<typename... Args>
auto	alltoallv (Args... args) const
	Wrapper for `MPI_Alltoallv`.

template<typename recv_value_type_tparam = kamping::internal::unused_tparam, typename... Args>
auto	scatter (Args... args) const

template<typename recv_value_type_tparam = kamping::internal::unused_tparam, typename... Args>
auto	scatter_single (Args... args) const

template<typename recv_value_type_tparam = kamping::internal::unused_tparam, typename... Args>
auto	scatterv (Args... args) const
	Wrapper for `MPI_Scatterv`.

template<typename... Args>
auto	reduce (Args... args) const

template<typename... Args>
auto	reduce_single (Args... args) const
	Wrapper for `MPI_Reduce`.

template<typename... Args>
auto	scan (Args... args) const

template<typename... Args>
auto	scan_inplace (Args... args) const
	Wrapper for the in-place version of Communicator::scan().

template<typename... Args>
auto	scan_single (Args... args) const
	Wrapper for `MPI_Scan` for single elements.

template<typename... Args>
auto	exscan (Args... args) const
	Wrapper for `MPI_Exscan`.

template<typename... Args>
auto	exscan_inplace (Args... args) const
	Wrapper for the in-place version of Communicator::exscan().

template<typename... Args>
auto	exscan_single (Args... args) const
	Wrapper for `MPI_exscan` for single elements.

template<typename... Args>
auto	allreduce (Args... args) const
	Wrapper for `MPI_Allreduce`; which is semantically a reduction followed by a broadcast.

template<typename... Args>
auto	allreduce_inplace (Args... args) const
	Wrapper for the in-place version of Communicator::allreduce().

template<typename... Args>
auto	allreduce_single (Args... args) const
	Wrapper for `MPI_Allreduce`; which is semantically a reduction followed by a broadcast.

template<typename... Args>
auto	iallreduce (Args... args) const
	Wrapper for `MPI_Iallreduce`.

template<typename... Args>
auto	gather (Args... args) const
	Wrapper for `MPI_Gather`.

template<typename... Args>
auto	gatherv (Args... args) const
	Wrapper for `MPI_Gatherv`.

template<typename... Args>
auto	allgather (Args... args) const
	Wrapper for `MPI_Allgather`.

template<typename... Args>
auto	allgather_inplace (Args... args) const
	Wrapper for the in-place version of `MPI_Allgather`.

template<typename... Args>
auto	allgatherv (Args... args) const
	Wrapper for `MPI_Allgatherv`.

template<typename recv_value_type_tparam = kamping::internal::unused_tparam, typename... Args>
auto	bcast (Args... args) const
	Wrapper for `MPI_Bcast`.

template<typename recv_value_type_tparam = kamping::internal::unused_tparam, typename... Args>
auto	bcast_single (Args... args) const
	Wrapper for `MPI_Bcast`.

template<typename... Args>
void	barrier (Args... args) const
	Perform a `MPI_Barrier` on this communicator.

template<typename... Args>
auto	ibarrier (Args... args) const
	Perform a non-blocking barrier synchronization on this communicator using `MPI_Ibarrier`. The call is associated with a kamping::Request (either allocated by KaMPIng or provided by the user). Only when the request has completed, it is guaranteed that all ranks have reached the barrier.

template<typename Value >
bool	is_same_on_all_ranks (Value const &value) const
	Checks if all ranks provide the same value to this collective.

Protected Member Functions
	TopologyCommunicator (size_t in_degree, size_t out_degree)
	topolgy constructor using `MPI_COMM_WORLD` by default.

	TopologyCommunicator (size_t in_degree, size_t out_degree, MPI_Comm comm, bool take_ownership=false)
	topolgy constructor where an MPI communicator has to be specified.

	TopologyCommunicator (size_t in_degree, size_t out_degree, MPI_Comm comm, int root, bool take_ownership=false)
	topolgy constructor where an MPI communicator and the default root rank have to be specified.

Additional Inherited Members
Protected Attributes inherited from kamping::Communicator< DefaultContainerType, Plugins >
size_t	_rank
	Rank of the MPI process in this communicator.

size_t	_size
	Number of MPI processes in this communicator.

MPI_Comm	_comm
	Corresponding MPI communicator.

size_t	_root
	Default root for MPI operations that require a root.

int	_default_tag
	Default tag value used in point to point communication.

bool	_owns_mpi_comm

Detailed Description

template<template< typename... > typename DefaultContainerType = std::vector, template< typename, template< typename... > typename > typename... Plugins>
class kamping::TopologyCommunicator< DefaultContainerType, Plugins >

A Communicator which possesses an additional virtual topology and supports neighborhood collectives (on the topology). A virtual topology can be defined by a communication graph: each MPI rank corresponds to a vertex in the graph and an edge (i,j) defines a (directed) communication link from rank i to rank j. Such a topolgy can be used to model frequent (sparse) communication patterns and there are specialized (neighborhood) collective operations, e.g., MPI_Neighbor_alltoall etc., exploiting this structure.

Template Parameters

DefaultContainerType	The default container type to use for containers created by KaMPIng. Defaults to std::vector.
Plugins	Plugins adding functionality to KaMPIng. Plugins should be classes taking a `Communicator` template parameter and can assume that they are castable to `Communicator` from which they can call any function of `kamping::Communicator`. See `test/plugin_tests.cpp` for examples.

Member Typedef Documentation

◆ default_container_type

template<template< typename... > typename DefaultContainerType = std::vector, template< typename, template< typename... > typename > typename... Plugins>

template<typename... Args>

using kamping::TopologyCommunicator< DefaultContainerType, Plugins >::default_container_type = DefaultContainerType<Args...>

Type of the default container type to use for containers created inside operations of this communicator.

Template Parameters

Args	Arguments to the container type.

Constructor & Destructor Documentation

◆ TopologyCommunicator() [1/3]

template<template< typename... > typename DefaultContainerType = std::vector, template< typename, template< typename... > typename > typename... Plugins>

kamping::TopologyCommunicator< DefaultContainerType, Plugins >::TopologyCommunicator	(	size_t	in_degree,
		size_t	out_degree )

inlineprotected

topolgy constructor using MPI_COMM_WORLD by default.

Parameters

in_degree	In degree of the process' rank in the underlying communication graph.
out_degree	Out degree of the process' rank in the underlying communication graph.

◆ TopologyCommunicator() [2/3]

template<template< typename... > typename DefaultContainerType = std::vector, template< typename, template< typename... > typename > typename... Plugins>

kamping::TopologyCommunicator< DefaultContainerType, Plugins >::TopologyCommunicator	(	size_t	in_degree,
		size_t	out_degree,
		MPI_Comm	comm,
		bool	take_ownership = false )

inlineexplicitprotected

topolgy constructor where an MPI communicator has to be specified.

Parameters

in_degree	In degree of the process' rank in the underlying communication graph.
out_degree	Out degree of the process' rank in the underlying communication graph.
comm	MPI communicator that is wrapped by this `Communicator`.
take_ownership	Whether the Communicator should take ownership of comm, i.e. free it in the destructor.

◆ TopologyCommunicator() [3/3]

template<template< typename... > typename DefaultContainerType = std::vector, template< typename, template< typename... > typename > typename... Plugins>

kamping::TopologyCommunicator< DefaultContainerType, Plugins >::TopologyCommunicator	(	size_t	in_degree,
		size_t	out_degree,
		MPI_Comm	comm,
		int	root,
		bool	take_ownership = false )

inlineexplicitprotected

topolgy constructor where an MPI communicator and the default root rank have to be specified.

Parameters

in_degree	In degree of the process' rank in the underlying communication graph.
out_degree	Out degree of the process' rank in the underlying communication graph.
comm	MPI communicator that is wrapped by this `Communicator`.
root	Default root that is used by MPI operations requiring a root.
take_ownership	Whether the Communicator should take ownership of comm, i.e. free it in the destructor.

Member Function Documentation

◆ in_degree()

template<template< typename... > typename DefaultContainerType = std::vector, template< typename, template< typename... > typename > typename... Plugins>

size_t kamping::TopologyCommunicator< DefaultContainerType, Plugins >::in_degree ( ) const

inline

Returns the in degree of the process' rank, i.e. the number of in-going edges/communication links towards the rank.

Returns: Number of in-going edges as unsigned integer.

◆ in_degree_signed()

template<template< typename... > typename DefaultContainerType = std::vector, template< typename, template< typename... > typename > typename... Plugins>

int kamping::TopologyCommunicator< DefaultContainerType, Plugins >::in_degree_signed ( ) const

inline

Returns the in degree of the process' rank, i.e. the number of in-going edges/communication links towards the rank.

Returns: Number of in-going edges as signed integer.

◆ out_degree()

template<template< typename... > typename DefaultContainerType = std::vector, template< typename, template< typename... > typename > typename... Plugins>

size_t kamping::TopologyCommunicator< DefaultContainerType, Plugins >::out_degree ( ) const

inline

Returns the out degree of the process' rank, i.e. the number of out-going edges/communication links starting at the rank.

Returns: Number of out-going edges as unsigned integer.

◆ out_degree_signed()

template<template< typename... > typename DefaultContainerType = std::vector, template< typename, template< typename... > typename > typename... Plugins>

int kamping::TopologyCommunicator< DefaultContainerType, Plugins >::out_degree_signed ( ) const

inline

Returns the out degree of the process' rank, i.e. the number of out-going edges/communication links starting at the rank.

Returns: Number of out-going edges as signed integer.

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

include/kamping/topology_communicator.hpp
include/kamping/collectives/neighborhood/alltoall.hpp

Public Types

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ default_container_type

Constructor & Destructor Documentation

◆ TopologyCommunicator() [1/3]

◆ TopologyCommunicator() [2/3]

◆ TopologyCommunicator() [3/3]

Member Function Documentation

◆ in_degree()

◆ in_degree_signed()

◆ out_degree()

◆ out_degree_signed()