Communication plan for data redistribution from a (possibly) multiply-owned to a uniquely-owned distribution. More...

#include <Tpetra_Export_decl.hpp>

Inheritance diagram for Tpetra::Export< LocalOrdinal, GlobalOrdinal, Node >:

Public Types
using	map_type = ::Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >
	The specialization of Map used by this class. More...

Public Member Functions
size_t	getNumSameIDs () const
	Number of initial identical IDs. More...

size_t	getNumPermuteIDs () const
	Number of IDs to permute but not to communicate. More...

Kokkos::DualView< const LocalOrdinal *, device_type >	getPermuteFromLIDs_dv () const
	List of local IDs in the source Map that are permuted, as a const DualView (that is sync'd to both host and device). More...

Teuchos::ArrayView< const LocalOrdinal >	getPermuteFromLIDs () const
	List of local IDs in the source Map that are permuted. More...

Kokkos::DualView< const LocalOrdinal *, device_type >	getPermuteToLIDs_dv () const
	List of local IDs in the target Map that are permuted, as a const DualView (that is sync'd to both host and device). More...

Teuchos::ArrayView< const LocalOrdinal >	getPermuteToLIDs () const
	List of local IDs in the target Map that are permuted. More...

size_t	getNumRemoteIDs () const
	Number of entries not on the calling process. More...

Kokkos::DualView< const LocalOrdinal *, device_type >	getRemoteLIDs_dv () const
	List of entries in the target Map to receive from other processes, as a const DualView (that is sync'd to both host and device). More...

Teuchos::ArrayView< const LocalOrdinal >	getRemoteLIDs () const
	List of entries in the target Map to receive from other processes. More...

size_t	getNumExportIDs () const
	Number of entries that must be sent by the calling process to other processes. More...

Kokkos::DualView< const LocalOrdinal *, device_type >	getExportLIDs_dv () const
	List of entries in the source Map that will be sent to other processes, as a const DualView (that is sync'd to both host and device). More...

Teuchos::ArrayView< const LocalOrdinal >	getExportLIDs () const
	List of entries in the source Map that will be sent to other processes. More...

Teuchos::ArrayView< const int >	getExportPIDs () const
	List of processes to which entries will be sent. More...

Teuchos::RCP< const map_type >	getSourceMap () const
	The source Map used to construct this Export or Import. More...

Teuchos::RCP< const map_type >	getTargetMap () const
	The target Map used to construct this Export or Import. More...

::Tpetra::Distributor &	getDistributor () const
	The Distributor that this Export or Import object uses to move data. More...

bool	isLocallyComplete () const
	Is this Export or Import locally complete? More...

Constructors, assignment, and destructor
	Export (const Teuchos::RCP< const map_type > &source, const Teuchos::RCP< const map_type > &target)
	Construct a Export object from the source and target Map. More...

	Export (const Teuchos::RCP< const map_type > &source, const Teuchos::RCP< const map_type > &target, const Teuchos::RCP< Teuchos::FancyOStream > &out)
	Construct an Export from the source and target Maps, with an output stream for debugging output. More...

	Export (const Teuchos::RCP< const map_type > &source, const Teuchos::RCP< const map_type > &target, const Teuchos::RCP< Teuchos::ParameterList > &plist)
	Constructor (with list of parameters) More...

	Export (const Teuchos::RCP< const map_type > &source, const Teuchos::RCP< const map_type > &target, const Teuchos::RCP< Teuchos::FancyOStream > &out, const Teuchos::RCP< Teuchos::ParameterList > &plist)
	Constructor (with list of parameters and debugging output stream) More...

	Export (const Export< LocalOrdinal, GlobalOrdinal, Node > &rhs)
	Copy constructor. More...

	Export (const Import< LocalOrdinal, GlobalOrdinal, Node > &importer)
	"Copy" constructor from an Export object. More...

Export< LocalOrdinal, GlobalOrdinal, Node > &	operator= (const Export< LocalOrdinal, GlobalOrdinal, Node > &rhs)=default
	Assignment operator. More...

virtual	~Export ()=default
	Destructor. More...

I/O Methods
virtual void	describe (Teuchos::FancyOStream &out, const Teuchos::EVerbosityLevel verbLevel=Teuchos::Describable::verbLevel_default) const
	Describe this object in a human-readable way to the given output stream. More...

virtual void	print (std::ostream &os) const
	Print the Export's data to the given output stream. More...

Protected Member Functions
Teuchos::FancyOStream &	verboseOutputStream () const
	Valid (nonnull) output stream for verbose output. More...

bool	verbose () const
	Whether to print verbose debugging output. More...

void	describeImpl (Teuchos::FancyOStream &out, const std::string &className, const Teuchos::EVerbosityLevel verbLevel=Teuchos::Describable::verbLevel_default) const
	Implementation of describe() for subclasses (Tpetra::Import and Tpetra::Export). More...

Protected Attributes
Teuchos::RCP< ImportExportData < LocalOrdinal, GlobalOrdinal, Node > >	TransferData_
	All the data needed for executing the Export communication plan. More...

Related Functions
(Note that these are not member functions.)
template<class LocalOrdinal , class GlobalOrdinal , class Node >
Teuchos::RCP< const Export < LocalOrdinal, GlobalOrdinal, Node > >	createExport (const Teuchos::RCP< const Map< LocalOrdinal, GlobalOrdinal, Node > > &src, const Teuchos::RCP< const Map< LocalOrdinal, GlobalOrdinal, Node > > &tgt)
	Nonmember "constructor" for Export objects. More...

Detailed Description

template<class LocalOrdinal, class GlobalOrdinal, class Node>
class Tpetra::Export< LocalOrdinal, GlobalOrdinal, Node >

Communication plan for data redistribution from a (possibly) multiply-owned to a uniquely-owned distribution.

Template Parameters

LocalOrdinal	The type of local indices. See the documentation of Map for requirements.
GlobalOrdinal	The type of global indices. See the documentation of Map for requirements.
Node	The Kokkos Node type. See the documentation of Map for requirements.

Tpetra users should use this class to construct a communication plan between two data distributions (i.e., two Map objects). The plan can be called repeatedly by computational classes to perform communication according to the same pattern. Constructing the plan may be expensive, both in terms of communication and computation. However, it can be reused inexpensively.

Tpetra has two classes for data redistribution: Import and Export. Import is for redistributing data from a uniquely-owned distribution to a possibly multiply-owned distribution. Export is for redistributing data from a possibly multiply-owned distribution to a uniquely-owned distribution.

The names "Import" and "Export" have nothing to do with the direction in which data moves relative to the calling process; any process may do both receives and sends in an Import or Export. Rather, the names suggest what happens in their most common use case, the communication pattern for sparse matrix-vector multiply. Import "brings in" remote source vector data (from the domain Map to the column Map) for local computation, and Export "pushes" the result back (from the row Map to the range Map). Import and Export have other uses as well.

One use case of Export is finite element assembly. For example, one way to compute a distributed forcing term vector is to use an overlapping distribution for the basis functions' domains. An Export with the SUM combine mode combines each process' contribution to the integration into a single nonoverlapping distribution.

Epetra separated Import and Export for performance reasons. The implementation is different, depending on which direction is the uniquely-owned Map. Tpetra retains this convention.

This class is templated on the same template arguments as Map: the local ordinal type LocalOrdinal, the global ordinal type GlobalOrdinal, and the Kokkos Node type.

This method accepts an optional list of parameters, either through the constructor or through the setParameterList() method. Most users do not need to worry about these parameters; the default values are fine. However, for expert users, we expose the following parameter:

"Barrier between receives and sends" (bool): Whether to execute a barrier between receives and sends, when executing the Import (i.e., when calling DistObject's doImport() (forward mode) or doExport() (reverse mode)).

Definition at line 122 of file Tpetra_Export_decl.hpp.

Member Typedef Documentation

template<class LocalOrdinal, class GlobalOrdinal, class Node>

using Tpetra::Export< LocalOrdinal, GlobalOrdinal, Node >::map_type = ::Tpetra::Map<LocalOrdinal, GlobalOrdinal, Node>

The specialization of Map used by this class.

Definition at line 131 of file Tpetra_Export_decl.hpp.

Constructor & Destructor Documentation

template<class LocalOrdinal , class GlobalOrdinal , class Node >

Tpetra::Export< LocalOrdinal, GlobalOrdinal, Node >::Export	(	const Teuchos::RCP< const map_type > &	source,
		const Teuchos::RCP< const map_type > &	target
	)

Construct a Export object from the source and target Map.

Parameters

source	[in] The source distribution. This may be a multiply owned (overlapping) distribution.
target	[in] The target distribution. This must be a uniquely owned (nonoverlapping) distribution.

Definition at line 105 of file Tpetra_Export_def.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >

Tpetra::Export< LocalOrdinal, GlobalOrdinal, Node >::Export	(	const Teuchos::RCP< const map_type > &	source,
		const Teuchos::RCP< const map_type > &	target,
		const Teuchos::RCP< Teuchos::FancyOStream > &	out
	)

Construct an Export from the source and target Maps, with an output stream for debugging output.

Parameters

source	[in] The source distribution. This may be a multiply owned (overlapping) distribution.
target	[in] The target distribution. This must be a uniquely owned (nonoverlapping) distribution.
out	[in/out] Output stream for debugging output.

Definition at line 112 of file Tpetra_Export_def.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >

Tpetra::Export< LocalOrdinal, GlobalOrdinal, Node >::Export	(	const Teuchos::RCP< const map_type > &	source,
		const Teuchos::RCP< const map_type > &	target,
		const Teuchos::RCP< Teuchos::ParameterList > &	plist
	)

Constructor (with list of parameters)

Parameters

source	[in] The source distribution. This may be a multiply owned (overlapping) distribution.
target	[in] The target distribution. This must be a uniquely owned (nonoverlapping) distribution.
plist	[in/out] List of parameters. Currently passed directly to the Distributor that implements communication. If you don't know what this should be, you should use the two-argument constructor, listed above.

Definition at line 120 of file Tpetra_Export_def.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >

Tpetra::Export< LocalOrdinal, GlobalOrdinal, Node >::Export	(	const Teuchos::RCP< const map_type > &	source,
		const Teuchos::RCP< const map_type > &	target,
		const Teuchos::RCP< Teuchos::FancyOStream > &	out,
		const Teuchos::RCP< Teuchos::ParameterList > &	plist
	)

Constructor (with list of parameters and debugging output stream)

Parameters

source	[in] The source distribution. This may be a multiply owned (overlapping) distribution.
target	[in] The target distribution. This must be a uniquely owned (nonoverlapping) distribution.
out	[in/out] Output stream for debugging output.
plist	[in/out] List of parameters. Currently passed directly to the Distributor that implements communication. If you don't know what this should be, you should use the two-argument constructor, listed above.

Definition at line 63 of file Tpetra_Export_def.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >

Tpetra::Export< LocalOrdinal, GlobalOrdinal, Node >::Export ( const Export< LocalOrdinal, GlobalOrdinal, Node > & rhs )

Copy constructor.

Note: Currently this only makes a shallow copy of the Export's underlying data.

Definition at line 128 of file Tpetra_Export_def.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >

Tpetra::Export< LocalOrdinal, GlobalOrdinal, Node >::Export ( const Import< LocalOrdinal, GlobalOrdinal, Node > & importer )

"Copy" constructor from an Export object.

This constructor creates an Export object from the "reverse" of the given Import object. This method is mainly useful for Tpetra developers, for example when building the explicit transpose of a sparse matrix.

Definition at line 134 of file Tpetra_Export_def.hpp.

template<class LocalOrdinal, class GlobalOrdinal, class Node>

virtual Tpetra::Export< LocalOrdinal, GlobalOrdinal, Node >::~Export ( )

virtualdefault

Destructor.

Member Function Documentation

template<class LocalOrdinal, class GlobalOrdinal, class Node>

Export<LocalOrdinal,GlobalOrdinal,Node>& Tpetra::Export< LocalOrdinal, GlobalOrdinal, Node >::operator= ( const Export< LocalOrdinal, GlobalOrdinal, Node > & rhs )

default

Assignment operator.

template<class LocalOrdinal , class GlobalOrdinal , class Node >

void Tpetra::Export< LocalOrdinal, GlobalOrdinal, Node >::describe	(	Teuchos::FancyOStream &	out,
		const Teuchos::EVerbosityLevel	verbLevel = `Teuchos::Describable::verbLevel_default`
	)		const

virtual

Describe this object in a human-readable way to the given output stream.

You must call this method as a collective over all processes in the communicator of the source and target Map of this object.

Parameters

out	[out] Output stream to which to write. Only Process 0 in this object's communicator may write to the output stream.
verbLevel	[in] Verbosity level. This also controls whether this method does any communication. At verbosity levels higher (greater) than Teuchos::VERB_LOW, this method behaves as a collective over the object's communicator.

Teuchos::FancyOStream wraps std::ostream. It adds features like tab levels. If you just want to wrap std::cout, try this:

auto out = Teuchos::getFancyOStream (Teuchos::rcpFromRef (std::out));

Reimplemented from Tpetra::Details::Transfer< LocalOrdinal, GlobalOrdinal, Node >.

Definition at line 141 of file Tpetra_Export_def.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >

void Tpetra::Export< LocalOrdinal, GlobalOrdinal, Node >::print ( std::ostream & os ) const

virtual

Print the Export's data to the given output stream.

This method assumes that the given output stream can be written on all process(es) in the Export's communicator. The resulting output is useful mainly for debugging.

Note: This method tries its best (by using barriers at the end of each iteration of a for loop over all communicator ranks) to ensure ordered deterministic output. However, the assumption that all processes can write to the stream means that there are no ordering guarantees other than what the operating and run-time system provide. (MPI synchronization may be separate from output stream synchronization, so the barriers only improve the chances that output can complete before the next process starts writing.)

Definition at line 150 of file Tpetra_Export_def.hpp.

size_t Tpetra::Details::Transfer< LocalOrdinal , GlobalOrdinal , Node >::getNumSameIDs ( ) const

inherited

Number of initial identical IDs.

The number of IDs that are identical between the source and target Maps, up to the first different ID.

size_t Tpetra::Details::Transfer< LocalOrdinal , GlobalOrdinal , Node >::getNumPermuteIDs ( ) const

inherited

Number of IDs to permute but not to communicate.

The number of IDs that are local to the calling process, but not part of the first getNumSameIDs() entries. The Import or Export will permute these entries locally (without distributed-memory communication).

Kokkos::DualView<const LocalOrdinal *, device_type> Tpetra::Details::Transfer< LocalOrdinal , GlobalOrdinal , Node >::getPermuteFromLIDs_dv ( ) const

inherited

List of local IDs in the source Map that are permuted, as a const DualView (that is sync'd to both host and device).

Teuchos::ArrayView<const LocalOrdinal > Tpetra::Details::Transfer< LocalOrdinal , GlobalOrdinal , Node >::getPermuteFromLIDs ( ) const

inherited

List of local IDs in the source Map that are permuted.

Kokkos::DualView<const LocalOrdinal *, device_type> Tpetra::Details::Transfer< LocalOrdinal , GlobalOrdinal , Node >::getPermuteToLIDs_dv ( ) const

inherited

List of local IDs in the target Map that are permuted, as a const DualView (that is sync'd to both host and device).

Teuchos::ArrayView<const LocalOrdinal > Tpetra::Details::Transfer< LocalOrdinal , GlobalOrdinal , Node >::getPermuteToLIDs ( ) const

inherited

List of local IDs in the target Map that are permuted.

size_t Tpetra::Details::Transfer< LocalOrdinal , GlobalOrdinal , Node >::getNumRemoteIDs ( ) const

inherited

Number of entries not on the calling process.

Kokkos::DualView<const LocalOrdinal *, device_type> Tpetra::Details::Transfer< LocalOrdinal , GlobalOrdinal , Node >::getRemoteLIDs_dv ( ) const

inherited

List of entries in the target Map to receive from other processes, as a const DualView (that is sync'd to both host and device).

Teuchos::ArrayView<const LocalOrdinal > Tpetra::Details::Transfer< LocalOrdinal , GlobalOrdinal , Node >::getRemoteLIDs ( ) const

inherited

List of entries in the target Map to receive from other processes.

size_t Tpetra::Details::Transfer< LocalOrdinal , GlobalOrdinal , Node >::getNumExportIDs ( ) const

inherited

Number of entries that must be sent by the calling process to other processes.

Kokkos::DualView<const LocalOrdinal *, device_type> Tpetra::Details::Transfer< LocalOrdinal , GlobalOrdinal , Node >::getExportLIDs_dv ( ) const

inherited

List of entries in the source Map that will be sent to other processes, as a const DualView (that is sync'd to both host and device).

Teuchos::ArrayView<const LocalOrdinal > Tpetra::Details::Transfer< LocalOrdinal , GlobalOrdinal , Node >::getExportLIDs ( ) const

inherited

List of entries in the source Map that will be sent to other processes.

Teuchos::ArrayView<const int> Tpetra::Details::Transfer< LocalOrdinal , GlobalOrdinal , Node >::getExportPIDs ( ) const

inherited

List of processes to which entries will be sent.

The entry with local ID getExportLIDs()[i] will be sent to process getExportPiDs()[i].

Teuchos::RCP<const map_type> Tpetra::Details::Transfer< LocalOrdinal , GlobalOrdinal , Node >::getSourceMap ( ) const

inherited

The source Map used to construct this Export or Import.

Teuchos::RCP<const map_type> Tpetra::Details::Transfer< LocalOrdinal , GlobalOrdinal , Node >::getTargetMap ( ) const

inherited

The target Map used to construct this Export or Import.

::Tpetra::Distributor& Tpetra::Details::Transfer< LocalOrdinal , GlobalOrdinal , Node >::getDistributor ( ) const

inherited

The Distributor that this Export or Import object uses to move data.

bool Tpetra::Details::Transfer< LocalOrdinal , GlobalOrdinal , Node >::isLocallyComplete ( ) const

inherited

Is this Export or Import locally complete?

If this is an Export, then do all source Map indices on the calling process exist on at least one process (not necessarily this one) in the target Map?

If this is an Import, then do all target Map indices on the calling process exist on at least one process (not necessarily this one) in the source Map?

It's not necessarily an error for an Export or Import not to be locally complete on one or more processes. For example, this may happen in the common use case of "restriction" – that is, taking a subset of a large object. Nevertheless, you may find this predicate useful for figuring out whether you set up your Maps in the way that you expect.

Teuchos::FancyOStream& Tpetra::Details::Transfer< LocalOrdinal , GlobalOrdinal , Node >::verboseOutputStream ( ) const

protectedinherited

Valid (nonnull) output stream for verbose output.

bool Tpetra::Details::Transfer< LocalOrdinal , GlobalOrdinal , Node >::verbose ( ) const

protectedinherited

Whether to print verbose debugging output.

void Tpetra::Details::Transfer< LocalOrdinal , GlobalOrdinal , Node >::describeImpl	(	Teuchos::FancyOStream &	out,
		const std::string &	className,
		const Teuchos::EVerbosityLevel	verbLevel = `Teuchos::Describable::verbLevel_default`
	)		const

protectedinherited

Implementation of describe() for subclasses (Tpetra::Import and Tpetra::Export).

Parameters

out	[out] Output stream to which to write. Only Process 0 in this object's communicator may write to the output stream.
className	[in] Name of the subclass of Transfer calling this method.
verbLevel	[in] Verbosity level. This also controls whether this method does any communication. At verbosity levels higher (greater) than Teuchos::VERB_LOW, this method behaves as a collective over the object's communicator.

Friends And Related Function Documentation

template<class LocalOrdinal , class GlobalOrdinal , class Node >

Teuchos::RCP< const Export< LocalOrdinal, GlobalOrdinal, Node > > createExport	(	const Teuchos::RCP< const Map< LocalOrdinal, GlobalOrdinal, Node > > &	src,
		const Teuchos::RCP< const Map< LocalOrdinal, GlobalOrdinal, Node > > &	tgt
	)

Create an Export object from the given source and target Maps.

Precondition: src != null; tgt != null

Returns: The Export object. If src == tgt, returns null.

(Debug mode: throws std::runtime_error if one of src or tgt is null.)

Definition at line 290 of file Tpetra_Export_decl.hpp.

Member Data Documentation

Teuchos::RCP<ImportExportData<LocalOrdinal , GlobalOrdinal , Node > > Tpetra::Details::Transfer< LocalOrdinal , GlobalOrdinal , Node >::TransferData_

protectedinherited

All the data needed for executing the Export communication plan.

Definition at line 231 of file Tpetra_Details_Transfer_decl.hpp.

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

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Related Functions

Detailed Description

template<class LocalOrdinal, class GlobalOrdinal, class Node> class Tpetra::Export< LocalOrdinal, GlobalOrdinal, Node >

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation

template<class LocalOrdinal, class GlobalOrdinal, class Node>
class Tpetra::Export< LocalOrdinal, GlobalOrdinal, Node >