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:

[legend]Collaboration diagram for Epetra_Vector:[legend]List of all members.

Public Member Functions
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, double *Values, int *Indices)
	Replace values in a vector with a given indexed list of values, indices are in global index space.
int	ReplaceMyValues (int NumEntries, double *Values, int *Indices)
	Replace values in a vector with a given indexed list of values, indices are in local index space.
int	SumIntoGlobalValues (int NumEntries, double *Values, int *Indices)
	Sum values into a vector with a given indexed list of values, indices are in global index space.
int	SumIntoMyValues (int NumEntries, double *Values, 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, double *Values, 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, double *Values, 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, double *Values, 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, double *Values, 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)
	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

• Distributed Global Vectors - In most instances, a multi-vector will be partitioned across multiple memory images associated with multiple processors. In this case, there is a unique copy of each element and elements are spread across all processors specified by the Epetra_Comm communicator.
• Replicated Local Vectors - Some algorithms use vectors that are too small to be distributed across all processors. Replicated local vectors handle these types of situation.

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:

• Basic - All values are zero.
• Copy - Copy an existing vector.
• Copy from or make view of user double array.
• Copy or make view of a vector from a Epetra_MultiVector object.

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:

• ExtractCopy - Copy values into a user-provided array.
• ExtractView - Set user-provided array to point to Epetra_Vector data.

Vector and Utility Functions

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

• Dot Products.
• Vector Updates.
• p Norms.
• Weighted Norms.
• Minimum, Maximum and Average Values.

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.

---

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: In  Map - A Epetra_LocalMap, Epetra_Map or Epetra_BlockMap. 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. 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.

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

Set vector values from user array. Parameters: In  Epetra_DataAccess - Enumerated type set to Copy or View. In  Map - A Epetra_LocalMap, Epetra_Map or Epetra_BlockMap. In  V - Pointer to an array of double precision numbers.. Returns: Integer error code, set to 0 if successful. See Detailed Description section for further discussion.

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: In  Epetra_DataAccess - Enumerated type set to Copy or View. In  Map - A Epetra_LocalMap, Epetra_Map or Epetra_BlockMap. In  Source - An existing fully constructed Epetra_MultiVector. In  Index - Index of vector to access. Returns: Integer error code, set to 0 if successful. See Detailed Description section for further discussion.

---

Member Function Documentation

int Epetra_Vector::ExtractCopy (  double *  V  )  const

Put vector values into user-provided array. Parameters: Out  V - Pointer to memory space that will contain the vector values. Returns: Integer error code, set to 0 if successful.

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

Set user-provided address of V. Parameters: Out  V - 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.

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

Element access function. Returns: V[Index]. Reimplemented from Epetra_MultiVector.

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

Element access function. Returns: V[Index]. Reimplemented from Epetra_MultiVector.

int Epetra_Vector::ReplaceGlobalValues (  int  NumEntries, int  BlockOffset, double *  Values, 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: In  NumEntries - Number of vector entries to modify. In  BlockOffset - Offset from the first vector entry associated with each of the given indices. In  Values - Values which will replace existing values in vector, of length NumEntries. In  Indices - 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.

int Epetra_Vector::ReplaceGlobalValues (  int  NumEntries, double *  Values, 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: In  NumEntries - Number of vector entries to modify. In  Values - Values which will replace existing values in vector, of length NumEntries. In  Indices - 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.

int Epetra_Vector::ReplaceMyValues (  int  NumEntries, int  BlockOffset, double *  Values, 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: In  NumEntries - Number of vector entries to modify. In  BlockOffset - Offset from the first vector entry associated with each of the given indices. In  Values - Values which will replace existing values in vector, of length NumEntries. In  Indices - 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.

int Epetra_Vector::ReplaceMyValues (  int  NumEntries, double *  Values, 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: In  NumEntries - Number of vector entries to modify. In  Values - Values which will replace existing values in vector, of length NumEntries. In  Indices - 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.

int Epetra_Vector::ResetView (  double *  Values  )  [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: Values  Vector 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.

int Epetra_Vector::SumIntoGlobalValues (  int  NumEntries, int  BlockOffset, double *  Values, 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: In  NumEntries - Number of vector entries to modify. In  BlockOffset - Offset from the first vector entry associated with each of the given indices. In  Values - Values which will replace existing values in vector, of length NumEntries. In  Indices - 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.

int Epetra_Vector::SumIntoGlobalValues (  int  NumEntries, double *  Values, 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: In  NumEntries - Number of vector entries to modify. In  Values - Values which will replace existing values in vector, of length NumEntries. In  Indices - 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.

int Epetra_Vector::SumIntoMyValues (  int  NumEntries, int  BlockOffset, double *  Values, 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: In  NumEntries - Number of vector entries to modify. In  BlockOffset - Offset from the first vector entry associated with each of the given indices. In  Values - Values which will replace existing values in vector, of length NumEntries. In  Indices - 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.

int Epetra_Vector::SumIntoMyValues (  int  NumEntries, double *  Values, 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: In  NumEntries - Number of vector entries to modify. In  Values - Values which will replace existing values in vector, of length NumEntries. In  Indices - 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.

---

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

• Epetra_Vector.h

---