Base class for distributed Tpetra objects that support data redistribution. More...

#include <Tpetra_KokkosRefactor_DistObject_decl.hpp>

Inheritance diagram for Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >:

Public Types
Typedefs
typedef Packet	packet_type
	The type of each datum being sent or received in an Import or Export.
typedef LocalOrdinal	local_ordinal_type
	The type of local indices.
typedef GlobalOrdinal	global_ordinal_type
	The type of global indices.
typedef Node	node_type
	The Kokkos Node type.
Public Member Functions
Constructors and destructor
	DistObject (const Teuchos::RCP< const Map< LocalOrdinal, GlobalOrdinal, Node > > &map)
	Constructor.
	DistObject (const DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node > &rhs)
	Copy constructor.
virtual	~DistObject ()
	Destructor (virtual for memory safety of derived classes).
Public methods for redistributing data
void	doImport (const SrcDistObject &source, const Import< LocalOrdinal, GlobalOrdinal, Node > &importer, CombineMode CM)
	Import data into this object using an Import object ("forward mode").
void	doExport (const SrcDistObject &source, const Export< LocalOrdinal, GlobalOrdinal, Node > &exporter, CombineMode CM)
	Export data into this object using an Export object ("forward mode").
void	doImport (const SrcDistObject &source, const Export< LocalOrdinal, GlobalOrdinal, Node > &exporter, CombineMode CM)
	Import data into this object using an Export object ("reverse mode").
void	doExport (const SrcDistObject &source, const Import< LocalOrdinal, GlobalOrdinal, Node > &importer, CombineMode CM)
	Export data into this object using an Import object ("reverse mode").
Attribute accessor methods
bool	isDistributed () const
	Whether this is a globally distributed object.
virtual Teuchos::RCP< const Map< LocalOrdinal, GlobalOrdinal, Node > >	getMap () const
	The Map describing the parallel distribution of this object.
I/O methods
void	print (std::ostream &os) const
	Print this object to the given output stream.
Implementation of Teuchos::Describable
virtual std::string	description () const
	One-line descriptiion of this object.
virtual void	describe (Teuchos::FancyOStream &out, const Teuchos::EVerbosityLevel verbLevel=Teuchos::Describable::verbLevel_default) const
	Print a descriptiion of this object to the given output stream.
Protected Types
enum	ReverseOption
	Whether the data transfer should be performed in forward or reverse mode. More...
Protected Member Functions
virtual size_t	constantNumberOfPackets () const
	Whether the implementation's instance promises always to have a constant number of packets per LID, and if so, how many packets per LID there are.
virtual void	doTransfer (const SrcDistObject &src, CombineMode CM, size_t numSameIDs, const Teuchos::ArrayView< const LocalOrdinal > &permuteToLIDs, const Teuchos::ArrayView< const LocalOrdinal > &permuteFromLIDs, const Teuchos::ArrayView< const LocalOrdinal > &remoteLIDs, const Teuchos::ArrayView< const LocalOrdinal > &exportLIDs, Distributor &distor, ReverseOption revOp)
	Redistribute data across memory images.
virtual void	createViews () const
	Hook for creating a const view.
virtual void	createViewsNonConst (KokkosClassic::ReadWriteOption rwo)
	Hook for creating a nonconst view.
virtual void	releaseViews () const
	Hook for releasing views.
Methods implemented by subclasses and used by doTransfer().
The doTransfer() method uses the subclass' implementations of these methods to implement data transfer. Subclasses of DistObject must implement these methods. This is an instance of the Template Method Pattern. ("Template" here doesn't mean "C++ template"; it means "pattern with holes that are filled in by the subclass' method implementations.")
virtual bool	checkSizes (const SrcDistObject &source)=0
	Compare the source and target (this) objects for compatibility.
virtual void	copyAndPermute (const SrcDistObject &source, size_t numSameIDs, const Teuchos::ArrayView< const LocalOrdinal > &permuteToLIDs, const Teuchos::ArrayView< const LocalOrdinal > &permuteFromLIDs)=0
	Perform copies and permutations that are local to this process.
virtual void	packAndPrepare (const SrcDistObject &source, const Teuchos::ArrayView< const LocalOrdinal > &exportLIDs, Teuchos::Array< Packet > &exports, const Teuchos::ArrayView< size_t > &numPacketsPerLID, size_t &constantNumPackets, Distributor &distor)=0
	Perform any packing or preparation required for communication.
virtual void	unpackAndCombine (const Teuchos::ArrayView< const LocalOrdinal > &importLIDs, const Teuchos::ArrayView< const Packet > &imports, const Teuchos::ArrayView< size_t > &numPacketsPerLID, size_t constantNumPackets, Distributor &distor, CombineMode CM)=0
	Perform any unpacking and combining after communication.
