Tpetra Matrix/Vector Services Version of the Day
Tpetra_CrsGraph_decl.hpp
00001 //@HEADER
00002 // ************************************************************************
00003 // 
00004 //               Tpetra: Templated Linear Algebra Services Package 
00005 //                 Copyright (2008) Sandia Corporation
00006 // 
00007 // Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
00008 // license for use of this work by or on behalf of the U.S. Government.
00009 // 
00010 // This library is free software; you can redistribute it and/or modify
00011 // it under the terms of the GNU Lesser General Public License as
00012 // published by the Free Software Foundation; either version 2.1 of the
00013 // License, or (at your option) any later version.
00014 //  
00015 // This library is distributed in the hope that it will be useful, but
00016 // WITHOUT ANY WARRANTY; without even the implied warranty of
00017 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00018 // Lesser General Public License for more details.
00019 //  
00020 // You should have received a copy of the GNU Lesser General Public
00021 // License along with this library; if not, write to the Free Software
00022 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
00023 // USA
00024 // Questions? Contact Michael A. Heroux (maherou@sandia.gov) 
00025 // 
00026 // ************************************************************************
00027 //@HEADER
00028 
00029 #ifndef TPETRA_CRSGRAPH_DECL_HPP
00030 #define TPETRA_CRSGRAPH_DECL_HPP
00031 
00032 #include <Teuchos_Describable.hpp>
00033 #include <Teuchos_SerialDenseMatrix.hpp>
00034 #include <Teuchos_CompileTimeAssert.hpp>
00035 
00036 #include <Kokkos_DefaultNode.hpp>
00037 #include <Kokkos_DefaultKernels.hpp>
00038 #include <Kokkos_CrsGraph.hpp>
00039 #include <Kokkos_NodeHelpers.hpp>
00040 
00041 #include "Tpetra_ConfigDefs.hpp"
00042 #include "Tpetra_RowGraph.hpp"
00043 #include "Tpetra_DistObject.hpp"
00044 #include "Tpetra_Util.hpp"
00045 
00046 namespace Tpetra {
00047 
00048 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00049   // forward declaration
00050   template <class S, class LO, class GO, class N, class SpMatOps>
00051   class CrsMatrix;
00052 #endif
00053 
00054   struct RowInfo {
00055     size_t localRow;
00056     size_t allocSize;
00057     size_t numEntries;
00058     size_t offset1D;
00059   };
00060 
00061   enum ELocalGlobal {
00062     LocalIndices,
00063     GlobalIndices
00064   };
00065 
00067 
00092   template <class LocalOrdinal, 
00093             class GlobalOrdinal = LocalOrdinal, 
00094             class Node = Kokkos::DefaultNode::DefaultNodeType,
00095             class LocalMatOps = typename Kokkos::DefaultKernels<void,LocalOrdinal,Node>::SparseOps >
00096   class CrsGraph : public RowGraph<LocalOrdinal,GlobalOrdinal,Node>,
00097                    public DistObject<GlobalOrdinal,LocalOrdinal,GlobalOrdinal,Node> {
00098     template <class S, class LO, class GO, class N, class SpMatOps>
00099     friend class CrsMatrix;
00100 
00101     public: 
00102       typedef LocalOrdinal  local_ordinal_type;
00103       typedef GlobalOrdinal global_ordinal_type;
00104       typedef Node          node_type;
00105 
00107 
00108 
00110       CrsGraph(const RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &rowMap, size_t maxNumEntriesPerRow, ProfileType pftype = DynamicProfile);
00111 
00113       CrsGraph(const RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &rowMap, const ArrayRCP<const size_t> &NumEntriesPerRowToAlloc, ProfileType pftype = DynamicProfile);
00114 
00116 
00118       CrsGraph(const RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &rowMap, const RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &colMap, size_t maxNumEntriesPerRow, ProfileType pftype = DynamicProfile);
00119 
00121 
00123       CrsGraph(const RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &rowMap, const RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &colMap, const ArrayRCP<const size_t> &NumEntriesPerRowToAlloc, ProfileType pftype = DynamicProfile);
00124 
00125       // !Destructor.
00126       virtual ~CrsGraph();
00127 
00129 
00131 
00132 
00134 
00145       void insertGlobalIndices(GlobalOrdinal globalRow, const ArrayView<const GlobalOrdinal> &indices);
00146 
00148 
00159       void insertLocalIndices(LocalOrdinal localRow, const ArrayView<const LocalOrdinal> &indices);
00160 
00162 
00171       void removeLocalIndices(LocalOrdinal localRow);
00172 
00174 
00176 
00182 
00184       void globalAssemble();
00185 
00194       void resumeFill();
00195 
00207       void fillComplete(const RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &domainMap, const RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &rangeMap, OptimizeOption os = DoOptimizeStorage);
00208 
00222       void fillComplete(OptimizeOption os = DoOptimizeStorage);
00223 
00225 
00227 
00228 
00230       const RCP<const Comm<int> > & getComm() const;
00231 
00233       RCP<Node> getNode() const;
00234 
00236       const RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > & getRowMap() const;
00237 
00239       const RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > & getColMap() const;
00240 
00242       const RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > & getDomainMap() const;
00243 
00245       const RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > & getRangeMap() const;
00246 
00248       RCP<const Import<LocalOrdinal,GlobalOrdinal,Node> > getImporter() const;
00249 
00251       RCP<const Export<LocalOrdinal,GlobalOrdinal,Node> > getExporter() const;
00252 
00254 
00256       global_size_t getGlobalNumRows() const;
00257 
00259 
00262       global_size_t getGlobalNumCols() const;
00263 
00265       size_t getNodeNumRows() const;
00266 
00268 
00270       size_t getNodeNumCols() const;
00271 
00273       GlobalOrdinal getIndexBase() const;
00274 
00276 
00278       global_size_t getGlobalNumEntries() const;
00279 
00281       size_t getNodeNumEntries() const;
00282 
00284 
00285       size_t getNumEntriesInGlobalRow(GlobalOrdinal globalRow) const;
00286 
00288 
00289       size_t getNumEntriesInLocalRow(LocalOrdinal localRow) const;
00290 
00292 
00299       size_t getNodeAllocationSize() const;
00300 
00302 
00303       size_t getNumAllocatedEntriesInGlobalRow(GlobalOrdinal globalRow) const;
00304 
00306 
00307       size_t getNumAllocatedEntriesInLocalRow(LocalOrdinal localRow) const;
00308 
00310 
00312       global_size_t getGlobalNumDiags() const;
00313 
00315 
00317       size_t getNodeNumDiags() const;
00318 
00320 
00322       size_t getGlobalMaxNumRowEntries() const;
00323 
00325 
00327       size_t getNodeMaxNumRowEntries() const;
00328 
00330       bool hasColMap() const; 
00331 
00333 
00335       bool isLowerTriangular() const;
00336 
00338 
00340       bool isUpperTriangular() const;
00341 
00343       bool isLocallyIndexed() const;
00344 
00346       bool isGloballyIndexed() const;
00347 
00349       bool isFillComplete() const;
00350 
00352       bool isFillActive() const;
00353 
00355 
00358       bool isSorted() const;
00359 
00361 
00367       bool isStorageOptimized() const;
00368 
00370       ProfileType getProfileType() const;
00371 
00373 
00382       void getGlobalRowCopy(GlobalOrdinal GlobalRow, 
00383                             const ArrayView<GlobalOrdinal> &Indices, 
00384                             size_t &NumIndices
00385                             ) const;
00386 
00388 
00399       void getLocalRowCopy(LocalOrdinal LocalRow, 
00400                            const ArrayView<LocalOrdinal> &indices, 
00401                            size_t &NumIndices
00402                            ) const;
00403 
00405 
00413       void getGlobalRowView(GlobalOrdinal GlobalRow, ArrayView<const GlobalOrdinal> &Indices) const;
00414 
00416 
00424       void getLocalRowView(LocalOrdinal LocalRow, ArrayView<const LocalOrdinal> &indices) const;
00425 
00427 
00429 
00430 
00432       std::string description() const;
00433 
00435       void describe(Teuchos::FancyOStream &out, const Teuchos::EVerbosityLevel verbLevel=Teuchos::Describable::verbLevel_default) const;
00436 
00438 
00440 
00441 
00442       bool checkSizes(const DistObject<GlobalOrdinal,LocalOrdinal,GlobalOrdinal,Node>& source);
00443 
00444       void copyAndPermute(const DistObject<GlobalOrdinal,LocalOrdinal,GlobalOrdinal,Node> & source,
00445                           size_t numSameIDs,
00446                           const ArrayView<const LocalOrdinal> &permuteToLIDs,
00447                           const ArrayView<const LocalOrdinal> &permuteFromLIDs);
00448 
00449       void packAndPrepare(const DistObject<GlobalOrdinal,LocalOrdinal,GlobalOrdinal,Node> & source,
00450                           const ArrayView<const LocalOrdinal> &exportLIDs,
00451                           Array<GlobalOrdinal> &exports,
00452                           const ArrayView<size_t> & numPacketsPerLID,
00453                           size_t& constantNumPackets,
00454                           Distributor &distor);
00455 
00456       void unpackAndCombine(const ArrayView<const LocalOrdinal> &importLIDs,
00457                             const ArrayView<const GlobalOrdinal> &imports,
00458                             const ArrayView<size_t> &numPacketsPerLID,
00459                             size_t constantNumPackets,
00460                             Distributor &distor,
00461                             CombineMode CM);
00463 
00465 
00466 
00468 
00471       ArrayRCP<const size_t>       getNodeRowBegs() const;
00472 
00474 
00477       ArrayRCP<const LocalOrdinal> getNodePackedIndices() const;
00478 
00480 
00482 
00483 
00492       TPETRA_DEPRECATED void optimizeStorage();
00493 
00495       TPETRA_DEPRECATED ArrayRCP<const GlobalOrdinal> getGlobalRowView(GlobalOrdinal GlobalRow) const;
00496 
00498       TPETRA_DEPRECATED ArrayRCP<const LocalOrdinal> getLocalRowView(LocalOrdinal LocalRow) const;
00499 
00501 
00502     private:
00503       // copy constructor disabled
00504       CrsGraph(const CrsGraph<LocalOrdinal,GlobalOrdinal,Node> &Source);
00505       // operator= disabled
00506       CrsGraph<LocalOrdinal,GlobalOrdinal,Node> & operator=(const CrsGraph<LocalOrdinal,GlobalOrdinal,Node> &rhs);
00507     protected:
00508       // these structs are conveniences, to cut down on the number of argument to some of the methods below.
00509       struct SLocalGlobalViews {
00510         ArrayView<const GlobalOrdinal> ginds;
00511         ArrayView<const LocalOrdinal>  linds;
00512       };
00513       struct SLocalGlobalNCViews {
00514         ArrayView<GlobalOrdinal>       ginds;
00515         ArrayView<LocalOrdinal>        linds;
00516       };
00517       // Allocation
00518       bool                                     indicesAreAllocated() const;
00519       void                                     allocateIndices(ELocalGlobal lg);
00520       template <class T>                  void allocateValues(ArrayRCP<T> &values1D, ArrayRCP<ArrayRCP<T> > &values2D) const;
00521       template <ELocalGlobal lg>          RowInfo updateAlloc(RowInfo rowinfo, size_t allocSize);
00522       template <ELocalGlobal lg, class T> RowInfo updateAllocAndValues(RowInfo rowinfo, size_t allocSize, ArrayRCP<T> &rowVals);
00523       // Local versus global indices
00524       void computeIndexState();
00525       void makeColMap();
00526       void makeIndicesLocal();
00527       void makeImportExport();
00528       // insert/suminto/replace
00529       template <ELocalGlobal lg>                           size_t                filterIndices         (const SLocalGlobalNCViews &inds) const;
00530       template <ELocalGlobal lg, class T>                  size_t                filterIndicesAndValues(const SLocalGlobalNCViews &inds, const ArrayView<T> &vals) const;
00531       template <ELocalGlobal lg, ELocalGlobal I>                           size_t       insertIndices         (RowInfo rowInfo, const SLocalGlobalViews &newInds);
00532       template <ELocalGlobal lg, ELocalGlobal I, class IterO, class IterN> void         insertIndicesAndValues(RowInfo rowInfo, const SLocalGlobalViews &newInds, IterO rowVals, IterN newVals);
00533       template <ELocalGlobal lg, class IterO, class IterN, class BinaryFunction> void   transformValues(RowInfo rowInfo, const SLocalGlobalViews &inds,    IterO rowVals, IterN newVals, BinaryFunction f) const;
00534       // Sorting and merging
00535       bool                       isMerged() const;
00536       void                       setSorted(bool sorted);
00537       void                       setMerged(bool merged);
00538       void                       sortAllIndices();
00539       void                       sortRowIndices(RowInfo rowinfo);
00540       template <class Scalar> void sortRowIndicesAndValues(RowInfo rowinfo, ArrayView<Scalar> values);
00541       void                                             mergeAllIndices();
00542       void                                             mergeRowIndices(RowInfo rowinfo);
00543       template <class Iter, class BinaryFunction> void mergeRowIndicesAndValues(RowInfo rowinfo, Iter rowValueIter, BinaryFunction f);
00544       // 
00545       void setDomainRangeMaps(const RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &domainMap, const RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &rangeMap);
00546       void staticAssertions() const;
00547       // global consts
00548       void clearGlobalConstants();
00549       void computeGlobalConstants();
00550       // graph data accessors
00551       RowInfo                         getRowInfo(size_t myRow) const;
00552       ArrayView<const LocalOrdinal>   getLocalView(RowInfo rowinfo) const;
00553       ArrayView<LocalOrdinal>         getLocalViewNonConst(RowInfo rowinfo);
00554       ArrayView<const GlobalOrdinal>  getGlobalView(RowInfo rowinfo) const;
00555       ArrayView<GlobalOrdinal>        getGlobalViewNonConst(RowInfo rowinfo);
00556       size_t                          findLocalIndex(RowInfo rowinfo, LocalOrdinal ind) const;
00557       size_t                          findGlobalIndex(RowInfo rowinfo, GlobalOrdinal ind) const;
00558       // local Kokkos objects
00559       void pushToLocalGraph();
00560       void pullFromLocalGraph();
00561       void fillLocalGraph(OptimizeOption os);
00562       const Kokkos::CrsGraph<LocalOrdinal,Node,LocalMatOps> & getLocalGraph() const;
00563       Kokkos::CrsGraph<LocalOrdinal,Node,LocalMatOps>       & getLocalGraphNonConst();
00564       // debugging
00565       void checkInternalState() const;
00566 
00567       // Tpetra support objects
00568       RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > rowMap_, colMap_, rangeMap_, domainMap_;
00569       RCP<Import<LocalOrdinal,GlobalOrdinal,Node> > importer_;
00570       RCP<Export<LocalOrdinal,GlobalOrdinal,Node> > exporter_;
00571 
00572       // local data, stored in a Kokkos::CrsGraph. only initialized after fillComplete()
00573       Kokkos::CrsGraph<LocalOrdinal,Node,LocalMatOps> lclGraph_;
00574 
00575       // Local and Global Counts
00576       // nodeNumEntries_ and nodeNumAllocated_ are required to be always consistent
00577       // nodeMaxNumEntries_, nodeNumDiags_ and the global quantities are computed during fillComplete() and only valid when isFillComplete()
00578       global_size_t globalNumEntries_, globalNumDiags_, globalMaxNumRowEntries_;
00579       size_t          nodeNumEntries_,   nodeNumDiags_,   nodeMaxNumRowEntries_, nodeNumAllocated_;
00580 
00581       // allocate static or dynamic?
00582       ProfileType pftype_;
00583       // requested allocation sizes; we have to preserve these, because we perform late-allocation
00584       // number of non-zeros to allocate per row; set to null after they are allocated.
00585       ArrayRCP<const size_t> numAllocPerRow_;
00586       // number of non-zeros to allocate for all row; either this or numAllocPerRow_ is used, but not both.
00587       size_t numAllocForAllRows_;
00588 
00589       // graph indices. before allocation, all are null. 
00590       // after allocation, except during makeIndicesLocal(), one of local or global is null.
00591       // we will never have 1D and 2D structures being non-null
00592       // this is host memory
00593       // 1D == StaticAllocation, 2D == DynamicAllocation
00595       //
00596       // 1D/Static structures
00597       //
00600       ArrayRCP< LocalOrdinal>                     lclInds1D_;
00602       ArrayRCP<GlobalOrdinal>                     gblInds1D_;
00603       // offset to the beg and end entries of each row. only used for 1D (Static) allocation.
00604       // i.e., indices for row R are lclInds1D_[i] for i in [b,e) where b = rowBegs_[R] and e = rowEnds_[R]
00605       // for a packed (optimized) allocation, we will typically have &rowBegs_[R]+1 == &rowEnds_[R]
00606       // these are null for 2D (Dynamic) allocations
00607       // the allocation size is computed by looking at the difference between rowBegs_[r+1] and rowBegs_[r]
00608       // rowBegs_ therefore has length N+1, while rowEnds_ has length N
00609       ArrayRCP<size_t> rowBegs_, rowEnds_;
00611       //
00612       // 2D/Dynamic structures. 
00613       //
00616       ArrayRCP<ArrayRCP< LocalOrdinal> > lclInds2D_;
00618       ArrayRCP<ArrayRCP<GlobalOrdinal> > gblInds2D_;
00620       ArrayRCP<size_t>       numEntriesPerRow_;
00621 
00622       // TODO: these might be useful in the future
00623       // ArrayRCP< typedef ArrayRCP<const GlobalOrdinal>::iterator > gRowPtrs_;
00624       // ArrayRCP< typedef ArrayRCP<GlobalOrdinal>::iterator > gRowPtrsNC_;
00625       // ArrayRCP< typedef ArrayRCP<const LocalOrdinal>::iterator > lRowPtrs_;
00626       // ArrayRCP< typedef ArrayRCP<LocalOrdinal>::iterator > lRowPtrsNC_;
00627 
00628       bool indicesAreAllocated_,
00629            indicesAreLocal_,
00630            indicesAreGlobal_,
00631            fillComplete_, 
00632            lowerTriangular_,
00633            upperTriangular_,
00634            indicesAreSorted_,
00635            noRedundancies_,
00636            haveGlobalConstants_;
00637 
00638       // non-local data
00639       std::map<GlobalOrdinal, std::deque<GlobalOrdinal> > nonlocals_;
00640 
00641   }; // class CrsGraph
00642 
00643 } // namespace Tpetra
00644 
00645 #endif
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines