Epetra Package Browser (Single Doxygen Collection) Development
|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_Import &Importer)|
|Epetra_Import copy constructor. |
|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_BlockMap &||SourceMap () const|
|Returns the SourceMap used to construct this importer. |
|const Epetra_BlockMap &||TargetMap () const|
|Returns the TargetMap used to construct this importer. |
|Epetra_Distributor &||Distributor () const|
|Epetra_Import &||operator= (const Epetra_Import &src)|
|virtual void||Print (ostream &os) const|
|Print object to an output stream Print method. |
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.
|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.
|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.|
Builds an import object that will transfer objects built with SourceMap to objects built with TargetMap.
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 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.
|Epetra_Import::Epetra_Import||(||const Epetra_Import &||Importer||)|
|int Epetra_Import::NumSameIDs||(||)|| const
|int Epetra_Import::NumPermuteIDs||(||)|| const
|int* Epetra_Import::PermuteFromLIDs||(||)|| const
|int* Epetra_Import::PermuteToLIDs||(||)|| const
|int Epetra_Import::NumRemoteIDs||(||)|| const
|int* Epetra_Import::RemoteLIDs||(||)|| const
|int Epetra_Import::NumExportIDs||(||)|| const
|int* Epetra_Import::ExportLIDs||(||)|| const
|int* Epetra_Import::ExportPIDs||(||)|| const
|int Epetra_Import::NumSend||(||)|| const
|int Epetra_Import::NumRecv||(||)|| const
|const Epetra_BlockMap& Epetra_Import::SourceMap||(||)|| const
|const Epetra_BlockMap& Epetra_Import::TargetMap||(||)|| const
|Epetra_Distributor& Epetra_Import::Distributor||(||)|| const
|void Epetra_Import::Print||(||ostream &||os||)|| const