Protected Attributes
Teuchos::RCP< const Map < LocalOrdinal, GlobalOrdinal, Node > >	map_
	The Map over which this object is distributed.
Teuchos::Array< Packet >	imports_
	Buffer into which packed data are imported (received from other processes).
Teuchos::Array< size_t >	numImportPacketsPerLID_
	Number of packets to receive for each receive operation.
Teuchos::Array< Packet >	exports_
	Buffer from which packed data are exported (sent to other processes).
Teuchos::Array< size_t >	numExportPacketsPerLID_
	Number of packets to send for each send operation.
Methods for use only by experts
virtual void	removeEmptyProcessesInPlace (const Teuchos::RCP< const Map< LocalOrdinal, GlobalOrdinal, Node > > &newMap)
	Remove processes which contain no elements in this object's Map.
template<class PT , class LO , class GO , class NT >
void	removeEmptyProcessesInPlace (Teuchos::RCP< Tpetra::DistObject< PT, LO, GO, NT > > &input, const Teuchos::RCP< const Map< LO, GO, NT > > &newMap)
template<class PT , class LO , class GO , class NT >
void	removeEmptyProcessesInPlace (Teuchos::RCP< Tpetra::DistObject< PT, LO, GO, NT > > &input)

Detailed Description

template<class Packet, class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>
class Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >

Base class for distributed Tpetra objects that support data redistribution.

DistObject is a base class for all Tpetra distributed global objects, including CrsMatrix and MultiVector. It provides the basic mechanisms and interface specifications for importing and exporting operations using Import and Export objects.

Template Parameters:

LocalOrdinal	The type of local IDs. Same as Map's `LocalOrdinal` template parameter. This should be an integer type, preferably signed.
GlobalOrdinal	The type of global IDs. Same as Map's `GlobalOrdinal` template parameter. Defaults to the same type as `LocalOrdinal`. This should also be an integer type, preferably signed.
Node	Same as Map's `Node` template parameter. Defaults to the default Kokkos Node type.

Summary

Most Tpetra users will only use this class' methods to perform data redistribution for subclasses such as CrsMatrix, MultiVector, and Vector. DistObject provides four methods for redistributing data: two versions of doImport(), and two versions of doExport(). Import operations redistribute data from a nonoverlapping (one-to-one) distribution to a possibly overlapping distribution. Export operations redistribute data from a possibly overlapping distribution to a nonoverlapping (one-to-one) distribution. Once you have precomputed a data redistribution plan (an Import or Export object), you may use the plan to redistribute an input object's data into this object, by calling one of these methods. The input object of doImport() or doExport() is always the "source" of the redistribution operation, which sends the data. The *this object is the target, which receives and combines the data. It has the distribution given by this->getMap().

Forward or reverse redistribution modes

Both Import and Export operations occur in two modes: forward and reverse. Forward mode is the usual case, where you are calling a method with its matching plan type (doImport() for an Import plan, or doExport() for an Export plan). In that case, the input DistObject must have the same Map as the source Map of the plan, and the target DistObject must have the same Map as the target Map of the plan. Reverse mode is also possible, where you call a method with the opposite plan type (doImport() for an Export plan, or doExport() for an Import plan). In that case, the source DistObject's Map must be the same as the target Map of the plan, and the target DistObject's Map must be the same as the source Map of the plan. If you call doImport(), we still call this an Import operation, even if you are using an Export plan in reverse. Similarly, if you call doExport(), we call this an Export operation.

Most users will want to use forward mode. However, reverse mode is useful for some applications. For example, suppose you are solving a nonlinear partial differential equation using the finite element method, with Newton's method for the nonlinear equation. When assembling into a vector, it is convenient and efficient to do local assembly first into a vector with an overlapping distribution, then do global assembly via forward mode Export into a vector with a nonoverlapping distribution. After the linear solve, you may want to bring the resulting nonoverlapping distribution vector back to the overlapping distribution for another update phase. This would be a reverse mode Import, using the precomputed Export object.

Another use case for reverse mode is in CrsMatrix, for the transpose version of distributed sparse matrix-vector multiply ("mat-vec"). Non-transpose mat-vec (a function from the domain Map to the range Map) does an Import to bring in the source vector's data from the domain Map to the column Map of the sparse matrix, and an Export (if necessary) to bring the results from the row Map of the sparse matrix to the range Map. Transpose mat-vec (a function from the range Map to the domain Map) uses these precomputed Import and Export objects in reverse mode: first the Export in reverse mode to Import the source vector's data to the row Map, and then the Import in reverse mode to Export the results to the domain Map. Reverse mode lets us reuse the precomputed data redistribution plans for the transpose case.

How to implement a subclass

If you want to implement your own DistObject subclass, you should start by implementing the four pure virtual methods: checkSizes(), copyAndPermute(), packAndPrepare(), and unpackAndCombine(). The implementation of doTransfer() includes documentation that explains how DistObject uses those methods to do data redistribution.

If you are writing a DistObject class that uses Kokkos compute buffers and aims to work for any Kokkos Node type, you should also implement the three hooks that create and release views: createViews(), createViewsNonConst(), and releaseViews(). The default implementation of these hooks does nothing. The documentation of these methods explains different ways you might choose to implement them.

DistObject implements SrcDistObject, because we presume that if an object can be the target of an Import or Export, it can also be the source of an Import or Export.

Definition at line 172 of file Tpetra_DistObject_decl.hpp.

Member Typedef Documentation

template<class Packet, class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>

typedef Packet Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >::packet_type

The type of each datum being sent or received in an Import or Export.

Note that this type does not always correspond to the Scalar template parameter of subclasses.

Reimplemented in Tpetra::Experimental::BlockMultiVector< Scalar, LO, GO, Node >, and Tpetra::Experimental::BlockCrsMatrix< Scalar, LO, GO, Node >.

Definition at line 183 of file Tpetra_DistObject_decl.hpp.

template<class Packet, class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>

typedef LocalOrdinal Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >::local_ordinal_type

The type of local indices.

Definition at line 185 of file Tpetra_DistObject_decl.hpp.

template<class Packet, class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>

typedef GlobalOrdinal Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >::global_ordinal_type

The type of global indices.

Definition at line 187 of file Tpetra_DistObject_decl.hpp.

template<class Packet, class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>

typedef Node Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >::node_type

The Kokkos Node type.

Definition at line 189 of file Tpetra_DistObject_decl.hpp.

Member Enumeration Documentation

template<class Packet, class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>

enum Tpetra::DistObject::ReverseOption [protected]

Whether the data transfer should be performed in forward or reverse mode.

"Reverse mode" means calling doExport() with an Import object, or calling doImport() with an Export object. "Forward mode" means calling doExport() with an Export object, or calling doImport() with an Import object.

Definition at line 417 of file Tpetra_DistObject_decl.hpp.

Constructor & Destructor Documentation

template<class Packet , class LocalOrdinal, class GlobalOrdinal, class Node>

Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >::DistObject ( const Teuchos::RCP< const Map< LocalOrdinal, GlobalOrdinal, Node > > & map ) [explicit]

Constructor.

Definition at line 59 of file Tpetra_DistObject_def.hpp.

template<class Packet, class LocalOrdinal, class GlobalOrdinal, class Node>

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

Copy constructor.

Definition at line 111 of file Tpetra_DistObject_def.hpp.

template<class Packet , class LocalOrdinal , class GlobalOrdinal , class Node >

Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >::~DistObject ( ) [virtual]

Destructor (virtual for memory safety of derived classes).

Definition at line 116 of file Tpetra_DistObject_def.hpp.

Member Function Documentation

template<class Packet , class LocalOrdinal, class GlobalOrdinal, class Node>

void Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >::doImport	(	const SrcDistObject< Packet, LocalOrdinal, GlobalOrdinal, Node > &	source,
		const Import< LocalOrdinal, GlobalOrdinal, Node > &	importer,
		CombineMode	CM
	)

Import data into this object using an Import object ("forward mode").

The input DistObject is always the source of the data redistribution operation, and the *this object is always the target.

If you don't know the difference between forward and reverse mode, then you probably want forward mode. Use this method with your precomputed Import object if you want to do an Import, else use doExport() with a precomputed Export object.

Parameters:

source	[in] The "source" object for redistribution.
importer	[in] Precomputed data redistribution plan. Its source Map must be the same as the input DistObject's Map, and its target Map must be the same as `this->getMap()`.
CM	[in] How to combine incoming data with the same global index.

Definition at line 196 of file Tpetra_DistObject_def.hpp.

template<class Packet , class LocalOrdinal, class GlobalOrdinal, class Node>

void Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >::doExport	(	const SrcDistObject< Packet, LocalOrdinal, GlobalOrdinal, Node > &	source,
		const Export< LocalOrdinal, GlobalOrdinal, Node > &	exporter,
		CombineMode	CM
	)

Export data into this object using an Export object ("forward mode").

The input DistObject is always the source of the data redistribution operation, and the *this object is always the target.

If you don't know the difference between forward and reverse mode, then you probably want forward mode. Use this method with your precomputed Export object if you want to do an Export, else use doImport() with a precomputed Import object.

Parameters:

source	[in] The "source" object for redistribution.
exporter	[in] Precomputed data redistribution plan. Its source Map must be the same as the input DistObject's Map, and its target Map must be the same as `this->getMap()`.
CM	[in] How to combine incoming data with the same global index.

Definition at line 228 of file Tpetra_DistObject_def.hpp.

template<class Packet , class LocalOrdinal, class GlobalOrdinal, class Node>

void Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >::doImport	(	const SrcDistObject< Packet, LocalOrdinal, GlobalOrdinal, Node > &	source,
		const Export< LocalOrdinal, GlobalOrdinal, Node > &	exporter,
		CombineMode	CM
	)

Import data into this object using an Export object ("reverse mode").

The input DistObject is always the source of the data redistribution operation, and the *this object is always the target.

If you don't know the difference between forward and reverse mode, then you probably want forward mode. Use the version of doImport() that takes a precomputed Import object in that case.

Parameters:

source	[in] The "source" object for redistribution.
exporter	[in] Precomputed data redistribution plan. Its target Map must be the same as the input DistObject's Map, and its source Map must be the same as `this->getMap()`. (Note the difference from forward mode.)
CM	[in] How to combine incoming data with the same global index.

Definition at line 260 of file Tpetra_DistObject_def.hpp.

template<class Packet , class LocalOrdinal, class GlobalOrdinal, class Node>

void Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >::doExport	(	const SrcDistObject< Packet, LocalOrdinal, GlobalOrdinal, Node > &	source,
		const Import< LocalOrdinal, GlobalOrdinal, Node > &	importer,
		CombineMode	CM
	)

Export data into this object using an Import object ("reverse mode").

The input DistObject is always the source of the data redistribution operation, and the *this object is always the target.

If you don't know the difference between forward and reverse mode, then you probably want forward mode. Use the version of doExport() that takes a precomputed Export object in that case.

Parameters:

source	[in] The "source" object for redistribution.
importer	[in] Precomputed data redistribution plan. Its target Map must be the same as the input DistObject's Map, and its source Map must be the same as `this->getMap()`. (Note the difference from forward mode.)
CM	[in] How to combine incoming data with the same global index.

Definition at line 293 of file Tpetra_DistObject_def.hpp.

template<class Packet , class LocalOrdinal , class GlobalOrdinal , class Node >

bool Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >::isDistributed ( ) const

Whether this is a globally distributed object.

For a definition of "globally distributed" (and its opposite, "locally replicated"), see the documentation of Map's isDistributed() method.

Definition at line 325 of file Tpetra_DistObject_def.hpp.

template<class Packet, class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>

virtual Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >::getMap ( ) const [inline, virtual]

The Map describing the parallel distribution of this object.

Note that some Tpetra objects might be distributed using multiple Map objects. For example, CrsMatrix has both a row Map and a column Map. It is up to the subclass to decide which Map to use when invoking the DistObject constructor.

Definition at line 316 of file Tpetra_DistObject_decl.hpp.

template<class Packet , class LocalOrdinal , class GlobalOrdinal , class Node >

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

Print this object to the given output stream.

We generally assume that all MPI processes can print to the given stream.

Definition at line 548 of file Tpetra_DistObject_def.hpp.

template<class Packet , class LocalOrdinal , class GlobalOrdinal , class Node >

std::string Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >::description ( ) const [virtual]

One-line descriptiion of this object.

We declare this method virtual so that subclasses of DistObject may override it.

Reimplemented in Tpetra::CrsMatrix< Scalar, LocalOrdinal, GlobalOrdinal, Node >, Tpetra::CrsMatrix< Scalar, LocalOrdinal, GlobalOrdinal, Kokkos::Compat::KokkosDeviceWrapperNode< DeviceType > >, Tpetra::MultiVector< Scalar, LocalOrdinal, GlobalOrdinal, Node >, Tpetra::MultiVector< Scalar, LocalOrdinal, GlobalOrdinal, Kokkos::Compat::KokkosDeviceWrapperNode< DeviceType > >, Tpetra::MultiVector< scalar_type, local_ordinal_type, global_ordinal_type, node_type >, Tpetra::CrsGraph< LocalOrdinal, GlobalOrdinal, Node >, Tpetra::CrsGraph< LO, GO, node_type >, Tpetra::CrsGraph< LocalOrdinal, GlobalOrdinal, Kokkos::Compat::KokkosDeviceWrapperNode< DeviceType > >, Tpetra::VbrMatrix< Scalar, LocalOrdinal, GlobalOrdinal, Node >, Tpetra::Vector< Scalar, LocalOrdinal, GlobalOrdinal, Node >, Tpetra::Vector< Scalar, LocalOrdinal, GlobalOrdinal, Kokkos::Compat::KokkosDeviceWrapperNode< DeviceType > >, and Tpetra::Experimental::BlockCrsMatrix< Scalar, LO, GO, Node >.

Definition at line 121 of file Tpetra_DistObject_def.hpp.

template<class Packet , class LocalOrdinal , class GlobalOrdinal , class Node >

void Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >::describe	(	Teuchos::FancyOStream &	out,
		const Teuchos::EVerbosityLevel	verbLevel = `Teuchos::Describable::verbLevel_default`
	)		const `[virtual]`

Print a descriptiion of this object to the given output stream.

We declare this method virtual so that subclasses of Distobject may override it.

Reimplemented in Tpetra::CrsMatrix< Scalar, LocalOrdinal, GlobalOrdinal, Node >, Tpetra::CrsMatrix< Scalar, LocalOrdinal, GlobalOrdinal, Kokkos::Compat::KokkosDeviceWrapperNode< DeviceType > >, Tpetra::MultiVector< Scalar, LocalOrdinal, GlobalOrdinal, Node >, Tpetra::MultiVector< Scalar, LocalOrdinal, GlobalOrdinal, Kokkos::Compat::KokkosDeviceWrapperNode< DeviceType > >, Tpetra::MultiVector< scalar_type, local_ordinal_type, global_ordinal_type, node_type >, Tpetra::CrsGraph< LocalOrdinal, GlobalOrdinal, Node >, Tpetra::CrsGraph< LO, GO, node_type >, Tpetra::CrsGraph< LocalOrdinal, GlobalOrdinal, Kokkos::Compat::KokkosDeviceWrapperNode< DeviceType > >, Tpetra::VbrMatrix< Scalar, LocalOrdinal, GlobalOrdinal, Node >, Tpetra::Vector< Scalar, LocalOrdinal, GlobalOrdinal, Node >, Tpetra::Vector< Scalar, LocalOrdinal, GlobalOrdinal, Kokkos::Compat::KokkosDeviceWrapperNode< DeviceType > >, and Tpetra::Experimental::BlockCrsMatrix< Scalar, LO, GO, Node >.

Definition at line 138 of file Tpetra_DistObject_def.hpp.

template<class Packet , class LocalOrdinal, class GlobalOrdinal, class Node>

void Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >::removeEmptyProcessesInPlace ( const Teuchos::RCP< const Map< LocalOrdinal, GlobalOrdinal, Node > > & newMap ) [virtual]

Remove processes which contain no elements in this object's Map.

Warning:: This method is ONLY for use by experts. We highly recommend using the nonmember function of the same name defined in this file.; We make NO promises of backwards compatibility. This method may change or disappear at any time.

On input, this object is distributed over the Map returned by getMap() (the "original Map," with its communicator, the "original communicator"). The input newMap of this method must be the same as the result of calling getMap()->removeEmptyProcesses(). On processes in the original communicator which contain zero elements ("excluded processes," as opposed to "included processes"), the input newMap must be Teuchos::null (which is what getMap()->removeEmptyProcesses() returns anyway).

On included processes, reassign this object's Map (that would be returned by getMap()) to the input newMap, and do any work that needs to be done to restore correct semantics. On excluded processes, free any data that needs freeing, and do any other work that needs to be done to restore correct semantics.

This method has collective semantics over the original communicator. On exit, the only method of this object which is safe to call on excluded processes is the destructor. This implies that subclasses' destructors must not contain communication operations.

Returns:: The object's new Map. Its communicator is a new communicator, distinct from the old Map's communicator, which contains a subset of the processes in the old communicator.

Note:: The name differs from Map's method removeEmptyProcesses(), in order to emphasize that the operation on DistObject happens in place, modifying the input, whereas the operation removeEmptyProcess() on Map does not modify the input.; To implementers of DistObject subclasses: The default implementation of this class throws std::logic_error.

Reimplemented in Tpetra::MultiVector< Scalar, LocalOrdinal, GlobalOrdinal, Node >, Tpetra::MultiVector< Scalar, LocalOrdinal, GlobalOrdinal, Kokkos::Compat::KokkosDeviceWrapperNode< DeviceType > >, and Tpetra::MultiVector< scalar_type, local_ordinal_type, global_ordinal_type, node_type >.

Definition at line 160 of file Tpetra_DistObject_def.hpp.

template<class Packet , class LocalOrdinal , class GlobalOrdinal , class Node >

size_t Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >::constantNumberOfPackets ( ) const [protected, virtual]

Whether the implementation's instance promises always to have a constant number of packets per LID, and if so, how many packets per LID there are.

If this method returns zero, the instance says that it might possibly have a different number of packets for each LID to send or receive. If it returns nonzero, the instance promises that the number of packets is the same for all LIDs, and that the return value is this number of packets per LID.

