Epetra_Export: This class builds an export object for efficient exporting of off-processor elements. More...

#include <Epetra_Export.h>

Inheritance diagram for Epetra_Export:

Public Member Functions
	Epetra_Export (const Epetra_BlockMap &SourceMap, const Epetra_BlockMap &TargetMap)
	Constructs a Epetra_Export object from the source and target maps. More...

	Epetra_Export (const Epetra_Export &Exporter)
	Epetra_Export copy constructor. More...

	Epetra_Export (const Epetra_Import &Exporter)
	Epetra_Export pseudo-copy constructor. Creates an Epetra_Export in the reverse direction of the Epetra_Import argument. More...

virtual	~Epetra_Export (void)
	Epetra_Export destructor. More...

int	NumSameIDs () const
	Returns the number of elements that are identical between the source and target maps, up to the first different ID. More...

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

int *	PermuteFromLIDs () const
	List of elements in the source map that are permuted. More...

int *	PermuteToLIDs () const
	List of elements in the target map that are permuted. More...

int	NumRemoteIDs () const
	Returns the number of elements that are not on the calling processor. More...

int *	RemoteLIDs () const
	List of elements in the target map that are coming from other processors. More...

int	NumExportIDs () const
	Returns the number of elements that must be sent by the calling processor to other processors. More...

int *	ExportLIDs () const
	List of elements that will be sent to other processors. More...

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

int	NumSend () const
	Total number of elements to be sent. More...

int	NumRecv () const
	Total number of elements to be received. More...

const Epetra_BlockMap &	SourceMap () const
	Returns the SourceMap used to construct this exporter. More...

const Epetra_BlockMap &	TargetMap () const
	Returns the TargetMap used to construct this exporter. More...

Epetra_Distributor &	Distributor () const

const Epetra_Distributor *	DistributorPtr () const

Public Member Functions inherited from Epetra_Object
	Epetra_Object (int TracebackModeIn=-1, bool set_label=true)
	Epetra_Object Constructor. More...

	Epetra_Object (const char *const Label, int TracebackModeIn=-1)
	Epetra_Object Constructor. More...

	Epetra_Object (const Epetra_Object &Object)
	Epetra_Object Copy Constructor. More...

virtual	~Epetra_Object ()
	Epetra_Object Destructor. More...

virtual void	SetLabel (const char *const Label)
	Epetra_Object Label definition using char *. More...

virtual const char *	Label () const
	Epetra_Object Label access funtion. More...

virtual int	ReportError (const std::string Message, int ErrorCode) const
	Error reporting method. More...

Private Member Functions
Epetra_Export &	operator= (const Epetra_Export &src)

template<typename int_type >
void	Construct (const Epetra_BlockMap &SourceMap, const Epetra_BlockMap &TargetMap)

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_Distributor *	Distor_

Friends
class	Epetra_Import

class	Epetra_BlockMap

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

Additional Inherited Members
Static Public Member Functions inherited from Epetra_Object
static void	SetTracebackMode (int TracebackModeValue)
	Set the value of the Epetra_Object error traceback report mode. More...

static int	GetTracebackMode ()
	Get the value of the Epetra_Object error report mode. More...

static std::ostream &	GetTracebackStream ()
	Get the output stream for error reporting. More...

Static Public Attributes inherited from Epetra_Object
static int	TracebackMode

Protected Member Functions inherited from Epetra_Object
std::string	toString (const int &x) const

std::string	toString (const long long &x) const

std::string	toString (const double &x) const

Detailed Description

Epetra_Export: This class builds an export object for efficient exporting of off-processor elements.

Epetra_Export 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 send data to a target processor.

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

Definition at line 70 of file Epetra_Export.h.

Constructor & Destructor Documentation

Epetra_Export::Epetra_Export	(	const Epetra_BlockMap &	SourceMap,
		const Epetra_BlockMap &	TargetMap
	)

Constructs a Epetra_Export object from the source and target maps.

  This constructor builds an Epetra_Export object by comparing the GID lists of the source and
  target maps.
  \param SourceMap (In) Map containing the GIDs from which data should be exported from each processor to
         the target map whenever an export operation is performed using this exporter.
  \param  TargetMap (In) Map containing the GIDs that should be used for exporting data.

  \warning Note that the TargetMap \e must have GIDs uniquely owned, each GID of the target map can occur only once.

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

A Epetra_Export object categorizes the elements of the target map into three sets as follows:
<ol>
<li> 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(). 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(). 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_Export constructor builds a list of elements that must be communicated to other processors as a result of export 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 target map argument of the export object.

This could correspond to a 9-entry forcing vector with the first three entries on PE 0, and so on. Suppose that the entries of this forcing vector are computed by integrating over linear "hat" functions:

^  ^  ^  ^  ^  ^  ^  ^  ^
 \/ \/ \/ \/ \/ \/ \/ \/
 /\ /\ /\ /\ /\ /\ /\ /\
+--+--+--+--+--+--+--+--+
0  1  2  3  4  5  6  7  8

In this case, PE 0 will make contributions to entries 0 through 3, PE 1 will make contributions to entries 2 through 6 and PE 2 will make contributions to entries 5 through 8. A convenient way to compute these contributions is to create a forcing vector with replicated entries for the shared contributions. Specifically the following SourceMap works for this scenario:

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

A vector constructed using this SourceMap can be used to collect each processor's contributions to the forcing vector. 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_Export constructor, we get the following attribute definitions:

On PE 0:

NumSameIDs      = 3

NumPermuteIDs   = 0
PermuteToLIDs   = 0
PermuteFromLIDs = 0

NumRemoteIDs    = 1
RemoteLIDs      = [2]

NumExportIDs    = 1
ExportLIDs      = [3]
ExportPIDs      = [1]

NumSend         = 1
NumRecv         = 1

On PE 1:

NumSameIDs      = 0

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

NumRemoteIDs    = 2
RemoteLIDs      = [0, 2]

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

NumSend         = 2
NumRecv         = 2

On PE 2:

NumSameIDs      = 0

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

NumRemoteIDs    = 1
RemoteLIDs      = [0]

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

NumSend         = 1
NumRecv         = 1

Using Epetra_Export Objects

Once a Epetra_Export 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 Export 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.

In the above example, if x_integrate is constructed using the SourceMap and then filled with local contributions, and x_force is constructed using the target map, the following operation will fill x_force with the combined results of x_integrate:

x_force.Export(x_integrate, exporter, Add);

The third argument above tells the export operation to add results that come from multiple processors for the same GID.

Epetra_Export objects can also be used by Import operations to perform the reverse operation. For example, if x_force in the above example had boundary conditions that should be sent to processors that share a boundary element, the following operation would send replicated values to x_integrate:

x_integrate.Import(x_force, exporter, Insert);

At the end of this operation, x_integrate would have replicated values from x_force of entries 2 and 3 on PEs 0 and 1, and entries 5 and 6 on PEs 1 and 2.

Definition at line 230 of file Epetra_Export.cpp.

Epetra_Export::Epetra_Export ( const Epetra_Export & Exporter )

Epetra_Export copy constructor.

Definition at line 268 of file Epetra_Export.cpp.

Epetra_Export::Epetra_Export ( const Epetra_Import & Exporter )

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

Definition at line 330 of file Epetra_Export.cpp.

Epetra_Export::~Epetra_Export ( void )

virtual

Epetra_Export destructor.

Definition at line 316 of file Epetra_Export.cpp.

Member Function Documentation

int Epetra_Export::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 251 of file Epetra_Export.h.

int Epetra_Export::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 254 of file Epetra_Export.h.

int* Epetra_Export::PermuteFromLIDs ( ) const

inline

List of elements in the source map that are permuted.

Definition at line 257 of file Epetra_Export.h.

int* Epetra_Export::PermuteToLIDs ( ) const

inline

List of elements in the target map that are permuted.

Definition at line 259 of file Epetra_Export.h.

int Epetra_Export::NumRemoteIDs ( ) const

inline

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

Definition at line 262 of file Epetra_Export.h.

int* Epetra_Export::RemoteLIDs ( ) const

inline

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

Definition at line 265 of file Epetra_Export.h.

int Epetra_Export::NumExportIDs ( ) const

inline

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

Definition at line 268 of file Epetra_Export.h.

int* Epetra_Export::ExportLIDs ( ) const

inline

List of elements that will be sent to other processors.

Definition at line 271 of file Epetra_Export.h.

int* Epetra_Export::ExportPIDs ( ) const

inline

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

Definition at line 274 of file Epetra_Export.h.

int Epetra_Export::NumSend ( ) const

inline

Total number of elements to be sent.

Definition at line 277 of file Epetra_Export.h.

int Epetra_Export::NumRecv ( ) const

inline

Total number of elements to be received.

Definition at line 280 of file Epetra_Export.h.

const Epetra_BlockMap& Epetra_Export::SourceMap ( ) const

inline

Returns the SourceMap used to construct this exporter.

Definition at line 283 of file Epetra_Export.h.

const Epetra_BlockMap& Epetra_Export::TargetMap ( ) const

inline

Returns the TargetMap used to construct this exporter.

Definition at line 286 of file Epetra_Export.h.

Epetra_Distributor& Epetra_Export::Distributor ( ) const

inline

Definition at line 288 of file Epetra_Export.h.

const Epetra_Distributor* Epetra_Export::DistributorPtr ( ) const

inline

Definition at line 290 of file Epetra_Export.h.

void Epetra_Export::Print ( std::ostream & os ) const

virtual

Print object to an output stream Print method.

Reimplemented from Epetra_Object.

Definition at line 398 of file Epetra_Export.cpp.

Epetra_Export & Epetra_Export::operator= ( const Epetra_Export & src )

private

Definition at line 589 of file Epetra_Export.cpp.

template<typename int_type >

void Epetra_Export::Construct	(	const Epetra_BlockMap &	SourceMap,
		const Epetra_BlockMap &	TargetMap
	)

private

Definition at line 59 of file Epetra_Export.cpp.

Friends And Related Function Documentation

friend class Epetra_Import

friend

Definition at line 71 of file Epetra_Export.h.

friend class Epetra_BlockMap

friend

Definition at line 298 of file Epetra_Export.h.

Member Data Documentation

Epetra_BlockMap Epetra_Export::TargetMap_

private

Definition at line 303 of file Epetra_Export.h.

Epetra_BlockMap Epetra_Export::SourceMap_

private

Definition at line 304 of file Epetra_Export.h.

int Epetra_Export::NumSameIDs_

private

Definition at line 306 of file Epetra_Export.h.

int Epetra_Export::NumPermuteIDs_

private

Definition at line 307 of file Epetra_Export.h.

int* Epetra_Export::PermuteToLIDs_

private

Definition at line 308 of file Epetra_Export.h.

int* Epetra_Export::PermuteFromLIDs_

private

Definition at line 309 of file Epetra_Export.h.

int Epetra_Export::NumRemoteIDs_

private

Definition at line 310 of file Epetra_Export.h.

int* Epetra_Export::RemoteLIDs_

private

Definition at line 311 of file Epetra_Export.h.

int Epetra_Export::NumExportIDs_

private

Definition at line 313 of file Epetra_Export.h.

int* Epetra_Export::ExportLIDs_

private

Definition at line 314 of file Epetra_Export.h.

int* Epetra_Export::ExportPIDs_

private

Definition at line 315 of file Epetra_Export.h.

int Epetra_Export::NumSend_

private

Definition at line 317 of file Epetra_Export.h.

int Epetra_Export::NumRecv_

private

Definition at line 318 of file Epetra_Export.h.

Epetra_Distributor* Epetra_Export::Distor_

private

Definition at line 320 of file Epetra_Export.h.

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

Public Member Functions

Private Member Functions

Private Attributes

Friends

Print object to an output stream

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation