Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members | Examples | Search for 

Epetra_MultiVector Class Reference

Epetra_MultiVector: A class for constructing and using dense multi-vectors, vectors and matrices in parallel. More...

#include <Epetra_MultiVector.h>

Inheritance diagram for Epetra_MultiVector:

[legend]
List of all members.

Constructors/destructors

 Epetra_MultiVector (const Epetra_BlockMap &Map, int NumVectors, bool zeroOut=true)
 Basic Epetra_MultiVector constuctor.
 Epetra_MultiVector (const Epetra_MultiVector &Source)
 Epetra_MultiVector copy constructor.
 Epetra_MultiVector (Epetra_DataAccess CV, const Epetra_BlockMap &Map, double *A, int MyLDA, int NumVectors)
 Set multi-vector values from two-dimensional array.
 Epetra_MultiVector (Epetra_DataAccess CV, const Epetra_BlockMap &Map, double **ArrayOfPointers, int NumVectors)
 Set multi-vector values from array of pointers.
 Epetra_MultiVector (Epetra_DataAccess CV, const Epetra_MultiVector &Source, int *Indices, int NumVectors)
 Set multi-vector values from list of vectors in an existing Epetra_MultiVector.
 Epetra_MultiVector (Epetra_DataAccess CV, const Epetra_MultiVector &Source, int StartIndex, int NumVectors)
 Set multi-vector values from range of vectors in an existing Epetra_MultiVector.
virtual ~Epetra_MultiVector ()
 Epetra_MultiVector destructor.

Post-construction modification routines

int ReplaceGlobalValue (int GlobalRow, int VectorIndex, double ScalarValue)
 Replace current value at the specified (GlobalRow, VectorIndex) location with ScalarValue.
int ReplaceGlobalValue (int GlobalBlockRow, int BlockRowOffset, int VectorIndex, double ScalarValue)
 Replace current value at the specified (GlobalBlockRow, BlockRowOffset, VectorIndex) location with ScalarValue.
int SumIntoGlobalValue (int GlobalRow, int VectorIndex, double ScalarValue)
 Adds ScalarValue to existing value at the specified (GlobalRow, VectorIndex) location.
int SumIntoGlobalValue (int GlobalBlockRow, int BlockRowOffset, int VectorIndex, double ScalarValue)
 Adds ScalarValue to existing value at the specified (GlobalBlockRow, BlockRowOffset, VectorIndex) location.
int ReplaceMyValue (int MyRow, int VectorIndex, double ScalarValue)
 Replace current value at the specified (MyRow, VectorIndex) location with ScalarValue.
int ReplaceMyValue (int MyBlockRow, int BlockRowOffset, int VectorIndex, double ScalarValue)
 Replace current value at the specified (MyBlockRow, BlockRowOffset, VectorIndex) location with ScalarValue.
int SumIntoMyValue (int MyRow, int VectorIndex, double ScalarValue)
 Adds ScalarValue to existing value at the specified (MyRow, VectorIndex) location.
int SumIntoMyValue (int MyBlockRow, int BlockRowOffset, int VectorIndex, double ScalarValue)
 Adds ScalarValue to existing value at the specified (MyBlockRow, BlockRowOffset, VectorIndex) location.
int PutScalar (double ScalarConstant)
 Initialize all values in a multi-vector with constant value.
int Random ()
 Set multi-vector values to random numbers.

Extraction methods

int ExtractCopy (double *A, int MyLDA) const
 Put multi-vector values into user-provided two-dimensional array.
int ExtractCopy (double **ArrayOfPointers) const
 Put multi-vector values into user-provided array of pointers.
int ExtractView (double **A, int *MyLDA) const
 Set user-provided addresses of A and MyLDA.
int ExtractView (double ***ArrayOfPointers) const
 Set user-provided addresses of ArrayOfPointers.

Mathematical methods

int Dot (const Epetra_MultiVector &A, double *Result) const
 Computes dot product of each corresponding pair of vectors.
int Abs (const Epetra_MultiVector &A)
 Puts element-wise absolute values of input Multi-vector in target.
int Reciprocal (const Epetra_MultiVector &A)
 Puts element-wise reciprocal values of input Multi-vector in target.
int Scale (double ScalarValue)
 Scale the current values of a multi-vector, this = ScalarValue*this.
int Scale (double ScalarA, const Epetra_MultiVector &A)
 Replace multi-vector values with scaled values of A, this = ScalarA*A.
int Update (double ScalarA, const Epetra_MultiVector &A, double ScalarThis)
 Update multi-vector values with scaled values of A, this = ScalarThis*this + ScalarA*A.
int Update (double ScalarA, const Epetra_MultiVector &A, double ScalarB, const Epetra_MultiVector &B, double ScalarThis)
 Update multi-vector with scaled values of A and B, this = ScalarThis*this + ScalarA*A + ScalarB*B.
int Norm1 (double *Result) const
 Compute 1-norm of each vector in multi-vector.
int Norm2 (double *Result) const
 Compute 2-norm of each vector in multi-vector.
int NormInf (double *Result) const
 Compute Inf-norm of each vector in multi-vector.
int NormWeighted (const Epetra_MultiVector &Weights, double *Result) const
 Compute Weighted 2-norm (RMS Norm) of each vector in multi-vector.
int MinValue (double *Result) const
 Compute minimum value of each vector in multi-vector.
int MaxValue (double *Result) const
 Compute maximum value of each vector in multi-vector.
int MeanValue (double *Result) const
 Compute mean (average) value of each vector in multi-vector.
int Multiply (char TransA, char TransB, double ScalarAB, const Epetra_MultiVector &A, const Epetra_MultiVector &B, double ScalarThis)
 Matrix-Matrix multiplication, this = ScalarThis*this + ScalarAB*A*B.
