Epetra Package Browser (Single Doxygen Collection) Development
Private Member Functions
Epetra_Vector Class Reference

Epetra_Vector: A class for constructing and using dense vectors on a parallel computer. More...

#include <Epetra_Vector.h>

Inheritance diagram for Epetra_Vector:
Inheritance graph
[legend]

List of all members.

Private Member Functions

int ChangeValues (int NumEntries, int BlockOffset, const double *Values, const int *Indices, bool IndicesGlobal, bool SumInto)

Constructors/destructors

 Epetra_Vector (const Epetra_BlockMap &Map, bool zeroOut=true)
 Basic Epetra_Vector constuctor.
 Epetra_Vector (const Epetra_Vector &Source)
 Epetra_Vector copy constructor.
 Epetra_Vector (Epetra_DataAccess CV, const Epetra_BlockMap &Map, double *V)
 Set vector values from user array.
 Epetra_Vector (Epetra_DataAccess CV, const Epetra_MultiVector &Source, int Index)
 Set vector values from a vector in an existing Epetra_MultiVector.
virtual ~Epetra_Vector ()
 Epetra_Vector destructor.

Post-construction modification routines

int ReplaceGlobalValues (int NumEntries, const double *Values, const int *Indices)
 Replace values in a vector with a given indexed list of values, indices are in global index space.
int ReplaceMyValues (int NumEntries, const double *Values, const int *Indices)
 Replace values in a vector with a given indexed list of values, indices are in local index space.
int SumIntoGlobalValues (int NumEntries, const double *Values, const int *Indices)
 Sum values into a vector with a given indexed list of values, indices are in global index space.
int SumIntoMyValues (int NumEntries, const double *Values, const int *Indices)
 Sum values into a vector with a given indexed list of values, indices are in local index space.
int ReplaceGlobalValues (int NumEntries, int BlockOffset, const double *Values, const int *Indices)
 Replace values in a vector with a given indexed list of values at the specified BlockOffset, indices are in global index space.
int ReplaceMyValues (int NumEntries, int BlockOffset, const double *Values, const int *Indices)
 Replace values in a vector with a given indexed list of values at the specified BlockOffset, indices are in local index space.
int SumIntoGlobalValues (int NumEntries, int BlockOffset, const double *Values, const int *Indices)
 Sum values into a vector with a given indexed list of values at the specified BlockOffset, indices are in global index space.
int SumIntoMyValues (int NumEntries, int BlockOffset, const double *Values, const int *Indices)
 Sum values into a vector with a given indexed list of values at the specified BlockOffset, indices are in local index space.

Extraction methods

int ExtractCopy (double *V) const
 Put vector values into user-provided array.
int ExtractView (double **V) const
 Set user-provided address of V.

Overloaded operators

double & operator[] (int index)
 Element access function.
const double & operator[] (int index) const
 Element access function.

Expert-only unsupported methods

int ResetView (double *Values_in)
 Reset the view of an existing vector to point to new user data.

Detailed Description

Epetra_Vector: A class for constructing and using dense vectors on a parallel computer.

The Epetra_Vector class enables the construction and use of real-valued, double-precision dense vectors in a distributed memory environment. The distribution of the dense vector is determined in part by a Epetra_Comm object and a Epetra_Map (or Epetra_LocalMap or Epetra_BlockMap).

This class is derived from the Epetra_MultiVector class. As such, it has full access to all of the functionality provided in the Epetra_MultiVector class.

Distributed Global vs. Replicated Local

Constructing Epetra_Vectors

There are four Epetra_Vector constructors. The first is a basic constructor that allocates space and sets all values to zero, the second is a copy constructor. The third and fourth constructors work with user data. These 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 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_Vector 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 vector.

There are four different Epetra_Vector constructors:

Extracting Data from Epetra_Vectors

Once a Epetra_Vector 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 two Extract functions:

Vector and Utility Functions

Once a Epetra_Vector is constructed, a variety of mathematical functions can be applied to the vector. Specifically:

The final useful function is Flops(). Each Epetra_Vector 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.

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

Definition at line 142 of file Epetra_Vector.h.


Constructor & Destructor Documentation

Epetra_Vector::Epetra_Vector ( const Epetra_BlockMap Map,
bool  zeroOut = true 
)

Basic Epetra_Vector constuctor.

Creates a Epetra_Vector object and fills with zero values.

Parameters:
InMap - A Epetra_LocalMap, Epetra_Map or Epetra_BlockMap.
InzeroOut - 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.
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.
Returns:
Pointer to a Epetra_Vector.

Definition at line 47 of file Epetra_Vector.cpp.

Epetra_Vector::Epetra_Vector ( const Epetra_Vector Source)

Epetra_Vector copy constructor.

Definition at line 53 of file Epetra_Vector.cpp.

Epetra_Vector::Epetra_Vector ( Epetra_DataAccess  CV,
const Epetra_BlockMap Map,
double *  V 
)

Set vector values from user array.

Parameters:
InEpetra_DataAccess - Enumerated type set to Copy or View.
InMap - A Epetra_LocalMap, Epetra_Map or Epetra_BlockMap.
InV - Pointer to an array of double precision numbers..
Returns:
Integer error code, set to 0 if successful.

See Detailed Description section for further discussion.

Definition at line 58 of file Epetra_Vector.cpp.

Epetra_Vector::Epetra_Vector ( Epetra_DataAccess  CV,
const Epetra_MultiVector Source,
int  Index 
)

Set vector values from a vector in an existing Epetra_MultiVector.

Parameters:
InEpetra_DataAccess - Enumerated type set to Copy or View.
InMap - A Epetra_LocalMap, Epetra_Map or Epetra_BlockMap.
InSource - An existing fully constructed Epetra_MultiVector.
InIndex - Index of vector to access.
Returns:
Integer error code, set to 0 if successful.

See Detailed Description section for further discussion.

Definition at line 64 of file Epetra_Vector.cpp.

Epetra_Vector::~Epetra_Vector ( ) [virtual]

Epetra_Vector destructor.

Definition at line 70 of file Epetra_Vector.cpp.


Member Function Documentation

int Epetra_Vector::ReplaceGlobalValues ( int  NumEntries,
const double *  Values,
const int *  Indices 
)

Replace values in a vector with a given indexed list of values, indices are in global index space.

Replace the Indices[i] entry in the this object with Values[i], for i=0; i<NumEntries. The indices are in global index space.

Parameters:
InNumEntries - Number of vector entries to modify.
InValues - Values which will replace existing values in vector, of length NumEntries.
InIndices - Indices in global index space corresponding to Values.
Returns:
Integer error code, set to 0 if successful, set to 1 if one or more indices are not associated with calling processor.

Definition at line 98 of file Epetra_Vector.cpp.

int Epetra_Vector::ReplaceMyValues ( int  NumEntries,
const double *  Values,
const int *  Indices 
)

Replace values in a vector with a given indexed list of values, indices are in local index space.

Replace the Indices[i] entry in the this object with Values[i], for i=0; i<NumEntries. The indices are in local index space.

Parameters:
InNumEntries - Number of vector entries to modify.
InValues - Values which will replace existing values in vector, of length NumEntries.
InIndices - Indices in local index space corresponding to Values.
Returns:
Integer error code, set to 0 if successful, set to 1 if one or more indices are not associated with calling processor.

Definition at line 104 of file Epetra_Vector.cpp.

int Epetra_Vector::SumIntoGlobalValues ( int  NumEntries,
const double *  Values,
const int *  Indices 
)

Sum values into a vector with a given indexed list of values, indices are in global index space.

Sum Values[i] into the Indices[i] entry in the this object, for i=0; i<NumEntries. The indices are in global index space.

Parameters:
InNumEntries - Number of vector entries to modify.
InValues - Values which will replace existing values in vector, of length NumEntries.
InIndices - Indices in global index space corresponding to Values.
Returns:
Integer error code, set to 0 if successful, set to 1 if one or more indices are not associated with calling processor.

Definition at line 110 of file Epetra_Vector.cpp.

int Epetra_Vector::SumIntoMyValues ( int  NumEntries,
const double *  Values,
const int *  Indices 
)

Sum values into a vector with a given indexed list of values, indices are in local index space.

Sum Values[i] into the Indices[i] entry in the this object, for i=0; i<NumEntries. The indices are in local index space.

Parameters:
InNumEntries - Number of vector entries to modify.
InValues - Values which will replace existing values in vector, of length NumEntries.
InIndices - Indices in local index space corresponding to Values.
Returns:
Integer error code, set to 0 if successful, set to 1 if one or more indices are not associated with calling processor.

Definition at line 116 of file Epetra_Vector.cpp.

int Epetra_Vector::ReplaceGlobalValues ( int  NumEntries,
int  BlockOffset,
const double *  Values,
const int *  Indices 
)

Replace values in a vector with a given indexed list of values at the specified BlockOffset, indices are in global index space.

Replace the Indices[i] entry in the this object with Values[i], for i=0; i<NumEntries. The indices are in global index space. This method is intended for vector that are defined using block maps. In this situation, an index value is associated with one or more vector entries, depending on the element size of the given index. The BlockOffset argument indicates which vector entry to modify as an offset from the first vector entry associated with the given index. The offset is used for each entry in the input list.

Parameters:
InNumEntries - Number of vector entries to modify.
InBlockOffset - Offset from the first vector entry associated with each of the given indices.
InValues - Values which will replace existing values in vector, of length NumEntries.
InIndices - Indices in global index space corresponding to Values.
Returns:
Integer error code, set to 0 if successful, set to 1 if one or more indices are not associated with calling processor.

Definition at line 122 of file Epetra_Vector.cpp.

int Epetra_Vector::ReplaceMyValues ( int  NumEntries,
int  BlockOffset,
const double *  Values,
const int *  Indices 
)

Replace values in a vector with a given indexed list of values at the specified BlockOffset, indices are in local index space.

Replace the (Indices[i], BlockOffset) entry in the this object with Values[i], for i=0; i<NumEntries. The indices are in local index space. This method is intended for vector that are defined using block maps. In this situation, an index value is associated with one or more vector entries, depending on the element size of the given index. The BlockOffset argument indicates which vector entry to modify as an offset from the first vector entry associated with the given index. The offset is used for each entry in the input list.

Parameters:
InNumEntries - Number of vector entries to modify.
InBlockOffset - Offset from the first vector entry associated with each of the given indices.
InValues - Values which will replace existing values in vector, of length NumEntries.
InIndices - Indices in local index space corresponding to Values.
Returns:
Integer error code, set to 0 if successful, set to 1 if one or more indices are not associated with calling processor.

Definition at line 128 of file Epetra_Vector.cpp.

int Epetra_Vector::SumIntoGlobalValues ( int  NumEntries,
int  BlockOffset,
const double *  Values,
const int *  Indices 
)

Sum values into a vector with a given indexed list of values at the specified BlockOffset, indices are in global index space.

Sum Values[i] into the Indices[i] entry in the this object, for i=0; i<NumEntries. The indices are in global index space. This method is intended for vector that are defined using block maps. In this situation, an index value is associated with one or more vector entries, depending on the element size of the given index. The BlockOffset argument indicates which vector entry to modify as an offset from the first vector entry associated with the given index. The offset is used for each entry in the input list.

Parameters:
InNumEntries - Number of vector entries to modify.
InBlockOffset - Offset from the first vector entry associated with each of the given indices.
InValues - Values which will replace existing values in vector, of length NumEntries.
InIndices - Indices in global index space corresponding to Values.
Returns:
Integer error code, set to 0 if successful, set to 1 if one or more indices are not associated with calling processor.

Definition at line 134 of file Epetra_Vector.cpp.

int Epetra_Vector::SumIntoMyValues ( int  NumEntries,
int  BlockOffset,
const double *  Values,
const int *  Indices 
)

Sum values into a vector with a given indexed list of values at the specified BlockOffset, indices are in local index space.

Sum Values[i] into the Indices[i] entry in the this object, for i=0; i<NumEntries. The indices are in local index space. This method is intended for vector that are defined using block maps. In this situation, an index value is associated with one or more vector entries, depending on the element size of the given index. The BlockOffset argument indicates which vector entry to modify as an offset from the first vector entry associated with the given index. The offset is used for each entry in the input list.

Parameters:
InNumEntries - Number of vector entries to modify.
InBlockOffset - Offset from the first vector entry associated with each of the given indices.
InValues - Values which will replace existing values in vector, of length NumEntries.
InIndices - Indices in local index space corresponding to Values.
Returns:
Integer error code, set to 0 if successful, set to 1 if one or more indices are not associated with calling processor.

Definition at line 140 of file Epetra_Vector.cpp.

int Epetra_Vector::ExtractCopy ( double *  V) const

Put vector values into user-provided array.

Parameters:
OutV - Pointer to memory space that will contain the vector values.
Returns:
Integer error code, set to 0 if successful.

Definition at line 73 of file Epetra_Vector.cpp.

int Epetra_Vector::ExtractView ( double **  V) const

Set user-provided address of V.

Parameters:
OutV - Address of a pointer to that will be set to point to the values of the vector.
Returns:
Integer error code, set to 0 if successful.

Definition at line 78 of file Epetra_Vector.cpp.

double& Epetra_Vector::operator[] ( int  index) [inline]

Element access function.

Returns:
V[Index].

Reimplemented from Epetra_MultiVector.

Definition at line 398 of file Epetra_Vector.h.

const double& Epetra_Vector::operator[] ( int  index) const [inline]

Element access function.

Returns:
V[Index].

Reimplemented from Epetra_MultiVector.

Definition at line 414 of file Epetra_Vector.h.

int Epetra_Vector::ResetView ( double *  Values_in) [inline]

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

Allows the (very) light-weight replacement of multivector values for an existing vector that was constructed using an Epetra_DataAccess mode of View. No checking is performed to see if the values passed in contain 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 vector 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:
ValuesVector 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 455 of file Epetra_Vector.h.

int Epetra_Vector::ChangeValues ( int  NumEntries,
int  BlockOffset,
const double *  Values,
const int *  Indices,
bool  IndicesGlobal,
bool  SumInto 
) [private]

Definition at line 146 of file Epetra_Vector.cpp.


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