Tpetra Matrix/Vector Services Version of the Day
Tpetra_Map_decl.hpp
Go to the documentation of this file.
00001 // @HEADER
00002 // ***********************************************************************
00003 //
00004 //          Tpetra: Templated Linear Algebra Services Package
00005 //                 Copyright (2008) Sandia Corporation
00006 //
00007 // Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
00008 // the U.S. Government retains certain rights in this software.
00009 //
00010 // Redistribution and use in source and binary forms, with or without
00011 // modification, are permitted provided that the following conditions are
00012 // met:
00013 //
00014 // 1. Redistributions of source code must retain the above copyright
00015 // notice, this list of conditions and the following disclaimer.
00016 //
00017 // 2. Redistributions in binary form must reproduce the above copyright
00018 // notice, this list of conditions and the following disclaimer in the
00019 // documentation and/or other materials provided with the distribution.
00020 //
00021 // 3. Neither the name of the Corporation nor the names of the
00022 // contributors may be used to endorse or promote products derived from
00023 // this software without specific prior written permission.
00024 //
00025 // THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
00026 // EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00027 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
00028 // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
00029 // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
00030 // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
00031 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
00032 // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
00033 // LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00034 // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00035 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00036 //
00037 // Questions? Contact Michael A. Heroux (maherou@sandia.gov)
00038 //
00039 // ************************************************************************
00040 // @HEADER
00041 
00042 #ifndef TPETRA_MAP_DECL_HPP
00043 #define TPETRA_MAP_DECL_HPP
00044 
00045 #include <Kokkos_DefaultNode.hpp>
00046 #include <Teuchos_Describable.hpp>
00047 
00048 // enums and defines
00049 #include "Tpetra_ConfigDefs.hpp"
00050 
00051 // mfh 27 Apr 2013: If HAVE_TPETRA_FIXED_HASH_TABLE is defined (which
00052 // it is by default), then Map will used the fixed-structure hash
00053 // table variant for global-to-local index lookups.  Otherwise, it
00054 // will use the dynamic-structure hash table variant.
00055 //
00056 // mfh 23 Mar 2014: I've removed all code in Map that uses the
00057 // dynamic-structure hash table variant, since it has not been used
00058 // for at least a year.  However, I am retaining the #define, in case
00059 // downstream code depends on it.
00060 
00061 #ifndef HAVE_TPETRA_FIXED_HASH_TABLE
00062 #  define HAVE_TPETRA_FIXED_HASH_TABLE 1
00063 #endif // HAVE_TPETRA_FIXED_HASH_TABLE
00064 
00068 namespace Tpetra {
00069 
00070 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00071   // Forward declaration of Directory.
00072   template <class LO, class GO, class N> class Directory;
00073 #endif // DOXYGEN_SHOULD_SKIP_THIS
00074 
00075   namespace Details {
00076 
00077 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00078     // Forward declaration of TieBreak
00079     template <class LO, class GO> class TieBreak;
00080 
00081     template<class GlobalOrdinal, class LocalOrdinal>
00082     class FixedHashTable;
00083 #endif // DOXYGEN_SHOULD_SKIP_THIS
00084 
00087     template<class OutMapType, class InMapType>
00088     struct MapCloner {
00089       typedef typename OutMapType::node_type out_node_type;
00090       typedef typename InMapType::node_type in_node_type;
00091 
00092       static Teuchos::RCP<const OutMapType>
00093       clone (const InMapType& mapIn,
00094              const Teuchos::RCP<out_node_type>& node2);
00095     };
00096   } // namespace Details
00097 
00232   template <class LocalOrdinal,
00233             class GlobalOrdinal = LocalOrdinal,
00234             class Node = KokkosClassic::DefaultNode::DefaultNodeType>
00235   class Map : public Teuchos::Describable {
00236   public:
00238 
00239 
00241     typedef LocalOrdinal local_ordinal_type;
00243     typedef GlobalOrdinal global_ordinal_type;
00245     typedef Node node_type;
00246 
00248 
00249 
00250 
00292     Map (global_size_t numGlobalElements,
00293          GlobalOrdinal indexBase,
00294          const Teuchos::RCP<const Teuchos::Comm<int> > &comm,
00295          LocalGlobal lg=GloballyDistributed,
00296          const Teuchos::RCP<Node> &node = KokkosClassic::Details::getNode<Node>());
00297 
00337     Map (global_size_t numGlobalElements,
00338          size_t numLocalElements,
00339          GlobalOrdinal indexBase,
00340          const Teuchos::RCP<const Teuchos::Comm<int> > &comm,
00341          const Teuchos::RCP<Node> &node = KokkosClassic::Details::getNode<Node>());
00342 
00377     Map (global_size_t numGlobalElements,
00378          const Teuchos::ArrayView<const GlobalOrdinal> &elementList,
00379          GlobalOrdinal indexBase,
00380          const Teuchos::RCP<const Teuchos::Comm<int> > &comm,
00381          const Teuchos::RCP<Node> &node = KokkosClassic::Details::getNode<Node>());
00382 
00383 
00394     Map ();
00395 
00397     ~Map ();
00398 
00400 
00401 
00402 
00407     bool isOneToOne () const;
00408 
00410     inline global_size_t getGlobalNumElements() const { return numGlobalElements_; }
00411 
00413     inline size_t getNodeNumElements() const { return numLocalElements_; }
00414 
00416     inline GlobalOrdinal getIndexBase() const { return indexBase_; }
00417 
00419     inline LocalOrdinal getMinLocalIndex() const {
00420       return Teuchos::OrdinalTraits<LocalOrdinal>::zero();
00421     }
00422 
00428     inline LocalOrdinal getMaxLocalIndex() const {
00429       if (getNodeNumElements () == 0) {
00430         return Teuchos::OrdinalTraits<LocalOrdinal>::invalid ();
00431       }
00432       else { // Local indices are always zero-based.
00433         return Teuchos::as<LocalOrdinal> (getNodeNumElements () - 1);
00434       }
00435     }
00436 
00438     inline GlobalOrdinal getMinGlobalIndex() const { return minMyGID_; }
00439 
00441     inline GlobalOrdinal getMaxGlobalIndex() const { return maxMyGID_; }
00442 
00444     inline GlobalOrdinal getMinAllGlobalIndex() const { return minAllGID_; }
00445 
00447     inline GlobalOrdinal getMaxAllGlobalIndex() const { return maxAllGID_; }
00448 
00453     LocalOrdinal getLocalElement (GlobalOrdinal globalIndex) const;
00454 
00459     GlobalOrdinal getGlobalElement (LocalOrdinal localIndex) const;
00460 
00490     LookupStatus
00491     getRemoteIndexList (const Teuchos::ArrayView<const GlobalOrdinal>& GIDList,
00492                         const Teuchos::ArrayView<                int>& nodeIDList,
00493                         const Teuchos::ArrayView<       LocalOrdinal>& LIDList) const;
00494 
00518     LookupStatus
00519     getRemoteIndexList (const Teuchos::ArrayView<const GlobalOrdinal> & GIDList,
00520                         const Teuchos::ArrayView<                int> & nodeIDList) const;
00521 
00528     Teuchos::ArrayView<const GlobalOrdinal> getNodeElementList() const;
00529 
00531 
00532 
00533 
00535     bool isNodeLocalElement (LocalOrdinal localIndex) const;
00536 
00538     bool isNodeGlobalElement (GlobalOrdinal globalIndex) const;
00539 
00546     bool isUniform () const;
00547 
00559     bool isContiguous () const;
00560 
00580     bool isDistributed () const;
00581 
00606     bool isCompatible (const Map<LocalOrdinal,GlobalOrdinal,Node> &map) const;
00607 
00638     bool isSameAs (const Map<LocalOrdinal,GlobalOrdinal,Node> &map) const;
00639 
00641 
00642 
00643 
00645     Teuchos::RCP<const Teuchos::Comm<int> > getComm () const;
00646 
00648     Teuchos::RCP<Node> getNode () const;
00649 
00651 
00652 
00653 
00655     std::string description() const;
00656 
00658     void
00659     describe (Teuchos::FancyOStream &out,
00660               const Teuchos::EVerbosityLevel verbLevel=Teuchos::Describable::verbLevel_default) const;
00661 
00663 
00664 
00665 
00667     template <class NodeOut>
00668     RCP<const Map<LocalOrdinal, GlobalOrdinal, NodeOut> > clone (const RCP<NodeOut>& nodeOut) const;
00669 
00717     RCP<const Map<LocalOrdinal, GlobalOrdinal, Node> >
00718     removeEmptyProcesses () const;
00719 
00747     RCP<const Map<LocalOrdinal, GlobalOrdinal, Node> >
00748     replaceCommWithSubset (const Teuchos::RCP<const Teuchos::Comm<int> >& newComm) const;
00750 
00751   protected:
00752     // This lets other specializations of Map access all of this
00753     // specialization's internal methods and data, so that we can
00754     // implement clone() without exposing the details of Map to users.
00755     template <class LO, class GO, class N> friend class Map;
00756 
00757   private:
00758     template<class OutMapType, class InMapType>
00759     friend struct Details::MapCloner;
00760 
00768     void setupDirectory () const;
00769 
00784     bool checkIsDist() const;
00785 
00790     bool locallySameAs (const Map<LocalOrdinal, GlobalOrdinal, node_type>& map) const;
00791 
00793     Teuchos::RCP<const Teuchos::Comm<int> > comm_;
00794 
00796     Teuchos::RCP<Node> node_;
00797 
00799     GlobalOrdinal indexBase_;
00800 
00802     global_size_t numGlobalElements_;
00803 
00805     size_t numLocalElements_;
00806 
00808     GlobalOrdinal minMyGID_;
00809 
00811     GlobalOrdinal maxMyGID_;
00812 
00814     GlobalOrdinal minAllGID_;
00815 
00817     GlobalOrdinal maxAllGID_;
00818 
00825     GlobalOrdinal firstContiguousGID_;
00826 
00840     GlobalOrdinal lastContiguousGID_;
00841 
00847     bool uniform_;
00848 
00850     bool contiguous_;
00851 
00858     bool distributed_;
00859 
00876     mutable Teuchos::ArrayRCP<GlobalOrdinal> lgMap_;
00877 
00879     typedef Details::FixedHashTable<GlobalOrdinal, LocalOrdinal> global_to_local_table_type;
00880 
00893     RCP<global_to_local_table_type> glMap_;
00894 
00922     mutable Teuchos::RCP<Directory<LocalOrdinal,GlobalOrdinal,Node> > directory_;
00923 
00924   }; // Map class
00925 
00940   template <class LocalOrdinal, class GlobalOrdinal>
00941   Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal> >
00942   createLocalMap (size_t numElements, const Teuchos::RCP<const Teuchos::Comm<int> >& comm);
00943 
00960   template <class LocalOrdinal, class GlobalOrdinal, class Node>
00961   Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> >
00962   createLocalMapWithNode (size_t numElements,
00963                           const Teuchos::RCP<const Teuchos::Comm<int> >& comm,
00964                           const Teuchos::RCP<Node>& node = KokkosClassic::Details::getNode<Node> ());
00965 
00974   template <class LocalOrdinal, class GlobalOrdinal>
00975   Teuchos::RCP< const Map<LocalOrdinal,GlobalOrdinal> >
00976   createUniformContigMap(global_size_t numElements, const Teuchos::RCP< const Teuchos::Comm< int > > &comm);
00977 
00984   template <class LocalOrdinal, class GlobalOrdinal, class Node>
00985   Teuchos::RCP< const Map<LocalOrdinal,GlobalOrdinal,Node> >
00986   createUniformContigMapWithNode(global_size_t numElements,
00987                                  const Teuchos::RCP< const Teuchos::Comm< int > > &comm,
00988                                  const Teuchos::RCP< Node > &node = KokkosClassic::Details::getNode<Node>());
00989 
00998   template <class LocalOrdinal, class GlobalOrdinal>
00999   Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,KokkosClassic::DefaultNode::DefaultNodeType> >
01000   createContigMap (global_size_t numElements,
01001                    size_t localNumElements,
01002                    const Teuchos::RCP<const Teuchos::Comm<int> > &comm);
01003 
01010   template <class LocalOrdinal, class GlobalOrdinal, class Node>
01011   Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> >
01012   createContigMapWithNode (global_size_t numElements,
01013                            size_t localNumElements,
01014                            const Teuchos::RCP<const Teuchos::Comm<int> > &comm,
01015                            const Teuchos::RCP<Node> &node);
01016 
01025   template <class LocalOrdinal, class GlobalOrdinal>
01026   Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,KokkosClassic::DefaultNode::DefaultNodeType> >
01027   createNonContigMap (const ArrayView<const GlobalOrdinal> &elementList,
01028                       const RCP<const Teuchos::Comm<int> > &comm);
01029 
01036   template <class LocalOrdinal, class GlobalOrdinal, class Node>
01037   Teuchos::RCP< const Map<LocalOrdinal,GlobalOrdinal,Node> >
01038   createNonContigMapWithNode (const ArrayView<const GlobalOrdinal> &elementList,
01039                               const RCP<const Teuchos::Comm<int> > &comm,
01040                               const RCP<Node> &node);
01041 
01048   template <class LocalOrdinal, class GlobalOrdinal, class Node>
01049   Teuchos::RCP< const Map<LocalOrdinal,GlobalOrdinal,Node> >
01050   createWeightedContigMapWithNode (int thisNodeWeight,
01051                                    global_size_t numElements,
01052                                    const Teuchos::RCP<const Teuchos::Comm<int> > &comm,
01053                                    const Teuchos::RCP<Node> &node);
01054 
01061   template<class LocalOrdinal, class GlobalOrdinal, class Node>
01062   Teuchos::RCP< const Map<LocalOrdinal,GlobalOrdinal,Node> >
01063   createOneToOne (const Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &M);
01064 
01072   template<class LocalOrdinal, class GlobalOrdinal, class Node>
01073   Teuchos::RCP< const Map<LocalOrdinal,GlobalOrdinal,Node> >
01074   createOneToOne(const Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &M,
01075                  const Tpetra::Details::TieBreak<LocalOrdinal,GlobalOrdinal> & tie_break);
01076 
01077 } // Tpetra namespace
01078 
01079 #include "Tpetra_Directory_decl.hpp"
01080 
01081 namespace Tpetra {
01082   namespace Details {
01083 
01084     template<class OutMapType, class InMapType>
01085     Teuchos::RCP<const OutMapType>
01086     MapCloner<OutMapType, InMapType>::
01087     clone (const InMapType& mapIn,
01088            const Teuchos::RCP<out_node_type>& nodeOut)
01089     {
01090       Teuchos::RCP<OutMapType> mapOut = Teuchos::rcp (new OutMapType ());
01091       // Fill the new Map with shallow copies of all of the original
01092       // Map's data.  This is safe because Map is immutable, so
01093       // users can't change the original Map.
01094       mapOut->comm_              = mapIn.comm_;
01095       mapOut->indexBase_         = mapIn.indexBase_;
01096       mapOut->numGlobalElements_ = mapIn.numGlobalElements_;
01097       mapOut->numLocalElements_  = mapIn.numLocalElements_;
01098       mapOut->minMyGID_          = mapIn.minMyGID_;
01099       mapOut->maxMyGID_          = mapIn.maxMyGID_;
01100       mapOut->minAllGID_         = mapIn.minAllGID_;
01101       mapOut->maxAllGID_         = mapIn.maxAllGID_;
01102       mapOut->firstContiguousGID_= mapIn.firstContiguousGID_;
01103       mapOut->lastContiguousGID_ = mapIn.lastContiguousGID_;
01104       mapOut->uniform_           = mapIn.uniform_;
01105       mapOut->contiguous_        = mapIn.contiguous_;
01106       mapOut->distributed_       = mapIn.distributed_;
01107       mapOut->lgMap_             = mapIn.lgMap_;
01108       mapOut->glMap_             = mapIn.glMap_;
01109       // New Map gets the new Node instance.
01110       mapOut->node_              = nodeOut;
01111       // mfh 02 Apr 2013: While Map could just wait to create the
01112       // Directory on demand in getRemoteIndexList, we have a
01113       // Directory here that we can clone inexpensively, so there is
01114       // no harm in creating it here.
01115       // if (! mapIn.directory_.is_null ()) {
01116       //   mapOut->directory_ =
01117       //     mapIn.directory_->template clone<out_node_type> (mapIn);
01118       // }
01119       return mapOut;
01120     }
01121   } // namespace Details
01122 
01123 
01124   template <class LocalOrdinal, class GlobalOrdinal, class Node>
01125   template <class NodeOut>
01126   RCP<const Map<LocalOrdinal, GlobalOrdinal, NodeOut> >
01127   Map<LocalOrdinal,GlobalOrdinal,Node>::clone (const RCP<NodeOut> &nodeOut) const
01128   {
01129     typedef Map<LocalOrdinal, GlobalOrdinal, Node> in_map_type;
01130     typedef Map<LocalOrdinal, GlobalOrdinal, NodeOut> out_map_type;
01131     return Details::MapCloner<out_map_type, in_map_type>::clone (*this, nodeOut);
01132   }
01133 
01134 } // namespace Tpetra
01135 
01138 template <class LocalOrdinal, class GlobalOrdinal, class Node>
01139 bool operator== (const Tpetra::Map<LocalOrdinal,GlobalOrdinal,Node> &map1,
01140                  const Tpetra::Map<LocalOrdinal,GlobalOrdinal,Node> &map2)
01141 { return map1.isSameAs (map2); }
01142 
01145 template <class LocalOrdinal, class GlobalOrdinal, class Node>
01146 bool operator!= (const Tpetra::Map<LocalOrdinal,GlobalOrdinal,Node> &map1,
01147                  const Tpetra::Map<LocalOrdinal,GlobalOrdinal,Node> &map2)
01148 { return ! map1.isSameAs (map2); }
01149 
01150 
01151 #if defined(TPETRA_USE_KOKKOS_REFACTOR_MAP)
01152 // Include KokkosRefactor partial specialization if enabled
01153 #  if defined(TPETRA_HAVE_KOKKOS_REFACTOR)
01154 #    include "Tpetra_KokkosRefactor_Map_decl.hpp"
01155 #  endif // defined(TPETRA_HAVE_KOKKOS_REFACTOR)
01156 #endif // defined(TPETRA_USE_KOKKOS_REFACTOR_MAP)
01157 
01158 
01159 #endif // TPETRA_MAP_DECL_HPP
01160 
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines