Epetra Package Browser (Single Doxygen Collection) Development
Public Member Functions | Private Member Functions | Private Attributes | Friends
Epetra_Import Class Reference

Epetra_Import: This class builds an import object for efficient importing of off-processor elements. More...

#include <Epetra_Import.h>

Inheritance diagram for Epetra_Import:
Inheritance graph
[legend]

List of all members.

Public Member Functions

 Epetra_Import (const Epetra_BlockMap &TargetMap, const Epetra_BlockMap &SourceMap)
 Constructs a Epetra_Import object from the source and target maps.
 Epetra_Import (const Epetra_BlockMap &TargetMap, const Epetra_BlockMap &SourceMap, int NumRemotePIDs, const int *RemotePIDs)
 Expert-only import constructor.
 Epetra_Import (const Epetra_BlockMap &TargetMap, const Epetra_BlockMap &SourceMap, int NumRemotePIDs, const int *RemotePIDs, const int &NumExportIDs, const int *ExportLIDs, const int *ExportPIDs)
 Expert-only import constructor.
 Epetra_Import (const Epetra_Import &Importer)
 Epetra_Import copy constructor.
 Epetra_Import (const Epetra_Export &Exporter)
 Epetra_Import pseudo-copy constructor. Creates an Epetra_Import in the reverse direction of the Epetra_Export argument.
virtual ~Epetra_Import (void)
 Epetra_Import destructor.
int NumSameIDs () const
 Returns the number of elements that are identical between the source and target maps, up to the first different ID.
int NumPermuteIDs () const
 Returns the number of elements that are local to the calling processor, but not part of the first NumSameIDs() elements.
int * PermuteFromLIDs () const
 List of elements in the source map that are permuted.
int * PermuteToLIDs () const
 List of elements in the target map that are permuted.
int NumRemoteIDs () const
 Returns the number of elements that are not on the calling processor.
int * RemoteLIDs () const
 List of elements in the target map that are coming from other processors.
int NumExportIDs () const
 Returns the number of elements that must be sent by the calling processor to other processors.
int * ExportLIDs () const
 List of elements that will be sent to other processors.
int * ExportPIDs () const
 List of processors to which elements will be sent, ExportLIDs() [i] will be sent to processor ExportPIDs() [i].
int NumSend () const
 Total number of elements to be sent.
int NumRecv () const
 Total number of elements to be received.
const Epetra_BlockMapSourceMap () const
 Returns the SourceMap used to construct this importer.
const Epetra_BlockMapTargetMap () const
 Returns the TargetMap used to construct this importer.
Epetra_DistributorDistributor () const

Private Member Functions

Epetra_Importoperator= (const Epetra_Import &src)
template<typename int_type >
void Construct (const Epetra_BlockMap &targetMap, const Epetra_BlockMap &sourceMap, int NumRemotePIDs=-1, const int *UserRemotePIDs=0)
template<typename int_type >
void Construct_Expert (const Epetra_BlockMap &TargetMap, const Epetra_BlockMap &SourceMap, int NumRemotePIDs, const int *RemotePIDs, const int &NumExportIDs, const int *ExportLIDs, const int *ExportPIDs)

Private Attributes

Epetra_BlockMap TargetMap_
Epetra_BlockMap SourceMap_
int NumSameIDs_
int NumPermuteIDs_
int * PermuteToLIDs_
int * PermuteFromLIDs_
int NumRemoteIDs_
int * RemoteLIDs_
int NumExportIDs_
int * ExportLIDs_
int * ExportPIDs_
int NumSend_
int NumRecv_
Epetra_DistributorDistor_

Friends

class Epetra_Export
class Epetra_BlockMap

Print object to an output stream

virtual void Print (std::ostream &os) const
 Print object to an output stream Print method.

Detailed Description

Epetra_Import: This class builds an import object for efficient importing of off-processor elements.

Epetra_Import is used to construct a communication plan that can be called repeatedly by computational classes such the Epetra matrix, vector and multivector classes to efficiently obtain off-processor elements.

This class currently has one constructor, taking two Epetra_Map or Epetra_BlockMap objects. The first map specifies the global IDs of elements that we want to import later. The second map specifies the global IDs that are owned by the calling processor.

Definition at line 63 of file Epetra_Import.h.


Constructor & Destructor Documentation

Epetra_Import::Epetra_Import ( const Epetra_BlockMap TargetMap,
const Epetra_BlockMap SourceMap 
)

Constructs a Epetra_Import object from the source and target maps.

This constructor builds an Epetra_Import object by comparing the GID lists of the source and target maps.

Parameters:
TargetMap(In) Map containing the GIDs from which data should be imported to each processor from the source map whenever an import operation is performed using this importer.
SourceMap(In) Map containing the GIDs that should be used for importing data.
Warning:
Note that the SourceMap must have GIDs uniquely owned, each GID of the source map can occur only once.

Builds an import object that will transfer objects built with SourceMap to objects built with TargetMap.

A Epetra_Import object categorizes the elements of the target map into three sets as follows:

  1. All elements in the target map that have the same GID as the corresponding element of the source map, starting with the first element in the target map, going up to the first element that is different from the source map. The number of these IDs is returned by NumSameIDs().
  2. All elements that are local to the processor, but are not part of the first set of elements. These elements have GIDs that are owned by the calling processor, but at least the first element of this list is permuted. Even if subsequent elements are not permuted, they are included in this list. The number of permuted elements is returned by NumPermutedIDs(). The list of elements (local IDs) in the source map that are permuted can be found in the list PermuteFromLIDs(). The list of elements (local IDs) in the target map that are the new locations of the source elements can be found in the list PermuteToLIDs().
  3. All remaining elements of the target map correspond to global IDs that are owned by remote processors. The number of these elements is returned by NumRemoteIDs() and the list of these is returned by RemoteLIDs().

Given the above information, the Epetra_Import constructor builds a list of elements that must be communicated to other processors as a result of import requests. The number of exported elements (where multiple sends of the same element to different processors is counted) is returned by NumExportIDs(). The local IDs to be sent are returned by the list ExportLIDs(). The processors to which each of the elements will be sent in returned in a list of the same length by ExportPIDs().

The total number of elements that will be sent by the calling processor is returned by NumSend(). The total number of elements that will be received is returned by NumRecv().

The following example illustrates the basic concepts.

Assume we have 3 processors and 9 global elements with each processor owning 3 elements as follows

 PE 0 Elements |  PE 1 Elements  |  PE 2 Elements
    0  1  2          3  4  5           6  7  8

The above layout essentially defines the source map argument of the import object.

This could correspond to a 9 by 9 matrix with the first three rows on PE 0, and so on. Suppose that this matrix is periodic tridiagonal having the following sparsity pattern:


PE 0 Rows:

  X  X  0  0  0  0  0  0  X
  X  X  X  0  0  0  0  0  0
  0  X  X  X  0  0  0  0  0

PE 1 Rows:

  0  0  X  X  X  0  0  0  0
  0  0  0  X  X  X  0  0  0
  0  0  0  0  X  X  X  0  0

PE 2 Rows:

  0  0  0  0  0  X  X  X  0
  0  0  0  0  0  0  X  X  X
  X  0  0  0  0  0  0  X  X

To perform a matrix vector multiplication operation y = A*x (assuming that x has the same distribution as the rows of the matrix A) each processor will need to import elements of x that are not local. To do this, we build a target map on each processor as follows:

    PE 0 Elements    |  PE 1 Elements    |  PE 2 Elements
    0  1  2  3  8       2  3  4  5  6       0  5  6  7  8

The above list is the elements that will be needed to perform the matrix vector multiplication locally on each processor. Note that the ordering of the elements on each processor is not unique, but has been chosen for illustration.

With these two maps passed into the Epetra_Import constructor, we get the following attribute definitions:

On PE 0:

NumSameIDs      = 3

NumPermuteIDs   = 0
PermuteToLIDs   = 0
PermuteFromLIDs = 0

NumRemoteIDs    = 2
RemoteLIDs      = [3, 4]

NumExportIDs    = 2
ExportLIDs      = [0, 2]
ExportPIDs      = [1, 2]

NumSend         = 2
NumRecv         = 2

On PE 1:

NumSameIDs      = 0

NumPermuteIDs   = 3
PermuteFromLIDs = [0, 1, 2]
PermuteToLIDs   = [1, 2, 3]

NumRemoteIDs    = 2
RemoteLIDs      = [0, 4]

NumExportIDs    = 2
ExportLIDs      = [0, 2]
ExportPIDs      = [0, 2]

NumSend         = 2
NumRecv         = 2

On PE 2:

NumSameIDs      = 0

NumPermuteIDs   = 3
PermuteFromLIDs = [0, 1, 2]
PermuteToLIDs   = [2, 3, 4]

NumRemoteIDs    = 2
RemoteLIDs      = [0, 1]

NumExportIDs    = 2
ExportLIDs      = [0, 2]
ExportPIDs      = [0, 1]

NumSend         = 2
NumRecv         = 2

Using Epetra_Import Objects

Once a Epetra_Import object has been constructed, it can be used by any of the Epetra classes that support distributed global objects, namely Epetra_Vector, Epetra_MultiVector, Epetra_CrsGraph, Epetra_CrsMatrix and Epetra_VbrMatrix. All of these classes have Import and Export methods that will fill new objects whose distribution is described by the target map, taking elements from the source object whose distribution is described by the source map. Details of usage for each class is given in the appropriate class documentation.

Note that the reverse operation, an export, using this importer is also possible and appropriate in some instances. For example, if we compute y = A^Tx, the transpose matrix-multiplication operation, then we can use the importer we constructed in the above example to do an export operation to y, adding the contributions that come from multiple processors.

Definition at line 572 of file Epetra_Import.cpp.

Epetra_Import::Epetra_Import ( const Epetra_BlockMap TargetMap,
const Epetra_BlockMap SourceMap,
int  NumRemotePIDs,
const int *  RemotePIDs 
)

Expert-only import constructor.

The additional RemotePIDs argument should be filled with the owning PIDs (from the SourceMap) of the remote GIDs in the TargetMap. The normal Import constructor computes this for you with a call to RemoteIDList. However in some cases (MakeImportExport) we already have this information.

WARNING: THIS METHOD IS FOR INTERNAL USE ONLY. USERS SHOULD NOT CALL THIS CONSTRUCTOR

Definition at line 494 of file Epetra_Import.cpp.

Epetra_Import::Epetra_Import ( const Epetra_BlockMap TargetMap,
const Epetra_BlockMap SourceMap,
int  NumRemotePIDs,
const int *  RemotePIDs,
const int &  NumExportIDs,
const int *  ExportLIDs,
const int *  ExportPIDs 
)

Expert-only import constructor.

The RemotePIDs argument should be filled with the owning PIDs (from the SourceMap) of the remote GIDs in the TargetMap. The normal Import constructor computes this for you with a call to RemoteIDList. However in some cases (MakeImportExport) we already have this information. We also require information on the Export PIDs/GIDs so we can use the Distributor's CreateFromSendsAndReceives method. WARNING: THIS METHOD IS FOR INTERNAL USE ONLY. USERS SHOULD NOT CALL THIS CONSTRUCTOR

Definition at line 533 of file Epetra_Import.cpp.

Epetra_Import::Epetra_Import ( const Epetra_Import Importer)

Epetra_Import copy constructor.

Definition at line 610 of file Epetra_Import.cpp.

Epetra_Import::Epetra_Import ( const Epetra_Export Exporter)

Epetra_Import pseudo-copy constructor. Creates an Epetra_Import in the reverse direction of the Epetra_Export argument.

Definition at line 670 of file Epetra_Import.cpp.

Epetra_Import::~Epetra_Import ( void  ) [virtual]

Epetra_Import destructor.

Definition at line 657 of file Epetra_Import.cpp.


Member Function Documentation

int Epetra_Import::NumSameIDs ( ) const [inline]

Returns the number of elements that are identical between the source and target maps, up to the first different ID.

Definition at line 262 of file Epetra_Import.h.

int Epetra_Import::NumPermuteIDs ( ) const [inline]

Returns the number of elements that are local to the calling processor, but not part of the first NumSameIDs() elements.

Definition at line 265 of file Epetra_Import.h.

int* Epetra_Import::PermuteFromLIDs ( ) const [inline]

List of elements in the source map that are permuted.

Definition at line 268 of file Epetra_Import.h.

int* Epetra_Import::PermuteToLIDs ( ) const [inline]

List of elements in the target map that are permuted.

Definition at line 270 of file Epetra_Import.h.

int Epetra_Import::NumRemoteIDs ( ) const [inline]

Returns the number of elements that are not on the calling processor.

Definition at line 273 of file Epetra_Import.h.

int* Epetra_Import::RemoteLIDs ( ) const [inline]

List of elements in the target map that are coming from other processors.

Definition at line 276 of file Epetra_Import.h.

int Epetra_Import::NumExportIDs ( ) const [inline]

Returns the number of elements that must be sent by the calling processor to other processors.

Definition at line 279 of file Epetra_Import.h.

int* Epetra_Import::ExportLIDs ( ) const [inline]

List of elements that will be sent to other processors.

Definition at line 282 of file Epetra_Import.h.

int* Epetra_Import::ExportPIDs ( ) const [inline]

List of processors to which elements will be sent, ExportLIDs() [i] will be sent to processor ExportPIDs() [i].

Definition at line 285 of file Epetra_Import.h.

int Epetra_Import::NumSend ( ) const [inline]

Total number of elements to be sent.

Definition at line 288 of file Epetra_Import.h.

int Epetra_Import::NumRecv ( ) const [inline]

Total number of elements to be received.

Definition at line 291 of file Epetra_Import.h.

const Epetra_BlockMap& Epetra_Import::SourceMap ( ) const [inline]

Returns the SourceMap used to construct this importer.

Definition at line 294 of file Epetra_Import.h.

const Epetra_BlockMap& Epetra_Import::TargetMap ( ) const [inline]

Returns the TargetMap used to construct this importer.

Definition at line 297 of file Epetra_Import.h.

Epetra_Distributor& Epetra_Import::Distributor ( ) const [inline]

Definition at line 299 of file Epetra_Import.h.

void Epetra_Import::Print ( std::ostream &  os) const [virtual]

Print object to an output stream Print method.

Reimplemented from Epetra_Object.

Definition at line 739 of file Epetra_Import.cpp.

Epetra_Import& Epetra_Import::operator= ( const Epetra_Import src) [inline, private]

Definition at line 310 of file Epetra_Import.h.

template<typename int_type >
void Epetra_Import::Construct ( const Epetra_BlockMap targetMap,
const Epetra_BlockMap sourceMap,
int  NumRemotePIDs = -1,
const int *  UserRemotePIDs = 0 
) [private]

Definition at line 288 of file Epetra_Import.cpp.

template<typename int_type >
void Epetra_Import::Construct_Expert ( const Epetra_BlockMap TargetMap,
const Epetra_BlockMap SourceMap,
int  NumRemotePIDs,
const int *  RemotePIDs,
const int &  NumExportIDs,
const int *  ExportLIDs,
const int *  ExportPIDs 
) [private]

Definition at line 67 of file Epetra_Import.cpp.


Friends And Related Function Documentation

friend class Epetra_Export [friend]

Definition at line 64 of file Epetra_Import.h.

friend class Epetra_BlockMap [friend]

Definition at line 307 of file Epetra_Import.h.


Member Data Documentation

Definition at line 321 of file Epetra_Import.h.

Definition at line 322 of file Epetra_Import.h.

Definition at line 324 of file Epetra_Import.h.

Definition at line 325 of file Epetra_Import.h.

Definition at line 326 of file Epetra_Import.h.

Definition at line 327 of file Epetra_Import.h.

Definition at line 328 of file Epetra_Import.h.

Definition at line 329 of file Epetra_Import.h.

Definition at line 331 of file Epetra_Import.h.

Definition at line 332 of file Epetra_Import.h.

Definition at line 333 of file Epetra_Import.h.

int Epetra_Import::NumSend_ [private]

Definition at line 335 of file Epetra_Import.h.

int Epetra_Import::NumRecv_ [private]

Definition at line 336 of file Epetra_Import.h.

Definition at line 338 of file Epetra_Import.h.


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