The default implementation of this method returns zero. This does not affect the behavior of doTransfer() in any way. If a nondefault implementation returns nonzero, doTransfer() will use this information to avoid unnecessary allocation and / or resizing of arrays.

Reimplemented in Tpetra::MultiVector< Scalar, LocalOrdinal, GlobalOrdinal, Node >, Tpetra::MultiVector< Scalar, LocalOrdinal, GlobalOrdinal, Kokkos::Compat::KokkosDeviceWrapperNode< DeviceType > >, and Tpetra::MultiVector< scalar_type, local_ordinal_type, global_ordinal_type, node_type >.

Definition at line 332 of file Tpetra_DistObject_def.hpp.

template<class Packet , class LocalOrdinal, class GlobalOrdinal , class Node >

void Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >::doTransfer	(	const SrcDistObject< Packet, LocalOrdinal, GlobalOrdinal, Node > &	src,
		CombineMode	CM,
		size_t	numSameIDs,
		const Teuchos::ArrayView< const LocalOrdinal > &	permuteToLIDs,
		const Teuchos::ArrayView< const LocalOrdinal > &	permuteFromLIDs,
		const Teuchos::ArrayView< const LocalOrdinal > &	remoteLIDs,
		const Teuchos::ArrayView< const LocalOrdinal > &	exportLIDs,
		Distributor &	distor,
		ReverseOption	revOp
	)		`[protected, virtual]`

Redistribute data across memory images.

Parameters:

src	[in] The source object, to redistribute into the target object, which is `*this` object.
CM	[in] The combine mode that describes how to combine values that map to the same global ID on the same process.
permuteToLIDs	[in] See copyAndPermute().
permuteFromLIDs	[in] See copyAndPermute().
remoteLIDs	[in] List of entries (as local IDs) in the destination object to receive from other processes.
exportLIDs	[in] See packAndPrepare().
distor	[in/out] The Distributor object that knows how to redistribute data.
revOp	[in] Whether to do a forward or reverse mode redistribution.

Definition at line 339 of file Tpetra_DistObject_def.hpp.

template<class Packet, class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>

virtual bool Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >::checkSizes ( const SrcDistObject< Packet, LocalOrdinal, GlobalOrdinal, Node > & source ) [protected, pure virtual]

Compare the source and target (this) objects for compatibility.

Returns:: True if they are compatible, else false.

Implemented in Tpetra::CrsMatrix< Scalar, LocalOrdinal, GlobalOrdinal, Node >, Tpetra::CrsMatrix< Scalar, LocalOrdinal, GlobalOrdinal, Kokkos::Compat::KokkosDeviceWrapperNode< DeviceType > >, Tpetra::MultiVector< Scalar, LocalOrdinal, GlobalOrdinal, Node >, Tpetra::MultiVector< Scalar, LocalOrdinal, GlobalOrdinal, Kokkos::Compat::KokkosDeviceWrapperNode< DeviceType > >, Tpetra::MultiVector< scalar_type, local_ordinal_type, global_ordinal_type, node_type >, Tpetra::CrsGraph< LocalOrdinal, GlobalOrdinal, Node >, Tpetra::CrsGraph< LO, GO, node_type >, Tpetra::CrsGraph< LocalOrdinal, GlobalOrdinal, Kokkos::Compat::KokkosDeviceWrapperNode< DeviceType > >, Tpetra::Experimental::BlockCrsMatrix< Scalar, LO, GO, Node >, Tpetra::VbrMatrix< Scalar, LocalOrdinal, GlobalOrdinal, Node >, and Tpetra::Experimental::BlockMultiVector< Scalar, LO, GO, Node >.

template<class Packet, class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>

virtual void Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >::copyAndPermute	(	const SrcDistObject< Packet, LocalOrdinal, GlobalOrdinal, Node > &	source,
		size_t	numSameIDs,
		const Teuchos::ArrayView< const LocalOrdinal > &	permuteToLIDs,
		const Teuchos::ArrayView< const LocalOrdinal > &	permuteFromLIDs
	)		`[protected, pure virtual]`

Perform copies and permutations that are local to this process.

Parameters:

source	[in] On entry, the source object, from which we are distributing. We distribute to the destination object, which is `*this` object.
numSameIDs	[in] The umber of elements that are the same on the source and destination (this) objects. These elements are owned by the same process in both the source and destination objects. No permutation occurs.
numPermuteIDs	[in] The number of elements that are locally permuted between the source and destination objects.
permuteToLIDs	[in] List of the elements that are permuted. They are listed by their LID in the destination object.
permuteFromLIDs	[in] List of the elements that are permuted. They are listed by their LID in the source object.

Implemented in Tpetra::CrsGraph< LocalOrdinal, GlobalOrdinal, Node >, Tpetra::CrsGraph< LocalOrdinal, GlobalOrdinal, Kokkos::Compat::KokkosDeviceWrapperNode< DeviceType > >, Tpetra::Experimental::BlockCrsMatrix< Scalar, LO, GO, Node >, Tpetra::VbrMatrix< Scalar, LocalOrdinal, GlobalOrdinal, Node >, and Tpetra::Experimental::BlockMultiVector< Scalar, LO, GO, Node >.

template<class Packet, class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>

virtual void Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >::packAndPrepare	(	const SrcDistObject< Packet, LocalOrdinal, GlobalOrdinal, Node > &	source,
		const Teuchos::ArrayView< const LocalOrdinal > &	exportLIDs,
		Teuchos::Array< Packet > &	exports,
		const Teuchos::ArrayView< size_t > &	numPacketsPerLID,
		size_t &	constantNumPackets,
		Distributor &	distor
	)		`[protected, pure virtual]`

Perform any packing or preparation required for communication.

Parameters:

source	[in] Source object for the redistribution.
exportLIDs	[in] List of the entries (as local IDs in the source object) we will be sending to other images.
exports	[out] On exit, the buffer for data to send.
numPacketsPerLID	[out] On exit, the implementation of this method must do one of two things: set numPacketsPerLID[i] to contain the number of packets to be exported for exportLIDs[i] and set constantNumPackets to zero, or set constantNumPackets to a nonzero value. If the latter, the implementation need not fill numPacketsPerLID.
constantNumPackets	[out] On exit, 0 if numPacketsPerLID has variable contents (different size for each LID). If nonzero, then it is expected that the number of packets per LID is constant, and that constantNumPackets is that value.
distor	[in] The Distributor object we are using.

Implemented in Tpetra::CrsMatrix< Scalar, LocalOrdinal, GlobalOrdinal, Node >, Tpetra::CrsMatrix< Scalar, LocalOrdinal, GlobalOrdinal, Kokkos::Compat::KokkosDeviceWrapperNode< DeviceType > >, Tpetra::CrsGraph< LocalOrdinal, GlobalOrdinal, Node >, Tpetra::CrsGraph< LocalOrdinal, GlobalOrdinal, Kokkos::Compat::KokkosDeviceWrapperNode< DeviceType > >, Tpetra::Experimental::BlockCrsMatrix< Scalar, LO, GO, Node >, Tpetra::VbrMatrix< Scalar, LocalOrdinal, GlobalOrdinal, Node >, and Tpetra::Experimental::BlockMultiVector< Scalar, LO, GO, Node >.

template<class Packet, class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>

virtual void Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >::unpackAndCombine	(	const Teuchos::ArrayView< const LocalOrdinal > &	importLIDs,
		const Teuchos::ArrayView< const Packet > &	imports,
		const Teuchos::ArrayView< size_t > &	numPacketsPerLID,
		size_t	constantNumPackets,
		Distributor &	distor,
		CombineMode	CM
	)		`[protected, pure virtual]`

Perform any unpacking and combining after communication.

Parameters:

importLIDs	[in] List of the entries (as LIDs in the destination object) we received from other images.
imports	[in] Buffer containing data we received.
numPacketsPerLID	[in] If constantNumPackets is zero, then numPacketsPerLID[i] contains the number of packets imported for importLIDs[i].
constantNumPackets	[in] If nonzero, then numPacketsPerLID is constant (same value in all entries) and constantNumPackets is that value. If zero, then numPacketsPerLID[i] is the number of packets imported for importLIDs[i].
distor	[in] The Distributor object we are using.
CM	[in] The combine mode to use when combining the imported entries with existing entries.

Implemented in Tpetra::CrsMatrix< Scalar, LocalOrdinal, GlobalOrdinal, Node >, Tpetra::CrsMatrix< Scalar, LocalOrdinal, GlobalOrdinal, Kokkos::Compat::KokkosDeviceWrapperNode< DeviceType > >, Tpetra::CrsGraph< LocalOrdinal, GlobalOrdinal, Node >, Tpetra::CrsGraph< LocalOrdinal, GlobalOrdinal, Kokkos::Compat::KokkosDeviceWrapperNode< DeviceType > >, Tpetra::Experimental::BlockCrsMatrix< Scalar, LO, GO, Node >, Tpetra::VbrMatrix< Scalar, LocalOrdinal, GlobalOrdinal, Node >, and Tpetra::Experimental::BlockMultiVector< Scalar, LO, GO, Node >.

template<class Packet , class LocalOrdinal , class GlobalOrdinal , class Node >

void Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >::createViews ( ) const [protected, virtual]

Hook for creating a const view.

doTransfer() calls this on the source object. By default, it does nothing, but the source object can use this as a hint to fetch data from a compute buffer on an off-CPU device (such as a GPU) into host memory.

Reimplemented in Tpetra::MultiVector< Scalar, LocalOrdinal, GlobalOrdinal, Node >, Tpetra::MultiVector< Scalar, LocalOrdinal, GlobalOrdinal, Kokkos::Compat::KokkosDeviceWrapperNode< DeviceType > >, and Tpetra::MultiVector< scalar_type, local_ordinal_type, global_ordinal_type, node_type >.

Definition at line 562 of file Tpetra_DistObject_def.hpp.

template<class Packet , class LocalOrdinal , class GlobalOrdinal , class Node >

void Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >::createViewsNonConst ( KokkosClassic::ReadWriteOption rwo ) [protected, virtual]

Hook for creating a nonconst view.

doTransfer() calls this on the destination (*this) object. By default, it does nothing, but the destination object can use this as a hint to fetch data from a compute buffer on an off-CPU device (such as a GPU) into host memory.

Parameters:

rwo [in] Whether to create a write-only or a read-and-write view. For Kokkos Node types where compute buffers live in a separate memory space (e.g., in the device memory of a discrete accelerator like a GPU), a write-only view only requires copying from host memory to the compute buffer, whereas a read-and-write view requires copying both ways (once to read, from the compute buffer to host memory, and once to write, back to the compute buffer).

Reimplemented in Tpetra::MultiVector< Scalar, LocalOrdinal, GlobalOrdinal, Node >, Tpetra::MultiVector< Scalar, LocalOrdinal, GlobalOrdinal, Kokkos::Compat::KokkosDeviceWrapperNode< DeviceType > >, and Tpetra::MultiVector< scalar_type, local_ordinal_type, global_ordinal_type, node_type >.

Definition at line 568 of file Tpetra_DistObject_def.hpp.

template<class Packet , class LocalOrdinal , class GlobalOrdinal , class Node >

void Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >::releaseViews ( ) const [protected, virtual]

Hook for releasing views.

doTransfer() calls this on both the source and destination objects, once it no longer needs to access that object's data. By default, this method does nothing. Implementations may use this as a hint to free host memory which is a view of a compute buffer, once the host memory view is no longer needed. Some implementations may prefer to mirror compute buffers in host memory; for these implementations, releaseViews() may do nothing.

Reimplemented in Tpetra::MultiVector< Scalar, LocalOrdinal, GlobalOrdinal, Node >, Tpetra::MultiVector< Scalar, LocalOrdinal, GlobalOrdinal, Kokkos::Compat::KokkosDeviceWrapperNode< DeviceType > >, and Tpetra::MultiVector< scalar_type, local_ordinal_type, global_ordinal_type, node_type >.

Definition at line 574 of file Tpetra_DistObject_def.hpp.

Member Data Documentation

template<class Packet, class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>

Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >::map_ [protected]

The Map over which this object is distributed.

Definition at line 611 of file Tpetra_DistObject_decl.hpp.

template<class Packet, class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>

Teuchos::Array<Packet> Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >::imports_ [protected]

Buffer into which packed data are imported (received from other processes).

Definition at line 615 of file Tpetra_DistObject_decl.hpp.

template<class Packet, class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>

Teuchos::Array<size_t> Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >::numImportPacketsPerLID_ [protected]

Number of packets to receive for each receive operation.

This array is used in Distributor::doPosts() (and doReversePosts()) when starting the ireceive operation.

This may be ignored in doTransfer() if constantNumPackets is nonzero, indicating a constant number of packets per LID. (For example, MultiVector sets the constantNumPackets output argument of packAndPrepare() to the number of columns in the multivector.)

Definition at line 627 of file Tpetra_DistObject_decl.hpp.

template<class Packet, class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>

Teuchos::Array<Packet> Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >::exports_ [protected]

Buffer from which packed data are exported (sent to other processes).

Definition at line 630 of file Tpetra_DistObject_decl.hpp.

template<class Packet, class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>

Teuchos::Array<size_t> Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >::numExportPacketsPerLID_ [protected]

Number of packets to send for each send operation.

This array is used in Distributor::doPosts() (and doReversePosts()) for preparing for the send operation.

This may be ignored in doTransfer() if constantNumPackets is nonzero, indicating a constant number of packets per LID. (For example, MultiVector sets the constantNumPackets output argument of packAndPrepare() to the number of columns in the multivector.)

Definition at line 642 of file Tpetra_DistObject_decl.hpp.

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

Public Types

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Methods for use only by experts

Detailed Description

template<class Packet, class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type> class Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >

Summary

Forward or reverse redistribution modes

How to implement a subclass

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

template<class Packet, class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>
class Tpetra::DistObject< Packet, LocalOrdinal, GlobalOrdinal, Node >