292 lines
9.2 KiB
C++
292 lines
9.2 KiB
C++
|
|
//@HEADER
|
|
/*
|
|
************************************************************************
|
|
|
|
Epetra: Linear Algebra Services Package
|
|
Copyright (2001) Sandia Corporation
|
|
|
|
Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
|
|
license for use of this work by or on behalf of the U.S. Government.
|
|
|
|
This library is free software; you can redistribute it and/or modify
|
|
it under the terms of the GNU Lesser General Public License as
|
|
published by the Free Software Foundation; either version 2.1 of the
|
|
License, or (at your option) any later version.
|
|
|
|
This library is distributed in the hope that it will be useful, but
|
|
WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
Lesser General Public License for more details.
|
|
|
|
You should have received a copy of the GNU Lesser General Public
|
|
License along with this library; if not, write to the Free Software
|
|
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
|
|
USA
|
|
Questions? Contact Michael A. Heroux (maherou@sandia.gov)
|
|
|
|
************************************************************************
|
|
*/
|
|
//@HEADER
|
|
|
|
#ifndef EPETRA_INTVECTOR_H
|
|
#define EPETRA_INTVECTOR_H
|
|
|
|
#include "Epetra_DistObject.h"
|
|
#include "Epetra_BlockMap.h"
|
|
#include "Epetra_Distributor.h"
|
|
class Epetra_Map;
|
|
|
|
//! Epetra_IntVector: A class for constructing and using dense integer vectors on a parallel computer.
|
|
|
|
/*! The Epetra_IntVector class enables the construction and use of integer
|
|
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).
|
|
|
|
|
|
<b> Distributed Global vs. Replicated Local</b>
|
|
<ul>
|
|
<li> 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.
|
|
<li> 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.
|
|
</ul>
|
|
|
|
<b>Constructing Epetra_IntVectors</b>
|
|
|
|
There are four Epetra_IntVector 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:
|
|
<ol>
|
|
<li> Copy mode - Allocates memory and makes a copy of the user-provided data. In this case, the
|
|
user data is not needed after construction.
|
|
<li> 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.
|
|
</ol>
|
|
|
|
\warning View mode is \e 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_IntVector constructors require a map argument that describes the layout of elements
|
|
on the parallel machine. Specifically,
|
|
\c map is a Epetra_Map, Epetra_LocalMap or Epetra_BlockMap object describing the desired
|
|
memory layout for the vector.
|
|
|
|
There are four different Epetra_IntVector constructors:
|
|
<ul>
|
|
<li> Basic - All values are zero.
|
|
<li> Copy - Copy an existing vector.
|
|
<li> Copy from or make view of user int array.
|
|
</ul>
|
|
|
|
<b>Extracting Data from Epetra_IntVectors</b>
|
|
|
|
Once a Epetra_IntVector is constructed, it is possible to extract a copy of the values or create
|
|
a view of them.
|
|
|
|
\warning ExtractView functions are \e 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:
|
|
<ul>
|
|
<li> ExtractCopy - Copy values into a user-provided array.
|
|
<li> ExtractView - Set user-provided array to point to Epetra_IntVector data.
|
|
</ul>
|
|
|
|
|
|
\warning A Epetra_Map, Epetra_LocalMap or Epetra_BlockMap object is required for all
|
|
Epetra_IntVector constructors.
|
|
|
|
*/
|
|
|
|
//=========================================================================
|
|
class Epetra_IntVector : public Epetra_DistObject {
|
|
|
|
public:
|
|
|
|
//! @name Constructors/destructors
|
|
//@{
|
|
//! Basic Epetra_IntVector constuctor.
|
|
/*! Creates a Epetra_IntVector object and, by default, fills with zero values.
|
|
|
|
\param 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.
|
|
\param In
|
|
zeroOut - If <tt>true</tt> then the allocated memory will be zeroed
|
|
out initialy. If <tt>false</tt> then this memory will not
|
|
be touched which can be significantly faster.
|
|
|
|
\return Pointer to a Epetra_IntVector.
|
|
|
|
*/
|
|
Epetra_IntVector(const Epetra_BlockMap& Map, bool zeroOut = true);
|
|
|
|
//! Epetra_IntVector copy constructor.
|
|
|
|
Epetra_IntVector(const Epetra_IntVector& Source);
|
|
|
|
//! Set vector values from user array.
|
|
/*!
|
|
\param In
|
|
Epetra_DataAccess - Enumerated type set to Copy or View.
|
|
\param In
|
|
Map - A Epetra_LocalMap, Epetra_Map or Epetra_BlockMap.
|
|
\param In
|
|
V - Pointer to an array of integer numbers..
|
|
|
|
\return Integer error code, set to 0 if successful.
|
|
|
|
See Detailed Description section for further discussion.
|
|
*/
|
|
Epetra_IntVector(Epetra_DataAccess CV, const Epetra_BlockMap& Map, int *V);
|
|
|
|
//! Epetra_IntVector destructor.
|
|
virtual ~Epetra_IntVector ();
|
|
//@}
|
|
|
|
|
|
//! @name Post-construction modification methods
|
|
//@{
|
|
//! Set all elements of the vector to Value
|
|
int PutValue(int Value);
|
|
//@}
|
|
|
|
|
|
//! @name Extraction methods
|
|
//@{
|
|
|
|
|
|
//! Put vector values into user-provided array.
|
|
/*!
|
|
\param Out
|
|
V - Pointer to memory space that will contain the vector values.
|
|
|
|
\return Integer error code, set to 0 if successful.
|
|
*/
|
|
int ExtractCopy(int *V) const;
|
|
|
|
//! Set user-provided address of V.
|
|
/*!
|
|
\param Out
|
|
V - Address of a pointer to that will be set to point to the values of the vector.
|
|
|
|
\return Integer error code, set to 0 if successful.
|
|
*/
|
|
int ExtractView(int **V) const;
|
|
//@}
|
|
|
|
//! @name Mathematical methods
|
|
//@{
|
|
//! Find maximum value
|
|
/*!
|
|
\return Maximum value across all processors.
|
|
*/
|
|
int MaxValue();
|
|
|
|
//! Find minimum value
|
|
/*!
|
|
\return Minimum value across all processors.
|
|
*/
|
|
int MinValue();
|
|
|
|
//@}
|
|
|
|
//! @name Overloaded operators
|
|
//@{
|
|
|
|
//! = Operator.
|
|
/*!
|
|
\param In
|
|
A - Epetra_IntVector to copy.
|
|
|
|
\return Epetra_IntVector.
|
|
*/
|
|
Epetra_IntVector& operator = (const Epetra_IntVector& Source);
|
|
|
|
//! Element access function.
|
|
/*!
|
|
\return V[Index].
|
|
*/
|
|
int& operator [] (int index) { return Values_[index]; }
|
|
//! Element access function.
|
|
/*!
|
|
\return V[Index].
|
|
*/
|
|
const int& operator [] (int index) const { return Values_[index]; }
|
|
//@}
|
|
|
|
//! @name Attribute access functions
|
|
//@{
|
|
|
|
//! Returns a pointer to an array containing the values of this vector.
|
|
int * Values() const {return(Values_);};
|
|
|
|
//! Returns the local vector length on the calling processor of vectors in the multi-vector.
|
|
int MyLength() const {return(Map().NumMyPoints());};
|
|
|
|
//! Returns the global vector length of vectors in the multi-vector.
|
|
int GlobalLength() const {return(Map().NumGlobalPoints());};
|
|
//@}
|
|
|
|
//! @name I/O methods
|
|
//@{
|
|
|
|
//! Print method
|
|
virtual void Print(ostream & os) const;
|
|
//@}
|
|
private:
|
|
|
|
int AllocateForCopy();
|
|
int DoCopy(int * V);
|
|
int AllocateForView();
|
|
int DoView(int * V);
|
|
|
|
// Routines to implement Epetra_DistObject virtual methods
|
|
int CheckSizes(const Epetra_SrcDistObject& A);
|
|
|
|
int CopyAndPermute(const Epetra_SrcDistObject & Source,
|
|
int NumSameIDs,
|
|
int NumPermuteIDs,
|
|
int * PermuteToLIDs,
|
|
int * PermuteFromLIDs,
|
|
const Epetra_OffsetIndex * Indexor);
|
|
|
|
int PackAndPrepare(const Epetra_SrcDistObject & Source,
|
|
int NumExportIDs,
|
|
int * ExportLIDs,
|
|
int & LenExports,
|
|
char * & Exports,
|
|
int & SizeOfPacket,
|
|
int * Sizes,
|
|
bool& VarSizes,
|
|
Epetra_Distributor & Distor);
|
|
|
|
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);
|
|
|
|
int * Values_;
|
|
bool UserAllocated_;
|
|
bool Allocated_;
|
|
};
|
|
|
|
#endif /* EPETRA_INTVECTOR_H */
|