Tpetra Matrix/Vector Services Version of the Day
Tpetra::Distributor Class Reference

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

#include <Tpetra_Distributor.hpp>

Inheritance diagram for Tpetra::Distributor:
Inheritance graph
[legend]

List of all members.

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:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines