Tpetra Matrix/Vector Services Version of the Day
Public Types | Related Functions
Tpetra::Import< LocalOrdinal, GlobalOrdinal, Node > Class Template Reference

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

#include <Tpetra_Import_decl.hpp>

Inherits Tpetra::Details::Transfer< LO, GO, NT >.

List of all members.

Public Types

typedef ::Tpetra::Map
< LocalOrdinal, GlobalOrdinal,
Node > 
map_type
 The specialization of Map used by this class.

Public Member Functions

Constructor/Destructor Methods
 Import (const Teuchos::RCP< const map_type > &source, const Teuchos::RCP< const map_type > &target)
 Construct an Import from the source and target Maps.
 Import (const Teuchos::RCP< const map_type > &source, const Teuchos::RCP< const map_type > &target, const RCP< Teuchos::FancyOStream > &out)
 Construct an Import from the source and target Maps, with an output stream for debugging output.
 Import (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)
 Import (const Teuchos::RCP< const map_type > &source, const Teuchos::RCP< const map_type > &target, const RCP< Teuchos::FancyOStream > &out, const Teuchos::RCP< Teuchos::ParameterList > &plist)
 Constructor (with list of parameters and debug output stream)
 Import (const Teuchos::RCP< const map_type > &source, const Teuchos::RCP< const map_type > &target, Teuchos::Array< int > &remotePIDs)
 Construct an Import from the source and target Maps.
 Import (const Import< LocalOrdinal, GlobalOrdinal, Node > &importer)
 Copy constructor.
 Import (const Export< LocalOrdinal, GlobalOrdinal, Node > &exporter)
 "Copy" constructor from an Export object.
virtual ~Import ()
 Destructor.
void setParameterList (const Teuchos::RCP< Teuchos::ParameterList > &plist)
 Set parameters.
Import Attribute Methods
size_t getNumSameIDs () const
 Number of initial identical IDs.
size_t getNumPermuteIDs () const
 Number of IDs to permute but not to communicate.
ArrayView< const LocalOrdinal > getPermuteFromLIDs () const
 List of local IDs in the source Map that are permuted.
ArrayView< const LocalOrdinal > getPermuteToLIDs () const
 List of local IDs in the target Map that are permuted.
size_t getNumRemoteIDs () const
 Number of entries not on the calling process.
ArrayView< const LocalOrdinal > getRemoteLIDs () const
 List of entries in the target Map to receive from other processes.
size_t getNumExportIDs () const
 Number of entries that must be sent by the calling process to other processes.
ArrayView< const LocalOrdinal > getExportLIDs () const
 List of entries in the source Map that will be sent to other processes.
ArrayView< const int > getExportPIDs () const
 List of processes to which entries will be sent.
Teuchos::RCP< const map_typegetSourceMap () const
 The Source Map used to construct this Import object.
Teuchos::RCP< const map_typegetTargetMap () const
 The Target Map used to construct this Import object.
DistributorgetDistributor () const
 The Distributor that this Import object uses to move data.
Import< LocalOrdinal,
GlobalOrdinal, Node > & 
operator= (const Import< LocalOrdinal, GlobalOrdinal, Node > &Source)
 Assignment operator.
Teuchos::RCP< const Import
< LocalOrdinal, GlobalOrdinal,
Node > > 
setUnion (const Import< LocalOrdinal, GlobalOrdinal, Node > &rhs) const
 Return the union of this Import and rhs.
Teuchos::RCP< const Import
< LocalOrdinal, GlobalOrdinal,
Node > > 
setUnion () const
 Return the union of this Import this->getSourceMap()
Teuchos::RCP< const Import
< LocalOrdinal, GlobalOrdinal,
Node > > 
createRemoteOnlyImport (const Teuchos::RCP< const map_type > &remoteTarget) const
 Returns an importer that contains only the remote entries of this.
I/O Methods
virtual void print (std::ostream &os) const
 Print the Import's data to the given output stream.

Related Functions

(Note that these are not member functions.)

template<class LocalOrdinal , class GlobalOrdinal , class Node >
Teuchos::RCP< const Import
< LocalOrdinal, GlobalOrdinal,
Node > > 
createImport (const Teuchos::RCP< const Map< LocalOrdinal, GlobalOrdinal, Node > > &src, const Teuchos::RCP< const Map< LocalOrdinal, GlobalOrdinal, Node > > &tgt)
 Nonmember constructor for Import.
template<class LocalOrdinal , class GlobalOrdinal , class Node >
Teuchos::RCP< const Import
< LocalOrdinal, GlobalOrdinal,
Node > > 
createImport (const Teuchos::RCP< const Map< LocalOrdinal, GlobalOrdinal, Node > > &src, const Teuchos::RCP< const Map< LocalOrdinal, GlobalOrdinal, Node > > &tgt, const Teuchos::RCP< Teuchos::ParameterList > &plist)
 Nonmember constructor for Import that takes a ParameterList.

Detailed Description

template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = KokkosClassic::DefaultNode::DefaultNodeType>
class Tpetra::Import< LocalOrdinal, GlobalOrdinal, Node >

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

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.

As mentioned above, one use case of Import is bringing in remote source vector data for a distributed sparse matrix-vector multiply. The source vector itself is uniquely owned, but must be brought in into an overlapping distribution so that each process can compute its part of the target vector without further communication.

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:

Definition at line 117 of file Tpetra_Import_decl.hpp.


Member Typedef Documentation

template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = KokkosClassic::DefaultNode::DefaultNodeType>
typedef ::Tpetra::Map<LocalOrdinal, GlobalOrdinal, Node> Tpetra::Import< LocalOrdinal, GlobalOrdinal, Node >::map_type

The specialization of Map used by this class.

Definition at line 125 of file Tpetra_Import_decl.hpp.


Constructor & Destructor Documentation

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

Construct an Import from the source and target Maps.

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

Definition at line 140 of file Tpetra_Import_def.hpp.

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

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

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

Definition at line 151 of file Tpetra_Import_def.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >
Tpetra::Import< LocalOrdinal, GlobalOrdinal, Node >::Import ( 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 must be a uniquely owned (nonoverlapping) distribution.
target[in] The target distribution. This may be a multiply owned (overlapping) 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 163 of file Tpetra_Import_def.hpp.

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

Constructor (with list of parameters and debug output stream)

Parameters:
source[in] The source distribution. This must be a uniquely owned (nonoverlapping) distribution.
target[in] The target distribution. This may be a multiply owned (overlapping) distribution.
out[in/out] Output stream (for printing copious debug output on all processes, if that option is enabled).
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 175 of file Tpetra_Import_def.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >
Tpetra::Import< LocalOrdinal, GlobalOrdinal, Node >::Import ( const Teuchos::RCP< const map_type > &  source,
const Teuchos::RCP< const map_type > &  target,
Teuchos::Array< int > &  remotePIDs 
)

Construct an Import from the source and target Maps.

Parameters:
source[in] The source distribution. This must be a uniquely owned (nonoverlapping) distribution.
target[in] The target distribution. This may be a multiply owned (overlapping) distribution.
remotePIDs[in] Owning PIDs corresponding to the remoteGIDs. If this information is available one can reduce the cost of the Import constructor.

Definition at line 188 of file Tpetra_Import_def.hpp.

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

Copy constructor.

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

Definition at line 199 of file Tpetra_Import_def.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >
Tpetra::Import< LocalOrdinal, GlobalOrdinal, Node >::Import ( const Export< LocalOrdinal, GlobalOrdinal, Node > &  exporter)

"Copy" constructor from an Export object.

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

Definition at line 207 of file Tpetra_Import_def.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >
Tpetra::Import< LocalOrdinal, GlobalOrdinal, Node >::~Import ( ) [virtual]

Destructor.

Definition at line 269 of file Tpetra_Import_def.hpp.


Member Function Documentation

template<class LocalOrdinal , class GlobalOrdinal , class Node >
void Tpetra::Import< LocalOrdinal, GlobalOrdinal, Node >::setParameterList ( const Teuchos::RCP< Teuchos::ParameterList > &  plist)

Set parameters.

Please see the class documentation for a list of all accepted parameters and their default values.

Definition at line 68 of file Tpetra_Import_def.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >
size_t Tpetra::Import< LocalOrdinal, GlobalOrdinal, Node >::getNumSameIDs ( ) const

Number of initial identical IDs.

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

Definition at line 273 of file Tpetra_Import_def.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >
size_t Tpetra::Import< LocalOrdinal, GlobalOrdinal, Node >::getNumPermuteIDs ( ) const

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 will permute these entries locally (without distributed-memory communication).

Definition at line 278 of file Tpetra_Import_def.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >
ArrayView< const LocalOrdinal > Tpetra::Import< LocalOrdinal, GlobalOrdinal, Node >::getPermuteFromLIDs ( ) const

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

Definition at line 284 of file Tpetra_Import_def.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >
ArrayView< const LocalOrdinal > Tpetra::Import< LocalOrdinal, GlobalOrdinal, Node >::getPermuteToLIDs ( ) const

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

Definition at line 290 of file Tpetra_Import_def.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >
size_t Tpetra::Import< LocalOrdinal, GlobalOrdinal, Node >::getNumRemoteIDs ( ) const

Number of entries not on the calling process.

Definition at line 295 of file Tpetra_Import_def.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >
ArrayView< const LocalOrdinal > Tpetra::Import< LocalOrdinal, GlobalOrdinal, Node >::getRemoteLIDs ( ) const

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

Definition at line 301 of file Tpetra_Import_def.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >
size_t Tpetra::Import< LocalOrdinal, GlobalOrdinal, Node >::getNumExportIDs ( ) const

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

Definition at line 306 of file Tpetra_Import_def.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >
ArrayView< const LocalOrdinal > Tpetra::Import< LocalOrdinal, GlobalOrdinal, Node >::getExportLIDs ( ) const

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

Definition at line 312 of file Tpetra_Import_def.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >
ArrayView< const int > Tpetra::Import< LocalOrdinal, GlobalOrdinal, Node >::getExportPIDs ( ) const

List of processes to which entries will be sent.

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

Definition at line 318 of file Tpetra_Import_def.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >
Teuchos::RCP< const typename Import< LocalOrdinal, GlobalOrdinal, Node >::map_type > Tpetra::Import< LocalOrdinal, GlobalOrdinal, Node >::getSourceMap ( ) const

The Source Map used to construct this Import object.

Definition at line 324 of file Tpetra_Import_def.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >
Teuchos::RCP< const typename Import< LocalOrdinal, GlobalOrdinal, Node >::map_type > Tpetra::Import< LocalOrdinal, GlobalOrdinal, Node >::getTargetMap ( ) const

The Target Map used to construct this Import object.

Definition at line 330 of file Tpetra_Import_def.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >
Distributor & Tpetra::Import< LocalOrdinal, GlobalOrdinal, Node >::getDistributor ( ) const

The Distributor that this Import object uses to move data.

Definition at line 336 of file Tpetra_Import_def.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >
Import< LocalOrdinal, GlobalOrdinal, Node > & Tpetra::Import< LocalOrdinal, GlobalOrdinal, Node >::operator= ( const Import< LocalOrdinal, GlobalOrdinal, Node > &  Source)

Assignment operator.

Definition at line 343 of file Tpetra_Import_def.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >
Teuchos::RCP< const Import< LocalOrdinal, GlobalOrdinal, Node > > Tpetra::Import< LocalOrdinal, GlobalOrdinal, Node >::setUnion ( const Import< LocalOrdinal, GlobalOrdinal, Node > &  rhs) const

Return the union of this Import and rhs.

The "union" of two Import objects is the Import whose source Map is the same as the input Imports' source Maps, and whose target Map is the union of the two input Imports' target Maps. The two input Import objects must have the same source Map. The union operation is symmetric in its two inputs.

The communicator of rhs must be the same as (MPI_EQUAL) or congruent with (MPI_CONGRUENT) this Import's communicator. (That is, the two communicators must have the same number of processes, and each process must have the same rank in both communicators.) This method must be called collectively over that communicator.

The Map that results from this operation does not preserve the original order of global indices in either of the two input Maps. Instead, it sorts global indices on each process so that owned indices occur first, in the same order as in the source Map, and so that remote indices are sorted in order of their sending process rank. This makes communication operations faster.

This primitive is useful for adding two sparse matrices (CrsMatrix), since its can skip over many of the steps of creating the result matrix's column Map from scratch.

We have to call this method "setUnion" rather than "union," because union is a reserved keyword in C++ (and C). It would also be reasonable to call this operator+, though it would be a bit confusing for operator+ to return a pointer but take a reference (or to take a pointer, but have the left-hand side of the + expression be a reference).

Definition at line 689 of file Tpetra_Import_def.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >
Teuchos::RCP< const Import< LocalOrdinal, GlobalOrdinal, Node > > Tpetra::Import< LocalOrdinal, GlobalOrdinal, Node >::setUnion ( ) const

Return the union of this Import this->getSourceMap()

This special case of setUnion creates a new Import object such that the targetMap of the new object contains all local unknowns in the sourceMap (plus whatever remotes were contained in this->getSourceMap()).

The Map that results from this operation does not preserve the input order of global indices. All local global indices are ordered in the order of the sourceMap, all remotes are ordered as implied by the Importer for *this.

This primitive is useful for adding or multipyling two sparse matrices (CrsMatrix), since its can skip over many of the steps of creating the result matrix's column Map from scratch.

Definition at line 1295 of file Tpetra_Import_def.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >
Teuchos::RCP< const Import< LocalOrdinal, GlobalOrdinal, Node > > Tpetra::Import< LocalOrdinal, GlobalOrdinal, Node >::createRemoteOnlyImport ( const Teuchos::RCP< const map_type > &  remoteTarget) const

Returns an importer that contains only the remote entries of this.

Returns an importer that contains only the remote entries of this importer. It is expected that remoteTarget represents such a map.

Definition at line 1365 of file Tpetra_Import_def.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >
void Tpetra::Import< LocalOrdinal, GlobalOrdinal, Node >::print ( std::ostream &  os) const [virtual]

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

This method assumes that the given output stream can be written on all process(es) in the Import'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 352 of file Tpetra_Import_def.hpp.


Friends And Related Function Documentation

template<class LocalOrdinal , class GlobalOrdinal , class Node >
Teuchos::RCP< const Import< LocalOrdinal, GlobalOrdinal, Node > > createImport ( const Teuchos::RCP< const Map< LocalOrdinal, GlobalOrdinal, Node > > &  src,
const Teuchos::RCP< const Map< LocalOrdinal, GlobalOrdinal, Node > > &  tgt 
) [related]

Nonmember constructor for Import.

Create a Import object from the given source and target Maps.

Precondition:
src != null
tgt != null
Returns:
The Import object. If src == tgt, returns null. (Debug mode: throws std::runtime_error if one of src or tgt is null.)

Definition at line 504 of file Tpetra_Import_decl.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >
Teuchos::RCP< const Import< LocalOrdinal, GlobalOrdinal, Node > > createImport ( const Teuchos::RCP< const Map< LocalOrdinal, GlobalOrdinal, Node > > &  src,
const Teuchos::RCP< const Map< LocalOrdinal, GlobalOrdinal, Node > > &  tgt,
const Teuchos::RCP< Teuchos::ParameterList > &  plist 
) [related]

Nonmember constructor for Import that takes a ParameterList.

Create a Import object from the given source and target Maps, using the given list of parameters.

Precondition:
src != null
tgt != null
Returns:
The Import object. If src == tgt, returns null. (Debug mode: throws std::runtime_error if one of src or tgt is null.)

Definition at line 534 of file Tpetra_Import_decl.hpp.


The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines