Epetra_CrsMatrix.h

Go to the documentation of this file.
00001 
00002 //@HEADER
00003 /*
00004 ************************************************************************
00005 
00006               Epetra: Linear Algebra Services Package 
00007                 Copyright (2001) Sandia Corporation
00008 
00009 Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
00010 license for use of this work by or on behalf of the U.S. Government.
00011 
00012 This library is free software; you can redistribute it and/or modify
00013 it under the terms of the GNU Lesser General Public License as
00014 published by the Free Software Foundation; either version 2.1 of the
00015 License, or (at your option) any later version.
00016  
00017 This library is distributed in the hope that it will be useful, but
00018 WITHOUT ANY WARRANTY; without even the implied warranty of
00019 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00020 Lesser General Public License for more details.
00021  
00022 You should have received a copy of the GNU Lesser General Public
00023 License along with this library; if not, write to the Free Software
00024 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
00025 USA
00026 Questions? Contact Michael A. Heroux (maherou@sandia.gov) 
00027 
00028 ************************************************************************
00029 */
00030 //@HEADER
00031 
00032 #ifndef EPETRA_CRSMATRIX_H
00033 #define EPETRA_CRSMATRIX_H
00034 
00035 #include "Epetra_DistObject.h" 
00036 #include "Epetra_CompObject.h" 
00037 #include "Epetra_BLAS.h"
00038 #include "Epetra_RowMatrix.h"
00039 #include "Epetra_Operator.h"
00040 #include "Epetra_CrsGraph.h"
00041 class Epetra_Map;
00042 class Epetra_Import;
00043 class Epetra_Export;
00044 class Epetra_Vector;
00045 class Epetra_MultiVector;
00046 
00047 // Define this to see a complete dump a an Epetra_CrsMatrix::Multiply(...) call
00048 //#define EPETRA_CRS_MATRIX_TRACE_DUMP_MULTIPLY
00049 
00050 #ifdef EPETRA_CRS_MATRIX_TRACE_DUMP_MULTIPLY
00051 extern bool Epetra_CrsMatrixTraceDumpMultiply;
00052 #endif // EPETRA_CRS_MATRIX_TRACE_DUMP_MULTIPLY
00053 
00055 
00152 class Epetra_CrsMatrix: public Epetra_DistObject, public Epetra_CompObject, public Epetra_BLAS, public virtual Epetra_RowMatrix {
00153  public:
00154 
00156 
00157 
00158 
00169   Epetra_CrsMatrix(Epetra_DataAccess CV, const Epetra_Map& RowMap, const int* NumEntriesPerRow, bool StaticProfile = false);
00170   
00172 
00184   Epetra_CrsMatrix(Epetra_DataAccess CV, const Epetra_Map& RowMap, int NumEntriesPerRow, bool StaticProfile = false);
00185 
00187 
00200   Epetra_CrsMatrix(Epetra_DataAccess CV, const Epetra_Map& RowMap, const Epetra_Map& ColMap, const int* NumEntriesPerRow, bool StaticProfile = false);
00201   
00203 
00217   Epetra_CrsMatrix(Epetra_DataAccess CV, const Epetra_Map& RowMap, const Epetra_Map& ColMap, int NumEntriesPerRow, bool StaticProfile = false);
00218 
00220 
00226   Epetra_CrsMatrix(Epetra_DataAccess CV, const Epetra_CrsGraph& Graph);
00227   
00229   Epetra_CrsMatrix(const Epetra_CrsMatrix& Matrix);
00230   
00232   virtual ~Epetra_CrsMatrix();
00234   
00236 
00237 
00239   Epetra_CrsMatrix& operator=(const Epetra_CrsMatrix& src);
00240 
00242 
00249   int PutScalar(double ScalarConstant);
00250   
00252 
00259   int Scale(double ScalarConstant);
00260   
00262 
00274   int InsertGlobalValues(int GlobalRow, int NumEntries, double* Values, int* Indices);
00275 
00277 
00289   int ReplaceGlobalValues(int GlobalRow, int NumEntries, double* Values, int* Indices);
00290   
00292 
00304   int SumIntoGlobalValues(int GlobalRow, int NumEntries, double* Values, int* Indices);
00305 
00307 
00320   int InsertMyValues(int MyRow, int NumEntries, double* Values, int* Indices);
00321 
00323 
00335   int ReplaceMyValues(int MyRow, int NumEntries, double* Values, int* Indices);
00336 
00338 
00351   int SumIntoMyValues(int MyRow, int NumEntries, double* Values, int* Indices);
00352 
00354 
00367   int ReplaceDiagonalValues(const Epetra_Vector& Diagonal);
00368   
00370 
00372 
00373   
00374 
00376   /* This version of FillComplete assumes that the domain and range
00377      distributions are identical to the matrix row distributions.
00378      \return error code, 0 if successful. Returns a positive warning code of 3
00379         if the matrix is rectangular (meaning that the other overloading of
00380         FillComplete should have been called, with differen domain-map and
00381         range-map specified).
00382   */
00383   int FillComplete();
00384 
00386   /* This version of FillComplete requires the explicit specification of the domain
00387      and range distribution maps.  These maps are used for importing and exporting vector
00388      and multi-vector elements that are needed for distributed matrix computations.  For
00389      example, to compute y = Ax in parallel, we would specify the DomainMap as the distribution
00390      of the vector x and the RangeMap as the distribution of the vector y.
00391     \param DomainMap - (In) Map that describes the distribution of vector and multi-vectors in the
00392     matrix domain.
00393     \param RangeMap - (In) Map that describes the distribution of vector and multi-vectors in the
00394     matrix range.
00395 
00396     \return error code, 0 if successful. positive warning code of 2 if it is detected that the
00397     matrix-graph got out of sync since this matrix was constructed (for instance if
00398     graph.FillComplete() was called by another matrix that shares the graph)
00399 
00400     \post IndicesAreLocal()==true
00401     */
00402   int FillComplete(const Epetra_Map& DomainMap, const Epetra_Map& RangeMap);
00403     
00405 
00425   int OptimizeStorage();
00426 
00427   
00429   int MakeDataContiguous() {EPETRA_CHK_ERR(OptimizeStorage()); return(0);}
00431   
00433 
00434   
00436 
00446   int ExtractGlobalRowCopy(int GlobalRow, int Length, int& NumEntries, double* Values, int* Indices) const;
00447 
00449 
00460   int ExtractMyRowCopy(int MyRow, int Length, int& NumEntries, double* Values, int* Indices) const;
00461 
00463 
00471   int ExtractGlobalRowCopy(int GlobalRow, int Length, int& NumEntries, double* Values) const;
00472 
00474 
00482   int ExtractMyRowCopy(int MyRow, int Length, int& NumEntries, double* Values) const;
00483 
00485 
00492   int ExtractDiagonalCopy(Epetra_Vector& Diagonal) const;
00493   
00495 
00506   int ExtractGlobalRowView(int GlobalRow, int& NumEntries, double*& Values, int*& Indices) const;
00507   
00509 
00520   int ExtractMyRowView(int MyRow, int& NumEntries, double*& Values, int*& Indices) const;
00521   
00523 
00530   int ExtractGlobalRowView(int GlobalRow, int& NumEntries, double*& Values) const;
00531 
00533 
00540   int ExtractMyRowView(int MyRow, int& NumEntries, double*& Values) const;
00542   
00544 
00545   
00547 
00556   int Multiply(bool TransA, const Epetra_Vector& x, Epetra_Vector& y) const;
00557   int Multiply1(bool TransA, const Epetra_Vector& x, Epetra_Vector& y) const;
00558 
00559 
00561 
00570   int Multiply(bool TransA, const Epetra_MultiVector& X, Epetra_MultiVector& Y) const;
00571   int Multiply1(bool TransA, const Epetra_MultiVector& X, Epetra_MultiVector& Y) const;
00572 
00574 
00585   int Solve(bool Upper, bool Trans, bool UnitDiagonal, const Epetra_Vector& x, Epetra_Vector& y) const;
00586   
00588 
00599   int Solve(bool Upper, bool Trans, bool UnitDiagonal, const Epetra_MultiVector& X, Epetra_MultiVector& Y) const;
00600   
00602 
00618   int InvRowSums(Epetra_Vector& x) const;
00619 
00621 
00633   int InvRowMaxs(Epetra_Vector& x) const;
00634   
00636 
00644   int LeftScale(const Epetra_Vector& x);
00645   
00647 
00664   int InvColSums(Epetra_Vector& x) const;
00665 
00667 
00679   int InvColMaxs(Epetra_Vector& x) const;
00680 
00682 
00690   int RightScale(const Epetra_Vector& x);
00692   
00694 
00695   
00696   
00698   bool Filled() const {return(Graph_.Filled());}
00699   
00701   bool StorageOptimized() const {return(StorageOptimized_);}
00702   
00704   bool IndicesAreGlobal() const {return(Graph_.IndicesAreGlobal());}
00705   
00707   bool IndicesAreLocal() const {return(Graph_.IndicesAreLocal());}
00708   
00710   bool IndicesAreContiguous() const {return(Graph_.IndicesAreContiguous());}
00711   
00713   bool LowerTriangular() const {return(Graph_.LowerTriangular());}
00714   
00716   bool UpperTriangular() const {return(Graph_.UpperTriangular());}
00717   
00719   bool NoDiagonal() const {return(Graph_.NoDiagonal());}
00720   
00722   
00724 
00725   
00727   /* Returns the quantity \f$ \| A \|_\infty\f$ such that
00728      \f[\| A \|_\infty = \max_{1\lei\lem} \sum_{j=1}^n |a_{ij}| \f]
00729      \warning The NormInf() method will not properly calculate the infinity norm for a matrix that has entries that are
00730      replicated on multiple processors. */ 
00731   double NormInf() const;
00732   
00734   /* Returns the quantity \f$ \| A \|_1\f$ such that
00735      \f[\| A \|_1= \max_{1\lej\len} \sum_{i=1}^m |a_{ij}| \f].
00736      \warning The NormOne() method will not properly calculate the one norm for a matrix that has entries that are
00737      replicated on multiple processors.
00738   */ 
00739   double NormOne() const;
00740 
00742   /* Returns the quantity \f[ \| A \|_{Frobenius} = \sqrt{\sum_{i=1}^m \sum_{j=1}^n\|a_{ij}\|^2}\f]
00743      \warning the NormFrobenius() method will not properly calculate the frobenius norm for a matrix that
00744      has entries which are replicated on multiple processors. In that case, the returned
00745      norm will be larger than the true norm.
00746    */
00747   double NormFrobenius() const;
00748 
00750   /*
00751     Note that if maps are defined such that some nonzeros appear on
00752     multiple processors, then those nonzeros will be counted multiple times.
00753     If the user wishes to assemble a matrix from overlapping submatrices,
00754     they can use Epetra_FECrsMatrix.
00755   */
00756   int NumGlobalNonzeros() const {return(Graph_.NumGlobalNonzeros());}
00757   
00759   int NumGlobalRows() const {return(Graph_.NumGlobalRows());}
00760   
00762   int NumGlobalCols() const {return(Graph_.NumGlobalCols());}
00763   
00765   int NumGlobalDiagonals() const {return(Graph_.NumGlobalDiagonals());}
00766   
00768   int NumMyNonzeros() const {return(Graph_.NumMyNonzeros());}
00769   
00771   int NumMyRows() const {return(Graph_.NumMyRows());}
00772   
00774 
00778   int NumMyCols() const {return(Graph_.NumMyCols());}
00779   
00781 
00784   int NumMyDiagonals() const {return(Graph_.NumMyDiagonals());}
00785   
00787   int NumGlobalEntries(int Row) const {return(Graph_.NumGlobalIndices(Row));}
00788   
00790   int NumAllocatedGlobalEntries(int Row) const{return(Graph_.NumAllocatedGlobalIndices(Row));}
00791   
00793 
00796   int MaxNumEntries() const {return(Graph_.MaxNumIndices());}
00797 
00799 
00802   int GlobalMaxNumEntries() const {return(Graph_.GlobalMaxNumIndices());}
00803   
00805   int NumMyEntries(int Row) const {return(Graph_.NumMyIndices(Row));}
00806   
00808   int NumAllocatedMyEntries(int Row) const {return(Graph_.NumAllocatedMyIndices(Row));}
00809   
00811   int IndexBase() const {return(Graph_.IndexBase());}
00812   
00813   
00815   bool StaticGraph() {return(StaticGraph_);}
00816 
00818   const Epetra_CrsGraph& Graph() const {return(Graph_);}
00819   
00821   const Epetra_Map& RowMap() const {return((Epetra_Map &)Graph_.RowMap());}
00822 
00824 
00830   int ReplaceRowMap(const Epetra_BlockMap& newmap);
00831 
00833 
00837   bool HaveColMap() const {return(Graph_.HaveColMap());}
00838 
00840 
00846   int ReplaceColMap(const Epetra_BlockMap& newmap);
00847 
00848 
00850 
00857   const Epetra_Map& ColMap() const {return((Epetra_Map &) Graph_.ColMap());}
00858   
00860 
00863   const Epetra_Map& DomainMap() const {return((Epetra_Map &)Graph_.DomainMap());}
00864   
00866 
00869   const Epetra_Map& RangeMap() const  {return((Epetra_Map &)Graph_.RangeMap());}
00870   
00872   const Epetra_Import* Importer() const {return(Graph_.Importer());}
00873   
00875   const Epetra_Export* Exporter() const {return(Graph_.Exporter());}
00876   
00878   const Epetra_Comm& Comm() const {return(Epetra_DistObject::Comm());}
00880   
00882 
00883 
00884   int LRID( int GRID) const {return(Graph_.LRID(GRID));}
00885   
00887   int GRID( int LRID) const {return(Graph_.GRID(LRID));}
00888   
00890 
00893   int LCID( int GCID) const {return(Graph_.LCID(GCID));}
00894   
00896 
00899   int GCID( int LCID) const {return(Graph_.GCID(LCID));}
00900   
00902   bool MyGRID(int GRID) const {return(Graph_.MyGRID(GRID));}
00903   
00905   bool MyLRID(int LRID) const {return(Graph_.MyLRID(LRID));}
00906   
00908 
00911   bool MyGCID(int GCID) const {return(Graph_.MyGCID(GCID));}
00912    
00914 
00917   bool MyLCID(int LCID) const {return(Graph_.MyLCID(LCID));}
00918 
00920   bool MyGlobalRow(int GID) const {return(Graph_.MyGlobalRow(GID));}
00922   
00923   
00925 
00926 
00928   virtual void Print(ostream& os) const;
00930 
00932 
00933 
00935   const char* Label() const {return(Epetra_Object::Label());}
00936   
00938 
00946   int SetUseTranspose(bool UseTranspose) {UseTranspose_ = UseTranspose; return(0);}
00947 
00949 
00957   int Apply(const Epetra_MultiVector& X, Epetra_MultiVector& Y) const {
00958     return(Epetra_CrsMatrix::Multiply(Epetra_CrsMatrix::UseTranspose(), X, Y));}
00959   
00961 
00974   int ApplyInverse(const Epetra_MultiVector& X, Epetra_MultiVector& Y) const {
00975     return(Solve(UpperTriangular(), Epetra_CrsMatrix::UseTranspose(), NoDiagonal(), X, Y));}
00976 
00978   bool HasNormInf() const {return(true);}
00979   
00981   bool UseTranspose() const {return(UseTranspose_);}
00982   
00984   const Epetra_Map& OperatorDomainMap() const
00985         {
00986           if (UseTranspose()) return(RangeMap());
00987           else return(DomainMap());
00988         }
00989   
00991   const Epetra_Map& OperatorRangeMap() const
00992         {
00993           if (UseTranspose()) return(DomainMap());
00994           else return(RangeMap());
00995         }
00996 
00998 
00999 
01000 
01002 
01011   int NumMyRowEntries(int MyRow, int& NumEntries) const;
01012 
01014   const Epetra_Map& RowMatrixRowMap() const {return(RowMap());}
01015   
01017   const Epetra_Map& RowMatrixColMap() const {return(ColMap());}
01018   
01020   const Epetra_Import* RowMatrixImporter() const {return(Importer());}
01021   
01023   
01025 
01026   
01028 
01033   inline double* operator[] (int Loc) { 
01034     if (StorageOptimized()){ int * ind = Graph().IndexOffset(); return(All_Values_+ind[Loc]);}
01035     else return Values_[Loc];}
01036   inline double* operator[] (int Loc) const {
01037     if (StorageOptimized()){ int * ind = Graph().IndexOffset(); return(All_Values_+ind[Loc]);}
01038     else return Values_[Loc];}
01040   
01042 
01043 
01044 
01057   int ExtractCrsDataPointers(int *& IndexOffset, int *& Indices, double *& Values) const {
01058     if (StorageOptimized()) { 
01059       IndexOffset = Graph().IndexOffset();
01060       Indices = Graph().All_Indices();
01061       Values  = All_Values(); 
01062       return (0);
01063     } 
01064     else { IndexOffset = 0; Indices = 0; Values  = 0; return (-1);} }
01065   
01067   
01069 
01070   
01072   const Epetra_Map& ImportMap() const {return((Epetra_Map&) Graph_.ImportMap());}
01073 
01075   int TransformToLocal();
01076 
01078   int TransformToLocal(const Epetra_Map* DomainMap, const Epetra_Map* RangeMap);
01079 
01081 
01082 
01083  protected:
01084   bool Allocated() const {return(Allocated_);}
01085   int SetAllocated(bool Flag) {Allocated_ = Flag; return(0);}
01086   double** Values() const {
01087     if (StorageOptimized()) throw ReportError("This method: double** Values() cannot be called when StorageOptimized()==true", -1);
01088     else return(Values_);}
01089   double* All_Values() const {
01090     if (!StorageOptimized()) throw ReportError("This method: double* All_Values()cannot be called when StorageOptimized()==false", -1);
01091     else return(All_Values_);}
01092   double* Values(int LocalRow) const {
01093     if (StorageOptimized())
01094       if (Graph().StorageOptimized())
01095   return(All_Values_+Graph().IndexOffset()[LocalRow]);
01096       else throw ReportError("This method: double* Values()cannot be called when StorageOptimized()==true and Graph().StorageOptimized()==false", -1);
01097     else return(Values_[LocalRow]);}
01098   
01099   void InitializeDefaults();
01100   int Allocate();
01101 
01102   int InsertValues(int LocalRow, int NumEntries, double* Values, int* Indices);
01103 
01104   int InsertOffsetValues(int GlobalRow, int NumEntries, double *Values, int *Indices);
01105   int ReplaceOffsetValues(int GlobalRow, int NumEntries, double *Values, int *Indices);
01106   int SumIntoOffsetValues(int GlobalRow, int NumEntries, double *Values, int *Indices);
01107   void UpdateImportVector(int NumVectors) const;
01108   void UpdateExportVector(int NumVectors) const;
01109   void GeneralMV(double * x, double * y) const;
01110   void GeneralMTV(double * x, double * y) const;
01111   void GeneralMM(double ** X, int LDX, double ** Y, int LDY, int NumVectors) const;
01112   void GeneralMTM(double ** X, int LDX, double ** Y, int LDY, int NumVectors) const;
01113   void GeneralSV(bool Upper, bool Trans, bool UnitDiagonal, double * x, double * y) const;
01114   void GeneralSM(bool Upper, bool Trans, bool UnitDiagonal, double ** X, int LDX, double ** Y, int LDY, int NumVectors) const;
01115 
01116   void SetStaticGraph(bool Flag) {StaticGraph_ = Flag;}
01117 
01118   int CheckSizes(const Epetra_SrcDistObject& A);
01119 
01120   int CopyAndPermute(const Epetra_SrcDistObject& Source,
01121                      int NumSameIDs, 
01122                      int NumPermuteIDs,
01123                      int* PermuteToLIDs,
01124                      int* PermuteFromLIDs,
01125                      const Epetra_OffsetIndex * Indexor);
01126   int CopyAndPermuteCrsMatrix(const Epetra_CrsMatrix& A,
01127                               int NumSameIDs, 
01128                               int NumPermuteIDs,
01129                               int* PermuteToLIDs,
01130                               int* PermuteFromLIDs,
01131                               const Epetra_OffsetIndex * Indexor);
01132   int CopyAndPermuteRowMatrix(const Epetra_RowMatrix& A,
01133                               int NumSameIDs, 
01134                               int NumPermuteIDs,
01135                               int* PermuteToLIDs,
01136                               int* PermuteFromLIDs,
01137                               const Epetra_OffsetIndex * Indexor);
01138   
01139   int PackAndPrepare(const Epetra_SrcDistObject& Source,
01140                      int NumExportIDs,
01141                      int* ExportLIDs,
01142                      int& LenExports,
01143                      char*& Exports,
01144                      int& SizeOfPacket,
01145                      int* Sizes,
01146                      bool& VarSizes,
01147                      Epetra_Distributor& Distor);
01148 
01149   int UnpackAndCombine(const Epetra_SrcDistObject& Source, 
01150                        int NumImportIDs,
01151                        int* ImportLIDs, 
01152                        int LenImports,
01153                        char* Imports,
01154                        int& SizeOfPacket, 
01155                        Epetra_Distributor& Distor,
01156                        Epetra_CombineMode CombineMode,
01157                        const Epetra_OffsetIndex * Indexor);
01158 
01160   int SortEntries();
01161 
01163   bool Sorted() const {return(Graph_.Sorted());}
01164 
01166   int MergeRedundantEntries();
01167 
01169   bool NoRedundancies() const {return(Graph_.NoRedundancies());}
01170     
01171   void DeleteMemory();
01172 
01173   Epetra_CrsGraph Graph_;
01174   bool Allocated_;
01175   bool StaticGraph_;
01176   bool UseTranspose_;
01177   bool constructedWithFilledGraph_;
01178   bool matrixFillCompleteCalled_;
01179   bool StorageOptimized_;
01180 
01181   double** Values_;
01182   double* All_Values_;
01183   mutable double NormInf_;
01184   mutable double NormOne_;
01185   mutable double NormFrob_;
01186 
01187   int NumMyRows_;
01188   mutable Epetra_MultiVector* ImportVector_;
01189   mutable Epetra_MultiVector* ExportVector_;
01190 
01191   Epetra_DataAccess CV_;
01192 
01193   bool squareFillCompleteCalled_;
01194  private:
01195 
01196   // These are the pre-5.0 versions of solve.  They are still faster that generic 5.0 solves, so we keep them around
01197   int Solve1(bool Upper, bool Trans, bool UnitDiagonal, const Epetra_Vector& x, Epetra_Vector& y) const;
01198   int Solve1(bool Upper, bool Trans, bool UnitDiagonal, const Epetra_MultiVector& X, Epetra_MultiVector& Y) const;
01199 
01200 };
01201 #endif /* EPETRA_CRSMATRIX_H */

Generated on Thu Sep 18 12:37:57 2008 for Epetra Package Browser (Single Doxygen Collection) by doxygen 1.3.9.1