int Multiply (double ScalarAB, const Epetra_MultiVector &A, const Epetra_MultiVector &B, double ScalarThis)
 Multiply a Epetra_MultiVector with another, element-by-element.
int ReciprocalMultiply (double ScalarAB, const Epetra_MultiVector &A, const Epetra_MultiVector &B, double ScalarThis)
 Multiply a Epetra_MultiVector by the reciprocal of another, element-by-element.

Random number utilities

int SetSeed (unsigned int Seed)
 Set seed for Random function.
unsigned int Seed ()
 Get seed from Random function.

Overloaded operators

Epetra_MultiVector & operator= (const Epetra_MultiVector &Source)
 = Operator.
double *& operator[] (int i)
 Vector access function.
double *const & operator[] (int i) const
 Vector access function.
Epetra_Vector *& operator() (int i)
 Vector access function.
const Epetra_Vector *& operator() (int i) const
 Vector access function.

Attribute access functions

int NumVectors () const
 Returns the number of vectors in the multi-vector.
int MyLength () const
 Returns the local vector length on the calling processor of vectors in the multi-vector.
int GlobalLength () const
 Returns the global vector length of vectors in the multi-vector.
int Stride () const
 Returns the stride between vectors in the multi-vector (only meaningful if ConstantStride() is true).
bool ConstantStride () const
 Returns true if this multi-vector has constant stride between vectors.

I/O methods

virtual void Print (ostream &os) const
 Print method.

Expert-only unsupported methods

int ResetView (double **ArrayOfPointers)
 Reset the view of an existing multivector to point to new user data.
double * Values () const
 Get pointer to MultiVector values.
double ** Pointers () const
 Get pointer to individual vector pointers.

Public Member Functions

int ReplaceMap (const Epetra_BlockMap &map)
 Replace map, only if new map has same point-structure as current map.
int Reduce ()

Protected Member Functions

void Assign (const Epetra_MultiVector &rhs)
int CheckInput ()

Protected Attributes

double * Values_

Private Member Functions

int AllocateForCopy (void)
int DoCopy (void)
void UpdateDoubleTemp () const
void UpdateVectors () const
int AllocateForView (void)
int DoView (void)
int ChangeGlobalValue (int GlobalBlockRow, int BlockRowOffset, int VectorIndex, double ScalarValue, bool SumInto)
int ChangeMyValue (int MyBlockRow, int BlockRowOffset, int VectorIndex, double ScalarValue, bool SumInto)
int CheckSizes (const Epetra_SrcDistObject &A)
 Allows the source and target (this) objects to be compared for compatibility, return nonzero if not.
int CopyAndPermute (const Epetra_SrcDistObject &Source, int NumSameIDs, int NumPermuteIDs, int *PermuteToLIDs, int *PermuteFromLIDs, const Epetra_OffsetIndex *Indexor)
 Perform ID copies and permutations that are on processor.
int PackAndPrepare (const Epetra_SrcDistObject &Source, int NumExportIDs, int *ExportLIDs, int &LenExports, char *&Exports, int &SizeOfPacket, int *Sizes, bool &VarSizes, Epetra_Distributor &Distor)
 Perform any packing or preparation required for call to DoTransfer().
int UnpackAndCombine (const Epetra_SrcDistObject &Source, int NumImportIDs, int *ImportLIDs, int LenImports, char *Imports, int &SizeOfPacket, Epetra_Distributor &Distor, Epetra_CombineMode CombineMode, const Epetra_OffsetIndex *Indexor)
 Perform any unpacking and combining after call to DoTransfer().

Private Attributes

double ** Pointers_
int MyLength_
int GlobalLength_
int NumVectors_
bool UserAllocated_
bool ConstantStride_
int Stride_
bool Allocated_
double * DoubleTemp_
Epetra_Vector ** Vectors_
Epetra_Util Util_

Detailed Description

Epetra_MultiVector: A class for constructing and using dense multi-vectors, vectors and matrices in parallel.

The Epetra_MultiVector class enables the construction and use of real-valued, double-precision dense vectors, multi-vectors, and matrices in a distributed memory environment. The dimensions and distribution of the dense multi-vectors is determined in part by a Epetra_Comm object, a Epetra_Map (or Epetra_LocalMap or Epetra_BlockMap) and the number of vectors passed to the constructors described below.

There are several concepts that important for understanding the Epetra_MultiVector class:

Constructing Epetra_MultiVectors

Except for the basic constructor and copy constructor, Epetra_MultiVector constructors have two data access modes:

  1. Copy mode - Allocates memory and makes a copy of the user-provided data. In this case, the user data is not needed after construction.
  2. View mode - Creates a "view" of the user data. In this case, the user data is required to remain intact for the life of the multi-vector.

Warning:
View mode is extremely dangerous from a data hiding perspective. Therefore, we strongly encourage users to develop code using Copy mode first and only use the View mode in a secondary optimization phase.
All Epetra_MultiVector constructors require a map argument that describes the layout of elements on the parallel machine. Specifically, map is a Epetra_Map, Epetra_LocalMap or Epetra_BlockMap object describing the desired memory layout for the multi-vector.

There are six different Epetra_MultiVector constructors:

Extracting Data from Epetra_MultiVectors

Once a Epetra_MultiVector is constructed, it is possible to extract a copy of the values or create a view of them.

Warning:
ExtractView functions are extremely dangerous from a data hiding perspective. For both ExtractView fuctions, there is a corresponding ExtractCopy function. We strongly encourage users to develop code using ExtractCopy functions first and only use the ExtractView functions in a secondary optimization phase.
There are four Extract functions:

Vector, Matrix and Utility Functions

Once a Epetra_MultiVector is constructed, a variety of mathematical functions can be applied to the individual vectors. Specifically:

In addition, a matrix-matrix multiply function supports a variety of operations on any viable combination of global distributed and local replicated multi-vectors using calls to DGEMM, a high performance kernel for matrix operations. In the near future we will add support for calls to other selected BLAS and LAPACK functions.

Counting Floating Point Operations

Each Epetra_MultiVector object keep track of the number of serial floating point operations performed using the specified object as the this argument to the function. The Flops() function returns this number as a double precision number. Using this information, in conjunction with the Epetra_Time class, one can get accurate parallel performance numbers. The ResetFlops() function resets the floating point counter.

Warning:
A Epetra_Map, Epetra_LocalMap or Epetra_BlockMap object is required for all Epetra_MultiVector constructors.

Definition at line 171 of file Epetra_MultiVector.h.

Constructor & Destructor Documentation

Epetra_MultiVector::Epetra_MultiVector (  const Epetra_BlockMap &  Map,
int  NumVectors,
bool  zeroOut = true
) 
 

Basic Epetra_MultiVector constuctor.

Creates a Epetra_MultiVector object and, by default, fills with zero values.

Parameters:
In Map - A Epetra_LocalMap, Epetra_Map or Epetra_BlockMap.
Warning:
Note that, because Epetra_LocalMap derives from Epetra_Map and Epetra_Map derives from Epetra_BlockMap, this constructor works for all three types of Epetra map classes.
Parameters:
In NumVectors - Number of vectors in multi-vector.
In zeroOut - If true then the allocated memory will be zeroed out initialy. If false then this memory will not be touched which can be significantly faster.
Returns:
Pointer to a Epetra_MultiVector.

Definition at line 46 of file Epetra_MultiVector.cpp.

Epetra_MultiVector::Epetra_MultiVector (  const Epetra_MultiVector &  Source  ) 
 

Epetra_MultiVector copy constructor.

Definition at line 71 of file Epetra_MultiVector.cpp.

Epetra_MultiVector::Epetra_MultiVector (  Epetra_DataAccess  CV,
const Epetra_BlockMap &  Map,
double *  A,
int  MyLDA,
int  NumVectors
) 
 

Set multi-vector values from two-dimensional array.

Parameters:
In Epetra_DataAccess - Enumerated type set to Copy or View.
In Map - A Epetra_LocalMap, Epetra_Map or Epetra_BlockMap.
In A - Pointer to an array of double precision numbers. The first vector starts at A. The second vector starts at A+MyLDA, the third at A+2*MyLDA, and so on.
In MyLDA - The "Leading Dimension", or stride between vectors in memory.
Warning:
This value refers to the stride on the calling processor. Thus it is a local quantity, not a global quantity.
Parameters:
In NumVectors - Number of vectors in multi-vector.
Returns:
Integer error code, set to 0 if successful.
See Detailed Description section for further discussion.

Definition at line 97 of file Epetra_MultiVector.cpp.

Epetra_MultiVector::Epetra_MultiVector (  Epetra_DataAccess  CV,
const Epetra_BlockMap &  Map,
double **  ArrayOfPointers,
int  NumVectors
) 
 

Set multi-vector values from array of pointers.

Parameters:
In Epetra_DataAccess - Enumerated type set to Copy or View.
In Map - A Epetra_LocalMap, Epetra_Map or Epetra_BlockMap.
In ArrayOfPointers - An array of pointers such that ArrayOfPointers[i] points to the memory location containing ith vector to be copied.
In NumVectors - Number of vectors in multi-vector.
Returns:
Integer error code, set to 0 if successful.
See Detailed Description section for further discussion.

Definition at line 127 of file Epetra_MultiVector.cpp.

Epetra_MultiVector::Epetra_MultiVector (  Epetra_DataAccess  CV,
const Epetra_MultiVector &  Source,
int *  Indices,
int  NumVectors
) 
 

Set multi-vector values from list of vectors in an existing Epetra_MultiVector.

Parameters:
In Epetra_DataAccess - Enumerated type set to Copy or View.
In Source - An existing fully constructed Epetra_MultiVector.
In Indices - Integer list of the vectors to copy.
In NumVectors - Number of vectors in multi-vector.
Returns:
Integer error code, set to 0 if successful.
See Detailed Description section for further discussion.

Definition at line 158 of file Epetra_MultiVector.cpp.

Epetra_MultiVector::Epetra_MultiVector (  Epetra_DataAccess  CV,
const Epetra_MultiVector &  Source,
int  StartIndex,
int  NumVectors
) 
 

Set multi-vector values from range of vectors in an existing Epetra_MultiVector.

Parameters:
In Epetra_DataAccess - Enumerated type set to Copy or View.
In Source - An existing fully constructed Epetra_MultiVector.
In StartIndex - First of the vectors to copy.
In NumVectors - Number of vectors in multi-vector.
Returns:
Integer error code, set to 0 if successful.
See Detailed Description section for further discussion.

Definition at line 189 of file Epetra_MultiVector.cpp.

Epetra_MultiVector::~Epetra_MultiVector (   )  [virtual]
 

Epetra_MultiVector destructor.

Definition at line 216 of file Epetra_MultiVector.cpp.

Member Function Documentation

int Epetra_MultiVector::ReplaceGlobalValue (  int  GlobalRow,
int  VectorIndex,
double  ScalarValue
) 
 

Replace current value at the specified (GlobalRow, VectorIndex) location with ScalarValue.

Replaces the existing value for a single entry in the multivector. The specified global row must correspond to a GID owned by the map of the multivector on the calling processor. In other words, this method does not perform cross-processor communication.

If the map associated with this multivector is an Epetra_BlockMap, only the first point entry associated with the global row will be modified. To modify a different point entry, use the other version of this method

Parameters:
In GlobalRow - Row of Multivector to modify in global index space.
In VectorIndex - Vector within MultiVector that should to modify.
In ScalarValue - Value to add to existing value.
Returns:
Integer error code, set to 0 if successful, set to 1 if GlobalRow not associated with calling processor set to -1 if VectorIndex >= NumVectors().

Definition at line 342 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::ReplaceGlobalValue (  int  GlobalBlockRow,
int  BlockRowOffset,
int  VectorIndex,
double  ScalarValue
) 
 

Replace current value at the specified (GlobalBlockRow, BlockRowOffset, VectorIndex) location with ScalarValue.

Replaces the existing value for a single entry in the multivector. The specified global block row and block row offset must correspond to a GID owned by the map of the multivector on the calling processor. In other words, this method does not perform cross-processor communication.

Parameters:
In GlobalBlockRow - BlockRow of Multivector to modify in global index space.
In BlockRowOffset - Offset into BlockRow of Multivector to modify in global index space.
In VectorIndex - Vector within MultiVector that should to modify.
In ScalarValue - Value to add to existing value.
Returns:
Integer error code, set to 0 if successful, set to 1 if GlobalRow not associated with calling processor set to -1 if VectorIndex >= NumVectors(), set to -2 if BlockRowOffset is out-of-range.

Definition at line 349 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::SumIntoGlobalValue (  int  GlobalRow,
int  VectorIndex,
double  ScalarValue
) 
 

Adds ScalarValue to existing value at the specified (GlobalRow, VectorIndex) location.

Sums the given value into the existing value for a single entry in the multivector. The specified global row must correspond to a GID owned by the map of the multivector on the calling processor. In other words, this method does not perform cross-processor communication.

If the map associated with this multivector is an Epetra_BlockMap, only the first point entry associated with the global row will be modified. To modify a different point entry, use the other version of this method

Parameters:
In GlobalRow - Row of Multivector to modify in global index space.
In VectorIndex - Vector within MultiVector that should to modify.
In ScalarValue - Value to add to existing value.
Returns:
Integer error code, set to 0 if successful, set to 1 if GlobalRow not associated with calling processor set to -1 if VectorIndex >= NumVectors().

Definition at line 356 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::SumIntoGlobalValue (  int  GlobalBlockRow,
int  BlockRowOffset,
int  VectorIndex,
double  ScalarValue
) 
 

Adds ScalarValue to existing value at the specified (GlobalBlockRow, BlockRowOffset, VectorIndex) location.

Sums the given value into the existing value for a single entry in the multivector. The specified global block row and block row offset must correspond to a GID owned by the map of the multivector on the calling processor. In other words, this method does not perform cross-processor communication.

Parameters:
In GlobalBlockRow - BlockRow of Multivector to modify in global index space.
In BlockRowOffset - Offset into BlockRow of Multivector to modify in global index space.
In VectorIndex - Vector within MultiVector that should to modify.
In ScalarValue - Value to add to existing value.
Returns:
Integer error code, set to 0 if successful, set to 1 if GlobalRow not associated with calling processor set to -1 if VectorIndex >= NumVectors(), set to -2 if BlockRowOffset is out-of-range.

Definition at line 363 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::ReplaceMyValue (  int  MyRow,
int  VectorIndex,
double  ScalarValue
) 
 

Replace current value at the specified (MyRow, VectorIndex) location with ScalarValue.

Replaces the existing value for a single entry in the multivector. The specified local row must correspond to a GID owned by the map of the multivector on the calling processor. In other words, this method does not perform cross-processor communication.

This method is intended for use with vectors based on an Epetra_Map. If used on a vector based on a non-trivial Epetra_BlockMap, this will update only block row 0, i.e.

Epetra_MultiVector::ReplaceMyValue ( MyRow, VectorIndex, ScalarValue ) is equivalent to: Epetra_MultiVector::ReplaceMyValue ( 0, MyRow, VectorIndex, ScalarValue )

Parameters:
In MyRow - Row of Multivector to modify in local index space.
In VectorIndex - Vector within MultiVector that should to modify.
In ScalarValue - Value to add to existing value.
Returns:
Integer error code, set to 0 if successful, set to 1 if MyRow not associated with calling processor set to -1 if VectorIndex >= NumVectors().

Definition at line 370 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::ReplaceMyValue (  int  MyBlockRow,
int  BlockRowOffset,
int  VectorIndex,
double  ScalarValue
) 
 

Replace current value at the specified (MyBlockRow, BlockRowOffset, VectorIndex) location with ScalarValue.

Replaces the existing value for a single entry in the multivector. The specified local block row and block row offset must correspond to a GID owned by the map of the multivector on the calling processor. In other words, this method does not perform cross-processor communication.

Parameters:
In MyBlockRow - BlockRow of Multivector to modify in local index space.
In BlockRowOffset - Offset into BlockRow of Multivector to modify in local index space.
In VectorIndex - Vector within MultiVector that should to modify.
In ScalarValue - Value to add to existing value.
Returns:
Integer error code, set to 0 if successful, set to 1 if MyRow not associated with calling processor set to -1 if VectorIndex >= NumVectors(), set to -2 if BlockRowOffset is out-of-range.

Definition at line 377 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::SumIntoMyValue (  int  MyRow,
int  VectorIndex,
double  ScalarValue
) 
 

Adds ScalarValue to existing value at the specified (MyRow, VectorIndex) location.

Sums the given value into the existing value for a single entry in the multivector. The specified local row must correspond to a GID owned by the map of the multivector on the calling processor. In other words, this method does not perform cross-processor communication.

If the map associated with this multivector is an Epetra_BlockMap, only the first point entry associated with the local row will be modified. To modify a different point entry, use the other version of this method

Parameters:
In MyRow - Row of Multivector to modify in local index space.
In VectorIndex - Vector within MultiVector that should to modify.
In ScalarValue - Value to add to existing value.
Returns:
Integer error code, set to 0 if successful, set to 1 if MyRow not associated with calling processor set to -1 if VectorIndex >= NumVectors().

Definition at line 384 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::SumIntoMyValue (  int  MyBlockRow,
int  BlockRowOffset,
int  VectorIndex,
double  ScalarValue
) 
 

Adds ScalarValue to existing value at the specified (MyBlockRow, BlockRowOffset, VectorIndex) location.

Sums the given value into the existing value for a single entry in the multivector. The specified local block row and block row offset must correspond to a GID owned by the map of the multivector on the calling processor. In other words, this method does not perform cross-processor communication.

Parameters:
In MyBlockRow - BlockRow of Multivector to modify in local index space.
In BlockRowOffset - Offset into BlockRow of Multivector to modify in local index space.
In VectorIndex - Vector within MultiVector that should to modify.
In ScalarValue - Value to add to existing value.
Returns:
Integer error code, set to 0 if successful, set to 1 if MyRow not associated with calling processor set to -1 if VectorIndex >= NumVectors(), set to -2 if BlockRowOffset is out-of-range.

Definition at line 390 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::PutScalar (  double  ScalarConstant  ) 
 

Initialize all values in a multi-vector with constant value.

Parameters:
In ScalarConstant - Value to use.
Returns:
Integer error code, set to 0 if successful.

Definition at line 514 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::Random (   ) 
 

Set multi-vector values to random numbers.

MultiVector uses the random number generator provided by Epetra_Util. The multi-vector values will be set to random values on the interval (-1.0, 1.0).

Returns:
Integer error code, set to 0 if successful.

Definition at line 422 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::ExtractCopy (  double *  A,
int  MyLDA
)  const
 

Put multi-vector values into user-provided two-dimensional array.

Parameters:
Out A - Pointer to memory space that will contain the multi-vector values. The first vector will be copied to the memory pointed to by A. The second vector starts at A+MyLDA, the third at A+2*MyLDA, and so on.
In MyLDA - The "Leading Dimension", or stride between vectors in memory.
Warning:
This value refers to the stride on the calling processor. Thus it is a local quantity, not a global quantity.
Returns:
Integer error code, set to 0 if successful.
See Detailed Description section for further discussion.

Definition at line 448 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::ExtractCopy (  double **  ArrayOfPointers  )  const
 

Put multi-vector values into user-provided array of pointers.

Parameters:
Out ArrayOfPointers - An array of pointers to memory space that will contain the multi-vector values, such that ArrayOfPointers[i] points to the memory location where the ith vector to be copied.
Returns:
Integer error code, set to 0 if successful.
See Detailed Description section for further discussion.

Definition at line 476 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::ExtractView (  double **  A,
int *  MyLDA
)  const
 

Set user-provided addresses of A and MyLDA.

Parameters:
A (Out) - Address of a pointer to that will be set to point to the values of the multi-vector. The first vector will be at the memory pointed to by A. The second vector starts at A+MyLDA, the third at A+2*MyLDA, and so on.
MyLDA (Out) - Address of the "Leading Dimension", or stride between vectors in memory.
Warning:
This value refers to the stride on the calling processor. Thus it is a local quantity, not a global quantity.
Returns:
Integer error code, set to 0 if successful.
See Detailed Description section for further discussion.

Definition at line 493 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::ExtractView (  double ***  ArrayOfPointers  )  const
 

Set user-provided addresses of ArrayOfPointers.

Parameters:
ArrayOfPointers (Out) - Address of array of pointers to memory space that will set to the multi-vector array of pointers, such that ArrayOfPointers[i] points to the memory location where the ith vector is located.
Returns:
Integer error code, set to 0 if successful.
See Detailed Description section for further discussion.

Definition at line 506 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::Dot (  const Epetra_MultiVector &  A,
double *  Result
)  const
 

Computes dot product of each corresponding pair of vectors.

Parameters:
In A - Multi-vector to be used with the "\e this" multivector.
Out Result - Result[i] will contain the ith dot product result.
Returns:
Integer error code, set to 0 if successful.

Definition at line 966 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::Abs (  const Epetra_MultiVector &  A  ) 
 

Puts element-wise absolute values of input Multi-vector in target.

Parameters:
In A - Input Multi-vector.
Out this will contain the absolute values of the entries of A.
Returns:
Integer error code, set to 0 if successful.
Note: It is possible to use the same argument for A and this.

Definition at line 986 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::Reciprocal (  const Epetra_MultiVector &  A  ) 
 

Puts element-wise reciprocal values of input Multi-vector in target.

Parameters:
In A - Input Multi-vector.
Out this will contain the element-wise reciprocal values of the entries of A.
Returns:
Integer error code, set to 0 if successful. Returns 2 if some entry is too small, but not zero. Returns 1 if some entry is zero.
Note: It is possible to use the same argument for A and this. Also, if a given value of A is smaller than Epetra_DoubleMin (defined in Epetra_Epetra.h), but nonzero, then the return code is 2. If an entry is zero, the return code is 1. However, in all cases the reciprocal value is still used, even if a NaN is the result.

Definition at line 1003 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::Scale (  double  ScalarValue  ) 
 

Scale the current values of a multi-vector, this = ScalarValue*this.

Parameters:
In ScalarValue - Scale value.
Out This - Multi-vector with scaled values.
Returns:
Integer error code, set to 0 if successful.

Definition at line 1030 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::Scale (  double  ScalarA,
const Epetra_MultiVector &  A
) 
 

Replace multi-vector values with scaled values of A, this = ScalarA*A.

Parameters:
In ScalarA - Scale value.
In A - Multi-vector to copy.
Out This - Multi-vector with values overwritten by scaled values of A.
Returns:
Integer error code, set to 0 if successful.

Definition at line 1043 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::Update (  double  ScalarA,
const Epetra_MultiVector &  A,
double  ScalarThis
) 
 

Update multi-vector values with scaled values of A, this = ScalarThis*this + ScalarA*A.

Parameters:
In ScalarA - Scale value for A.
In A - Multi-vector to add.
In ScalarThis - Scale value for this.
Out This - Multi-vector with updatede values.
Returns:
Integer error code, set to 0 if successful.

Definition at line 1062 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::Update (  double  ScalarA,
const Epetra_MultiVector &  A,
double  ScalarB,
const Epetra_MultiVector &  B,
double  ScalarThis
) 
 

Update multi-vector with scaled values of A and B, this = ScalarThis*this + ScalarA*A + ScalarB*B.

Parameters:
In ScalarA - Scale value for A.
In A - Multi-vector to add.
In ScalarB - Scale value for B.
In B - Multi-vector to add.
In ScalarThis - Scale value for this.
Out This - Multi-vector with updatede values.
Returns:
Integer error code, set to 0 if successful.

Definition at line 1103 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::Norm1 (  double *  Result  )  const
 

Compute 1-norm of each vector in multi-vector.

Parameters:
Out Result - Result[i] contains 1-norm of ith vector.
Returns:
Integer error code, set to 0 if successful.

Definition at line 1207 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::Norm2 (  double *  Result  )  const
 

Compute 2-norm of each vector in multi-vector.

Parameters:
Out Result - Result[i] contains 2-norm of ith vector.
Returns:
Integer error code, set to 0 if successful.

Definition at line 1225 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::NormInf (  double *  Result  )  const
 

Compute Inf-norm of each vector in multi-vector.

Parameters:
Out Result - Result[i] contains Inf-norm of ith vector.
Returns:
Integer error code, set to 0 if successful.

Definition at line 1248 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::NormWeighted (  const Epetra_MultiVector &  Weights,
double *  Result
)  const
 

Compute Weighted 2-norm (RMS Norm) of each vector in multi-vector.

Parameters:
In Weights - Multi-vector of weights. If Weights contains a single vector, that vector will be used as the weights for all vectors of this. Otherwise, Weights should have the same number of vectors as this.
Out Result - Result[i] contains the weighted 2-norm of ith vector. Specifically if we denote the ith vector in the multivector by $x$, and the ith weight vector by $w$ and let j represent the jth entry of each vector, on return Result[i] will contain the following result:

\[\sqrt{(1/n)\sum_{j=1}^n(x_j/w_j)^2}\]

, where $n$ is the global length of the vectors.

Returns:
Integer error code, set to 0 if successful.

Definition at line 1269 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::MinValue (  double *  Result  )  const
 

Compute minimum value of each vector in multi-vector.

Note that the vector contents must be already initialized for this function to compute a well-defined result. The length of the vector need not be greater than zero on all processors. If length is greater than zero on any processor then a valid result will be computed.

Parameters:
Out Result - Result[i] contains minimum value of ith vector.
Returns:
Integer error code, set to 0 if successful.

Definition at line 1308 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::MaxValue (  double *  Result  )  const
 

Compute maximum value of each vector in multi-vector.

Note that the vector contents must be already initialized for this function to compute a well-defined result. The length of the vector need not be greater than zero on all processors. If length is greater than zero on any processor then a valid result will be computed.

Parameters:
Out Result - Result[i] contains maximum value of ith vector.
Returns:
Integer error code, set to 0 if successful.

Definition at line 1405 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::MeanValue (  double *  Result  )  const
 

Compute mean (average) value of each vector in multi-vector.

Parameters:
Out Result - Result[i] contains mean value of ith vector.
Returns:
Integer error code, set to 0 if successful.

Definition at line 1502 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::Multiply (  char  TransA,
char  TransB,
double  ScalarAB,
const Epetra_MultiVector &  A,
const Epetra_MultiVector &  B,
double  ScalarThis
) 
 

Matrix-Matrix multiplication, this = ScalarThis*this + ScalarAB*A*B.

This function performs a variety of matrix-matrix multiply operations, interpreting the Epetra_MultiVectors (this-aka C , A and B) as 2D matrices. Variations are due to the fact that A, B and C can be local replicated or global distributed Epetra_MultiVectors and that we may or may not operate with the transpose of A and B. Possible cases are: 


    Total of 32 case (2^5).
    Num
    OPERATIONS                        case  Notes
    1) C(local) = A^X(local) * B^X(local)  4   (X=Transpose or Not, No comm needed) 
    2) C(local) = A^T(distr) * B  (distr)  1   (2D dot product, replicate C)
    3) C(distr) = A  (distr) * B^X(local)  2   (2D vector update, no comm needed)

    Note that the following operations are not meaningful for 
    1D distributions:

    1) C(local) = A^T(distr) * B^T(distr)  1
    2) C(local) = A  (distr) * B^X(distr)  2
    3) C(distr) = A^X(local) * B^X(local)  4
    4) C(distr) = A^X(local) * B^X(distr)  4
    5) C(distr) = A^T(distr) * B^X(local)  2
    6) C(local) = A^X(distr) * B^X(local)  4
    7) C(distr) = A^X(distr) * B^X(local)  4
    8) C(local) = A^X(local) * B^X(distr)  4

Parameters:
In TransA - Operate with the transpose of A if = 'T', else no transpose if = 'N'.
In TransB - Operate with the transpose of B if = 'T', else no transpose if = 'N'.
In ScalarAB - Scalar to multiply with A*B.
In A - Multi-vector.
In B - Multi-vector.
In ScalarThis - Scalar to multiply with this.
Returns:
Integer error code, set to 0 if successful.
Warning:
{Each multi-vector A, B and this is checked if it has constant stride using the ConstantStride() query function. If it does not have constant stride, a temporary copy is made and used for the computation. This activity is transparent to the user, except that there is memory and computation overhead. All temporary space is deleted prior to exit.}

Definition at line 1527 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::Multiply (  double  ScalarAB,
const Epetra_MultiVector &  A,
const Epetra_MultiVector &  B,
double  ScalarThis
) 
 

Multiply a Epetra_MultiVector with another, element-by-element.

This function supports diagonal matrix multiply. A is usually a single vector while B and this may have one or more columns. Note that B and this must have the same shape. A can be one vector or have the same shape as B. The actual computation is this = ScalarThis * this + ScalarAB * B @ A where @ denotes element-wise multiplication.

Definition at line 1674 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::ReciprocalMultiply (  double  ScalarAB,
const Epetra_MultiVector &  A,
const Epetra_MultiVector &  B,
double  ScalarThis
) 
 

Multiply a Epetra_MultiVector by the reciprocal of another, element-by-element.

This function supports diagonal matrix scaling. A is usually a single vector while B and this may have one or more columns. Note that B and this must have the same shape. A can be one vector or have the same shape as B. The actual computation is this = ScalarThis * this + ScalarAB * B @ A where @ denotes element-wise division.

Definition at line 1767 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::SetSeed (  unsigned int  Seed  )  [inline]
 

Set seed for Random function.

Parameters:
In Seed - Should be an integer on the interval (0, 2^31-1).
Returns:
Integer error code, set to 0 if successful.

Definition at line 833 of file Epetra_MultiVector.h.

unsigned int Epetra_MultiVector::Seed (   )  [inline]
 

Get seed from Random function.

Returns:
Current random number seed.

Definition at line 839 of file Epetra_MultiVector.h.

Epetra_MultiVector & Epetra_MultiVector::operator= (  const Epetra_MultiVector &  Source  ) 
 

= Operator.

Parameters:
In A - Epetra_MultiVector to copy.
Returns:
Epetra_MultiVector.

Definition at line 1895 of file Epetra_MultiVector.cpp.

double*& Epetra_MultiVector::operator[] (  int  i  )  [inline]
 

Vector access function.

Returns:
Pointer to the array of doubles containing the local values of the ith vector in the multi-vector.

Reimplemented in Epetra_Vector.

Definition at line 863 of file Epetra_MultiVector.h.

double* const& Epetra_MultiVector::operator[] (  int  i  )  const [inline]
 

Vector access function.

Returns:
Pointer to the array of doubles containing the local values of the ith vector in the multi-vector.

Reimplemented in Epetra_Vector.

Definition at line 869 of file Epetra_MultiVector.h.

Epetra_Vector *& Epetra_MultiVector::operator() (  int  i  ) 
 

Vector access function.

Returns:
An Epetra_Vector pointer to the ith vector in the multi-vector.

Definition at line 1862 of file Epetra_MultiVector.cpp.

const Epetra_Vector *& Epetra_MultiVector::operator() (  int  i  )  const
 

Vector access function.

Returns:
An Epetra_Vector pointer to the ith vector in the multi-vector.

Definition at line 1878 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::NumVectors (   )  const [inline]
 

Returns the number of vectors in the multi-vector.

Definition at line 888 of file Epetra_MultiVector.h.

int Epetra_MultiVector::MyLength (   )  const [inline]
 

Returns the local vector length on the calling processor of vectors in the multi-vector.

Definition at line 891 of file Epetra_MultiVector.h.

int Epetra_MultiVector::GlobalLength (   )  const [inline]
 

Returns the global vector length of vectors in the multi-vector.

Definition at line 894 of file Epetra_MultiVector.h.

int Epetra_MultiVector::Stride (   )  const [inline]
 

Returns the stride between vectors in the multi-vector (only meaningful if ConstantStride() is true).

Definition at line 897 of file Epetra_MultiVector.h.

bool Epetra_MultiVector::ConstantStride (   )  const [inline]
 

Returns true if this multi-vector has constant stride between vectors.

Definition at line 900 of file Epetra_MultiVector.h.

int Epetra_MultiVector::ReplaceMap (  const Epetra_BlockMap &  map  ) 
 

Replace map, only if new map has same point-structure as current map.

return 0 if map is replaced, -1 if not.

Definition at line 462 of file Epetra_MultiVector.cpp.

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

Print method.

Reimplemented from Epetra_DistObject.

Definition at line 1967 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::ResetView (  double **  ArrayOfPointers  ) 
 

Reset the view of an existing multivector to point to new user data.

Allows the (very) light-weight replacement of multivector values for an existing multivector that was constructed using an Epetra_DataAccess mode of View. No checking is performed to see if the array of values passed in contains valid data. It is assumed that the user has verified the integrity of data before calling this method. This method is useful for situations where a multivector is needed for use with an Epetra operator or matrix and the user is not passing in a multivector, or the multivector is being passed in with another map that is not exactly compatible with the operator, but has the correct number of entries.

This method is used by AztecOO and Ifpack in the matvec, and solve methods to improve performance and reduce repeated calls to constructors and destructors.

Parameters:
ArrayOfPointers Contains the array of pointers containing the multivector data.
Returns:
Integer error code, set to 0 if successful, -1 if the multivector was not created as a View.
Warning:
This method is extremely dangerous and should only be used by experts.

Definition at line 1955 of file Epetra_MultiVector.cpp.

double* Epetra_MultiVector::Values (   )  const [inline]
 

Get pointer to MultiVector values.

Definition at line 941 of file Epetra_MultiVector.h.

double** Epetra_MultiVector::Pointers (   )  const [inline]
 

Get pointer to individual vector pointers.

Definition at line 944 of file Epetra_MultiVector.h.

int Epetra_MultiVector::Reduce (   ) 
 

Definition at line 1920 of file Epetra_MultiVector.cpp.

void Epetra_MultiVector::Assign (  const Epetra_MultiVector &  rhs  )  [protected]
 

Definition at line 1904 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::CheckInput (   )  [protected]
 

int Epetra_MultiVector::AllocateForCopy (  void   )  [private]
 

Definition at line 234 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::DoCopy (  void   )  [private]
 

Definition at line 264 of file Epetra_MultiVector.cpp.

void Epetra_MultiVector::UpdateDoubleTemp (   )  const [inline, private]
 

Definition at line 966 of file Epetra_MultiVector.h.

void Epetra_MultiVector::UpdateVectors (   )  const [inline, private]
 

Definition at line 969 of file Epetra_MultiVector.h.

int Epetra_MultiVector::AllocateForView (  void   )  [private]
 

Definition at line 286 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::DoView (  void   )  [private]
 

Definition at line 313 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::ChangeGlobalValue (  int  GlobalBlockRow,
int  BlockRowOffset,
int  VectorIndex,
double  ScalarValue,
bool  SumInto
)  [private]
 

Definition at line 397 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::ChangeMyValue (  int  MyBlockRow,
int  BlockRowOffset,
int  VectorIndex,
double  ScalarValue,
bool  SumInto
)  [private]
 

Definition at line 405 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::CheckSizes (  const Epetra_SrcDistObject &  A  )  [private, virtual]
 

Allows the source and target (this) objects to be compared for compatibility, return nonzero if not.

Implements Epetra_DistObject.

Definition at line 523 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::CopyAndPermute (  const Epetra_SrcDistObject &  Source,
int  NumSameIDs,
int  NumPermuteIDs,
int *  PermuteToLIDs,
int *  PermuteFromLIDs,
const Epetra_OffsetIndex *  Indexor
)  [private, virtual]
 

Perform ID copies and permutations that are on processor.

Implements Epetra_DistObject.

Definition at line 532 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::PackAndPrepare (  const Epetra_SrcDistObject &  Source,
int  NumExportIDs,
int *  ExportLIDs,
int &  LenExports,
char *&  Exports,
int &  SizeOfPacket,
int *  Sizes,
bool &  VarSizes,
Epetra_Distributor &  Distor
)  [private, virtual]
 

Perform any packing or preparation required for call to DoTransfer().

Implements Epetra_DistObject.

Definition at line 637 of file Epetra_MultiVector.cpp.

int Epetra_MultiVector::UnpackAndCombine (  const Epetra_SrcDistObject &  Source,
int  NumImportIDs,
int *  ImportLIDs,
int  LenImports,
char *  Imports,
int &  SizeOfPacket,
Epetra_Distributor &  Distor,
Epetra_CombineMode  CombineMode,
const Epetra_OffsetIndex *  Indexor
)  [private, virtual]
 

Perform any unpacking and combining after call to DoTransfer().

Implements Epetra_DistObject.

Definition at line 729 of file Epetra_MultiVector.cpp.

Member Data Documentation

double* Epetra_MultiVector::Values_ [protected]
 

Definition at line 956 of file Epetra_MultiVector.h.

double** Epetra_MultiVector::Pointers_ [private]
 

Definition at line 1016 of file Epetra_MultiVector.h.

int Epetra_MultiVector::MyLength_ [private]
 

Definition at line 1018 of file Epetra_MultiVector.h.

int Epetra_MultiVector::GlobalLength_ [private]
 

Definition at line 1019 of file Epetra_MultiVector.h.

int Epetra_MultiVector::NumVectors_ [private]
 

Definition at line 1020 of file Epetra_MultiVector.h.

bool Epetra_MultiVector::UserAllocated_ [private]
 

Definition at line 1021 of file Epetra_MultiVector.h.

bool Epetra_MultiVector::ConstantStride_ [private]
 

Definition at line 1022 of file Epetra_MultiVector.h.

int Epetra_MultiVector::Stride_ [private]
 

Definition at line 1023 of file Epetra_MultiVector.h.

bool Epetra_MultiVector::Allocated_ [private]
 

Definition at line 1024 of file Epetra_MultiVector.h.

double* Epetra_MultiVector::DoubleTemp_ [mutable, private]
 

Definition at line 1025 of file Epetra_MultiVector.h.

Epetra_Vector** Epetra_MultiVector::Vectors_ [mutable, private]
 

Definition at line 1026 of file Epetra_MultiVector.h.

Epetra_Util Epetra_MultiVector::Util_ [private]
 

Definition at line 1027 of file Epetra_MultiVector.h.

The documentation for this class was generated from the following files:
Generated on Thu Sep 18 12:38:06 2008 for Epetra Package Browser (Single Doxygen Collection) by doxygen 1.3.9.1