Class that sets up gathers and scatters for Tpetra communication. More...

#include <Tpetra_Distributor.hpp>

Inheritance diagram for Tpetra::Distributor:

Public Member Functions
Constructor/Destructor
	Distributor (const RCP< const Comm< int > > &comm)
	Construct the Distributor using the specified communicator.
	Distributor (const Distributor &distributor)
	Copy constructor.
	~Distributor ()
	Destructor.
Gather/Scatter Constructors
size_t	createFromSends (const ArrayView< const int > &exportNodeIDs)
	Set up Distributor using list of node IDs to which this node will send.
template<class Ordinal >
void	createFromRecvs (const ArrayView< const Ordinal > &remoteIDs, const ArrayView< const int > &remoteNodeIDs, ArrayRCP< Ordinal > &exportIDs, ArrayRCP< int > &exportNodeIDs)
	Set up Distributor using list of node IDs from which to receive.
Attribute Accessor Methods
size_t	getNumReceives () const
	The number of nodes from which we will receive data, not include this node ("myself").
size_t	getNumSends () const
	The number of nodes to which we will send data, not include this node ("myself").
bool	hasSelfMessage () const
	Indicates whether values are being sent to/recieved from this node.
size_t	getMaxSendLength () const
	Maximum number of values that this node is sending to another single node.
size_t	getTotalReceiveLength () const
	Total number of values that this nodes is receiving from other nodes.
ArrayView< const int >	getImagesFrom () const
	A list of images sending values to this node. (non-persisting view)
ArrayView< const int >	getImagesTo () const
	A list of images to which this node is sending values. (non-persisting view)
ArrayView< const size_t >	getLengthsFrom () const
	Number of values we're receiving from each node. (non-persisting view)
ArrayView< const size_t >	getLengthsTo () const
	Number of values we're sending to each node. (non-persisting view)
Reverse Communication Methods
const RCP< Distributor > &	getReverse () const
	Returns a Distributor with a reverse plan of this Distributor's plan.
Execute Distributor Plan Methods
template<class Packet >
void	doPostsAndWaits (const ArrayView< const Packet > &exports, size_t numPackets, const ArrayView< Packet > &imports)
	Execute a plan specified by the distributor object.
template<class Packet >
void	doPostsAndWaits (const ArrayView< const Packet > &exports, const ArrayView< size_t > &numExportPacketsPerLID, const ArrayView< Packet > &imports, const ArrayView< size_t > &numImportPacketsPerLID)
	Execute a plan specified by the distributor object.
template<class Packet >
void	doPosts (const ArrayView< const Packet > &exports, size_t numPackets, const ArrayRCP< Packet > &imports)
	Post the data for a distributor plan, but do not execute the waits yet.
template<class Packet >
void	doPosts (const ArrayView< const Packet > &exports, const ArrayView< size_t > &numExportPacketsPerLID, const ArrayRCP< Packet > &imports, const ArrayView< size_t > &numImportPacketsPerLID)
	Post the data for a distributor plan, but do not execute the waits yet.
void	doWaits ()
	Wait on any outstanding posts to complete.
template<class Packet >
void	doReversePostsAndWaits (const ArrayView< const Packet > &exports, size_t numPackets, const ArrayView< Packet > &imports)
	Execute a reverse plan specified by the distributor object.
template<class Packet >
void	doReversePostsAndWaits (const ArrayView< const Packet > &exports, const ArrayView< size_t > &numExportPacketsPerLID, const ArrayView< Packet > &imports, const ArrayView< size_t > &numImportPacketsPerLID)
	Execute a reverse plan specified by the distributor object.
template<class Packet >
void	doReversePosts (const ArrayView< const Packet > &exports, size_t numPackets, const ArrayRCP< Packet > &imports)
	Post the data for a reverse plan, but do not execute the waits yet.
template<class Packet >
void	doReversePosts (const ArrayView< const Packet > &exports, const ArrayView< size_t > &numExportPacketsPerLID, const ArrayRCP< Packet > &imports, const ArrayView< size_t > &numImportPacketsPerLID)
	Post the data for a reverse plan, but do not execute the waits yet.
void	doReverseWaits ()
	Wait on any outstanding reverse waits to complete.
Overridden from Teuchos::Describable
std::string	description () const
	Return a simple one-line description of this object.
void	describe (Teuchos::FancyOStream &out, const Teuchos::EVerbosityLevel verbLevel=Teuchos::Describable::verbLevel_default) const
	Print the object with some verbosity level to an FancyOStream object.

Detailed Description

Class that sets up gathers and scatters for Tpetra communication.

This class encapsulates the general information and services needed for other Tpetra classes to perform gather/scatter operations on a parallel computer.

Definition at line 61 of file Tpetra_Distributor.hpp.

Constructor & Destructor Documentation

Tpetra::Distributor::Distributor ( const RCP< const Comm< int > > & comm ) [explicit]

Construct the Distributor using the specified communicator.

This doesn't actually set up the distribution pattern. You need to call one of the "gather / scatter 'constructors'" to do that.

Definition at line 46 of file Tpetra_Distributor.cpp.

Tpetra::Distributor::Distributor ( const Distributor & distributor )

Copy constructor.

Definition at line 56 of file Tpetra_Distributor.cpp.

Tpetra::Distributor::~Distributor ( )

Destructor.

Definition at line 67 of file Tpetra_Distributor.cpp.

Member Function Documentation

size_t Tpetra::Distributor::createFromSends ( const ArrayView< const int > & exportNodeIDs )

Set up Distributor using list of node IDs to which this node will send.

Take a list of node IDs and construct a plan for efficiently scattering to those nodes. Return the number of nodes which will send me data.

Parameters:

exportNodeIDs [in] List of nodes that will get the exported data. A node ID greater than or equal to the number of nodes will result in a std::runtime_error on all nodes. Node IDs less than zero are ignored; their placement corresponds to null sends in any future exports. That is, if exportNodeIDs[0] == -1, then the corresponding position in the export array is ignored during a call to doPosts() or doPostsAndWaits(). For this reason, a negative entry is sufficient to break contiguity.

Returns:: Number of imports this node will be receiving.

Definition at line 367 of file Tpetra_Distributor.cpp.

template<class Ordinal >

void Tpetra::Distributor::createFromRecvs	(	const ArrayView< const Ordinal > &	remoteIDs,
		const ArrayView< const int > &	remoteNodeIDs,
		ArrayRCP< Ordinal > &	exportIDs,
		ArrayRCP< int > &	exportNodeIDs
	)

Set up Distributor using list of node IDs from which to receive.

Take a list of node IDs and construct a plan for efficiently scattering to those nodes. Return the number and list of IDs being sent by me.

Import invokes this method in order to creating a Distributor from a list of receive neighbors and IDs. A common use case for this process is setting up sends and receives for the remote entries of the source vector in a distributed sparse matrix-vector multiply. The Mantevo HPCCG miniapp shows an annotated and simplified version of this process for that special case.

Parameters:

remoteIDs	[in] List of remote IDs wanted.
remoteNodeIDs	[in] List of the nodes that will send the remote IDs listed in . Node IDs less than zero are ignored; their placement corresponds to null sends in any future exports. A node ID greater than or equal to the number of nodes will result in an `std::runtime_error` on all nodes.
exportIDs	[out] List of IDs that need to be sent from this node.
exportNodeIDs	[out] List of nodes that will get the exported IDs in `exportIDs`.

The exportGIDs and exportNodeIDs arrays are allocated by the Distributor, which is why they are passed in a nonconst reference to an ArrayRCP. They may be null on entry.

Definition at line 859 of file Tpetra_Distributor.hpp.

size_t Tpetra::Distributor::getNumReceives ( ) const

The number of nodes from which we will receive data, not include this node ("myself").

Definition at line 81 of file Tpetra_Distributor.cpp.

size_t Tpetra::Distributor::getNumSends ( ) const

The number of nodes to which we will send data, not include this node ("myself").

Definition at line 87 of file Tpetra_Distributor.cpp.

bool Tpetra::Distributor::hasSelfMessage ( ) const

Indicates whether values are being sent to/recieved from this node.

If we are sending any elements to ourself, returns true. If we aren't, returns false.

Definition at line 84 of file Tpetra_Distributor.cpp.

size_t Tpetra::Distributor::getMaxSendLength ( ) const

Maximum number of values that this node is sending to another single node.

Definition at line 90 of file Tpetra_Distributor.cpp.

size_t Tpetra::Distributor::getTotalReceiveLength ( ) const

Total number of values that this nodes is receiving from other nodes.

Definition at line 78 of file Tpetra_Distributor.cpp.

Teuchos::ArrayView< const int > Tpetra::Distributor::getImagesFrom ( ) const

A list of images sending values to this node. (non-persisting view)

Definition at line 93 of file Tpetra_Distributor.cpp.

Teuchos::ArrayView< const int > Tpetra::Distributor::getImagesTo ( ) const

A list of images to which this node is sending values. (non-persisting view)

Definition at line 99 of file Tpetra_Distributor.cpp.

Teuchos::ArrayView< const size_t > Tpetra::Distributor::getLengthsFrom ( ) const

Number of values we're receiving from each node. (non-persisting view)

We will receive getLengthsFrom[i] values from node getImagesFrom[i].

Definition at line 96 of file Tpetra_Distributor.cpp.

Teuchos::ArrayView< const size_t > Tpetra::Distributor::getLengthsTo ( ) const

Number of values we're sending to each node. (non-persisting view)

We will send getLengthsTo[i] values to image getImagesTo[i].

Definition at line 102 of file Tpetra_Distributor.cpp.

const Teuchos::RCP< Distributor > & Tpetra::Distributor::getReverse ( ) const

Returns a Distributor with a reverse plan of this Distributor's plan.

This method creates the reverse Distributor the first time the function is called.

Definition at line 106 of file Tpetra_Distributor.cpp.

template<class Packet >

void Tpetra::Distributor::doPostsAndWaits	(	const ArrayView< const Packet > &	exports,
		size_t	numPackets,
		const ArrayView< Packet > &	imports
	)

Execute a plan specified by the distributor object.

Parameters:

exports	[in] Contains the values we're exporting.
numPackets	[in] Specifies the number of values per export/import.
imports	[out] On entry, buffer must be large enough to accomodate the data exported to us. On exit, contains the values exported to us.

Definition at line 454 of file Tpetra_Distributor.hpp.

template<class Packet >

void Tpetra::Distributor::doPostsAndWaits	(	const ArrayView< const Packet > &	exports,
		const ArrayView< size_t > &	numExportPacketsPerLID,
		const ArrayView< Packet > &	imports,
		const ArrayView< size_t > &	numImportPacketsPerLID
	)

Execute a plan specified by the distributor object.

Parameters:

exports	[in] Contains the values we're exporting.
numPackets	[in] Specifies the number of values per export/import.
imports	[out] On entry, buffer must be large enough to accomodate the data exported to us. On exit, contains the values exported to us.

Definition at line 469 of file Tpetra_Distributor.hpp.

template<class Packet >

void Tpetra::Distributor::doPosts	(	const ArrayView< const Packet > &	exports,
		size_t	numPackets,
		const ArrayRCP< Packet > &	imports
	)

Post the data for a distributor plan, but do not execute the waits yet.

Parameters:

exports	[in] Contains the values to be sent by this node.
numPackets	[in] Specifies the number of scalars per export/import.
imports	[out] Buffer must be large enough to accomodate the data exported to us. The buffer is not guaranteed to be filled until doWaits() is executed.

Definition at line 486 of file Tpetra_Distributor.hpp.

template<class Packet >

void Tpetra::Distributor::doPosts	(	const ArrayView< const Packet > &	exports,
		const ArrayView< size_t > &	numExportPacketsPerLID,
		const ArrayRCP< Packet > &	imports,
		const ArrayView< size_t > &	numImportPacketsPerLID
	)

Post the data for a distributor plan, but do not execute the waits yet.

Parameters:

exports	[in] Contains the values to be sent by this node.
numPackets	[in] Specifies the number of scalars per export/import.
imports	[out] Buffer must be large enough to accomodate the data exported to us. The buffer is not guaranteed to be filled until doWaits() is executed.

Definition at line 606 of file Tpetra_Distributor.hpp.

void Tpetra::Distributor::doWaits ( )

Wait on any outstanding posts to complete.

Definition at line 161 of file Tpetra_Distributor.cpp.

template<class Packet >

void Tpetra::Distributor::doReversePostsAndWaits	(	const ArrayView< const Packet > &	exports,
		size_t	numPackets,
		const ArrayView< Packet > &	imports
	)

Execute a reverse plan specified by the distributor object.

Parameters:

exports	[in] Contains the values to be sent by this node.
numPackets	[in] Specifies the number of scalars per export/import.
imports	[out] On entry, buffer must be large enough to accomodate the data exported to us. On exit, contains the values exported to us.

Definition at line 764 of file Tpetra_Distributor.hpp.

template<class Packet >

void Tpetra::Distributor::doReversePostsAndWaits	(	const ArrayView< const Packet > &	exports,
		const ArrayView< size_t > &	numExportPacketsPerLID,
		const ArrayView< Packet > &	imports,
		const ArrayView< size_t > &	numImportPacketsPerLID
	)

Execute a reverse plan specified by the distributor object.

Parameters:

exports	[in] Contains the values to be sent by this node.
numPackets	[in] Specifies the number of scalars per export/import.
imports	[out] On entry, buffer must be large enough to accomodate the data exported to us. On exit, contains the values exported to us.

Definition at line 777 of file Tpetra_Distributor.hpp.

template<class Packet >

void Tpetra::Distributor::doReversePosts	(	const ArrayView< const Packet > &	exports,
		size_t	numPackets,
		const ArrayRCP< Packet > &	imports
	)

Post the data for a reverse plan, but do not execute the waits yet.

Parameters:

exports	[in] Contains the values we're exporting.
numPackets	[in] Specifies the number of scalars per export/import.
imports	[out] Buffer must be large enough to accomodate the data exported to us. The buffer is not guaranteed to be filled until doWaits() is executed.

Definition at line 792 of file Tpetra_Distributor.hpp.

template<class Packet >

void Tpetra::Distributor::doReversePosts	(	const ArrayView< const Packet > &	exports,
		const ArrayView< size_t > &	numExportPacketsPerLID,
		const ArrayRCP< Packet > &	imports,
		const ArrayView< size_t > &	numImportPacketsPerLID
	)

Post the data for a reverse plan, but do not execute the waits yet.

Parameters:

exports	[in] Contains the values we're exporting.
numPackets	[in] Specifies the number of scalars per export/import.
imports	[out] Buffer must be large enough to accomodate the data exported to us. The buffer is not guaranteed to be filled until doWaits() is executed.

Definition at line 806 of file Tpetra_Distributor.hpp.

void Tpetra::Distributor::doReverseWaits ( )

Wait on any outstanding reverse waits to complete.

Definition at line 183 of file Tpetra_Distributor.cpp.

std::string Tpetra::Distributor::description ( ) const [virtual]

Return a simple one-line description of this object.

Reimplemented from Teuchos::Describable.

Definition at line 191 of file Tpetra_Distributor.cpp.

void Tpetra::Distributor::describe	(	Teuchos::FancyOStream &	out,
		const Teuchos::EVerbosityLevel	verbLevel = `Teuchos::Describable::verbLevel_default`
	)		const `[virtual]`

Print the object with some verbosity level to an FancyOStream object.

Reimplemented from Teuchos::Describable.

Definition at line 198 of file Tpetra_Distributor.cpp.

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

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation