Tpetra_Map_decl.hpp

Go to the documentation of this file.

// @HEADER
// ***********************************************************************
//
//          Tpetra: Templated Linear Algebra Services Package
//                 Copyright (2008) Sandia Corporation
//
// Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
// the U.S. Government retains certain rights in this software.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
// 1. Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
//
// 2. Redistributions in binary form must reproduce the above copyright
// notice, this list of conditions and the following disclaimer in the
// documentation and/or other materials provided with the distribution.
//
// 3. Neither the name of the Corporation nor the names of the
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
// EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
// PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
// LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
// Questions? Contact Michael A. Heroux (maherou@sandia.gov)
//
// ************************************************************************
// @HEADER

#ifndef TPETRA_MAP_DECL_HPP
#define TPETRA_MAP_DECL_HPP


#include "Tpetra_ConfigDefs.hpp"
#include "Tpetra_Details_LocalMap.hpp"
#include "Kokkos_DefaultNode.hpp"
#include "Kokkos_DualView.hpp"
#include "Teuchos_Describable.hpp"

namespace Tpetra {

#ifndef DOXYGEN_SHOULD_SKIP_THIS
  // Forward declaration of Directory.
  template <class LO, class GO, class N> class Directory;
#endif // DOXYGEN_SHOULD_SKIP_THIS

  namespace Details {

#ifndef DOXYGEN_SHOULD_SKIP_THIS
    // Forward declaration of TieBreak
    template <class LO, class GO> class TieBreak;
#endif // DOXYGEN_SHOULD_SKIP_THIS

    template<class OutMapType, class InMapType>
    struct MapCloner {
      typedef typename OutMapType::node_type out_node_type;
      typedef typename InMapType::node_type in_node_type;

      static OutMapType
      clone (const InMapType& mapIn,
             const Teuchos::RCP<out_node_type>& node2);
    };

  } // namespace Details

  template<class Node>
  Teuchos::RCP<Node> defaultArgNode() {
    // Workaround function for a deferred visual studio bug
    // http://connect.microsoft.com/VisualStudio/feedback/details/719847/erroneous-error-c2783-could-not-deduce-template-argument
    // Use this function for default arguments rather than calling
    // what is the return value below.  Also helps in reducing
    // duplication in various constructors.
    return KokkosClassic::Details::getNode<Node> ();
  }

  template <class LocalOrdinal = ::Tpetra::Details::DefaultTypes::local_ordinal_type,
            class GlobalOrdinal = ::Tpetra::Details::DefaultTypes::global_ordinal_type,
            class Node = ::Tpetra::Details::DefaultTypes::node_type>
  class Map : public Teuchos::Describable {
  public:


    typedef LocalOrdinal local_ordinal_type;
    typedef GlobalOrdinal global_ordinal_type;
    typedef Node node_type;

    typedef typename Node::execution_space execution_space;
    typedef typename Node::memory_space memory_space;

    typedef typename Node::device_type device_type;

    typedef Details::LocalMap<LocalOrdinal, GlobalOrdinal, device_type>
      local_map_type;



    Map (global_size_t numGlobalElements,
         GlobalOrdinal indexBase,
         const Teuchos::RCP<const Teuchos::Comm<int> > &comm,
         LocalGlobal lg=GloballyDistributed,
         const Teuchos::RCP<Node> &node = defaultArgNode<Node>());

    Map (global_size_t numGlobalElements,
         size_t numLocalElements,
         GlobalOrdinal indexBase,
         const Teuchos::RCP<const Teuchos::Comm<int> > &comm,
         const Teuchos::RCP<Node> &node = defaultArgNode<Node>());

    Map (const global_size_t numGlobalElements,
         const Kokkos::View<const GlobalOrdinal*, device_type>& indexList,
         const GlobalOrdinal indexBase,
         const Teuchos::RCP<const Teuchos::Comm<int> >& comm);

    Map (const global_size_t numGlobalElements,
         const GlobalOrdinal indexList[],
         const LocalOrdinal indexListSize,
         const GlobalOrdinal indexBase,
         const Teuchos::RCP<const Teuchos::Comm<int> >& comm);

    Map (const global_size_t numGlobalElements,
         const Teuchos::ArrayView<const GlobalOrdinal>& indexList,
         const GlobalOrdinal indexBase,
         const Teuchos::RCP<const Teuchos::Comm<int> >& comm,
         const Teuchos::RCP<Node>& node = defaultArgNode<Node>());

    Map ();

    ~Map ();



    bool isOneToOne () const;

    global_size_t getGlobalNumElements () const {
      return numGlobalElements_;
    }

    size_t getNodeNumElements () const {
      return numLocalElements_;
    }

    GlobalOrdinal getIndexBase () const {
      return indexBase_;
    }

    LocalOrdinal getMinLocalIndex () const {
      return static_cast<LocalOrdinal> (0);
    }

    LocalOrdinal getMaxLocalIndex () const {
      if (this->getNodeNumElements () == 0) {
        return Tpetra::Details::OrdinalTraits<LocalOrdinal>::invalid ();
      } else { // Local indices are always zero-based.
        return static_cast<LocalOrdinal> (this->getNodeNumElements () - 1);
      }
    }

    GlobalOrdinal getMinGlobalIndex () const {
      return minMyGID_;
    }

    GlobalOrdinal getMaxGlobalIndex () const {
      return maxMyGID_;
    }

    GlobalOrdinal getMinAllGlobalIndex () const {
      return minAllGID_;
    }

    GlobalOrdinal getMaxAllGlobalIndex () const {
      return maxAllGID_;
    }

    LocalOrdinal getLocalElement (GlobalOrdinal globalIndex) const;

    GlobalOrdinal getGlobalElement (LocalOrdinal localIndex) const;

    local_map_type getLocalMap () const;

    LookupStatus
    getRemoteIndexList (const Teuchos::ArrayView<const GlobalOrdinal>& GIDList,
                        const Teuchos::ArrayView<                int>& nodeIDList,
                        const Teuchos::ArrayView<       LocalOrdinal>& LIDList) const;

    LookupStatus
    getRemoteIndexList (const Teuchos::ArrayView<const GlobalOrdinal> & GIDList,
                        const Teuchos::ArrayView<                int> & nodeIDList) const;

  private:
    typedef Kokkos::View<const GlobalOrdinal*,
                         Kokkos::LayoutLeft,
                         device_type> global_indices_array_type;

  public:
    global_indices_array_type getMyGlobalIndices () const;

    Teuchos::ArrayView<const GlobalOrdinal> getNodeElementList() const;



    bool isNodeLocalElement (LocalOrdinal localIndex) const;

    bool isNodeGlobalElement (GlobalOrdinal globalIndex) const;

    bool isUniform () const;

    bool isContiguous () const;

    bool isDistributed () const;

    bool isCompatible (const Map<LocalOrdinal,GlobalOrdinal,Node> &map) const;

    bool isSameAs (const Map<LocalOrdinal,GlobalOrdinal,Node> &map) const;

    bool locallySameAs (const Map<LocalOrdinal, GlobalOrdinal, node_type>& map) const;



    Teuchos::RCP<const Teuchos::Comm<int> > getComm () const;

    Teuchos::RCP<Node> getNode () const;



    std::string description () const;

    void
    describe (Teuchos::FancyOStream &out,
              const Teuchos::EVerbosityLevel verbLevel =
                Teuchos::Describable::verbLevel_default) const;


    template <class NodeOut>
    Teuchos::RCP<const Map<LocalOrdinal, GlobalOrdinal, NodeOut> >
    clone (const Teuchos::RCP<NodeOut>& nodeOut) const;

    Teuchos::RCP<const Map<LocalOrdinal, GlobalOrdinal, Node> >
    removeEmptyProcesses () const;

    Teuchos::RCP<const Map<LocalOrdinal, GlobalOrdinal, Node> >
    replaceCommWithSubset (const Teuchos::RCP<const Teuchos::Comm<int> >& newComm) const;

  protected:
    // This lets other specializations of Map access all of this
    // specialization's internal methods and data, so that we can
    // implement clone() without exposing the details of Map to users.
    template <class LO, class GO, class N> friend class Map;

  private:
    template<class OutMapType, class InMapType>
    friend struct Details::MapCloner;

    std::string
    localDescribeToString (const Teuchos::EVerbosityLevel vl) const;

    void setupDirectory () const;

    bool checkIsDist() const;

    global_size_t
    initialNonuniformDebugCheck (const global_size_t numGlobalElements,
                                 const size_t numLocalElements,
                                 const GlobalOrdinal indexBase,
                                 const Teuchos::RCP<const Teuchos::Comm<int> >& comm) const;

    void
    initWithNonownedHostIndexList (const global_size_t numGlobalElements,
                                   const Kokkos::View<const GlobalOrdinal*,
                                     Kokkos::LayoutLeft,
                                     Kokkos::HostSpace,
                                     Kokkos::MemoryUnmanaged>& entryList,
                                   const GlobalOrdinal indexBase,
                                   const Teuchos::RCP<const Teuchos::Comm<int> >& comm);

    Teuchos::RCP<const Teuchos::Comm<int> > comm_;

    Teuchos::RCP<Node> node_;

    GlobalOrdinal indexBase_;

    global_size_t numGlobalElements_;

    size_t numLocalElements_;

    GlobalOrdinal minMyGID_;

    GlobalOrdinal maxMyGID_;

    GlobalOrdinal minAllGID_;

    GlobalOrdinal maxAllGID_;

    GlobalOrdinal firstContiguousGID_;

    GlobalOrdinal lastContiguousGID_;

    bool uniform_;

    bool contiguous_;

    bool distributed_;

    mutable Kokkos::View<const GlobalOrdinal*,
                         Kokkos::LayoutLeft,
                         device_type> lgMap_;

    mutable typename decltype (lgMap_)::HostMirror lgMapHost_;

    typedef Details::FixedHashTable<GlobalOrdinal, LocalOrdinal, device_type>
      global_to_local_table_type;

    global_to_local_table_type glMap_;

    mutable Teuchos::RCP<Directory<LocalOrdinal,GlobalOrdinal,Node> > directory_;

  }; // Map class

  template <class LocalOrdinal, class GlobalOrdinal>
  Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal> >
  createLocalMap (const size_t numElements,
                  const Teuchos::RCP<const Teuchos::Comm<int> >& comm);

  template <class LocalOrdinal, class GlobalOrdinal, class Node>
  Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> >
  createLocalMapWithNode (const size_t numElements,
                          const Teuchos::RCP<const Teuchos::Comm<int> >& comm,
                          const Teuchos::RCP<Node>& node = Teuchos::null);

  template <class LocalOrdinal, class GlobalOrdinal>
  Teuchos::RCP< const Map<LocalOrdinal,GlobalOrdinal> >
  createUniformContigMap (const global_size_t numElements,
                          const Teuchos::RCP<const Teuchos::Comm<int> >& comm);

  template <class LocalOrdinal, class GlobalOrdinal, class Node>
  Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> >
  createUniformContigMapWithNode (const global_size_t numElements,
                                  const Teuchos::RCP<const Teuchos::Comm<int> >& comm,
                                  const Teuchos::RCP<Node>& node = Teuchos::null);

  template <class LocalOrdinal, class GlobalOrdinal>
  Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal> >
  createContigMap (const global_size_t numElements,
                   const size_t localNumElements,
                   const Teuchos::RCP<const Teuchos::Comm<int> >& comm);

  template <class LocalOrdinal, class GlobalOrdinal, class Node>
  Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> >
  createContigMapWithNode (const global_size_t numElements,
                           const size_t localNumElements,
                           const Teuchos::RCP<const Teuchos::Comm<int> >& comm,
                           const Teuchos::RCP<Node>& node =
                             defaultArgNode<Node> ());

  template <class LocalOrdinal, class GlobalOrdinal>
  Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal> >
  createNonContigMap (const Teuchos::ArrayView<const GlobalOrdinal>& elementList,
                      const Teuchos::RCP<const Teuchos::Comm<int> >& comm);

  template <class LocalOrdinal, class GlobalOrdinal, class Node>
  Teuchos::RCP< const Map<LocalOrdinal,GlobalOrdinal,Node> >
  createNonContigMapWithNode (const Teuchos::ArrayView<const GlobalOrdinal> &elementList,
                              const Teuchos::RCP<const Teuchos::Comm<int> > &comm,
                              const Teuchos::RCP<Node>& node = Teuchos::null);

  template <class LocalOrdinal, class GlobalOrdinal, class Node>
  Teuchos::RCP< const Map<LocalOrdinal,GlobalOrdinal,Node> >
  createWeightedContigMapWithNode (const int thisNodeWeight,
                                   const global_size_t numElements,
                                   const Teuchos::RCP<const Teuchos::Comm<int> > &comm,
                                   const Teuchos::RCP<Node>& node = Teuchos::null);

  template<class LocalOrdinal, class GlobalOrdinal, class Node>
  Teuchos::RCP< const Map<LocalOrdinal,GlobalOrdinal,Node> >
  createOneToOne (const Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &M);

  template<class LocalOrdinal, class GlobalOrdinal, class Node>
  Teuchos::RCP< const Map<LocalOrdinal,GlobalOrdinal,Node> >
  createOneToOne(const Teuchos::RCP<const Map<LocalOrdinal,GlobalOrdinal,Node> > &M,
                 const Tpetra::Details::TieBreak<LocalOrdinal,GlobalOrdinal> & tie_break);

} // Tpetra namespace

#include "Tpetra_Directory_decl.hpp"

namespace Tpetra {
  namespace Details {

    template<class OutMapType, class InMapType>
    OutMapType
    MapCloner<OutMapType, InMapType>::
    clone (const InMapType& mapIn,
           const Teuchos::RCP<out_node_type>& nodeOut)
    {
      static_assert (std::is_same<typename OutMapType::local_ordinal_type,
                                  typename InMapType::local_ordinal_type>::value,
                     "Tpetra::Map clone: The LocalOrdinal template parameter "
                     "of the input and output Map types must be the same.");
      static_assert (std::is_same<typename OutMapType::global_ordinal_type,
                                  typename InMapType::global_ordinal_type>::value,
                     "Tpetra::Map clone: The GlobalOrdinal template parameter "
                     "of the input and output Map types must be the same.");
      typedef typename OutMapType::local_ordinal_type LO;
      typedef typename OutMapType::global_ordinal_type GO;
      typedef ::Tpetra::Directory<LO, GO,
                                  typename OutMapType::node_type> out_dir_type;
      typedef typename OutMapType::global_to_local_table_type out_table_type;
      typedef typename OutMapType::device_type out_device_type;

      OutMapType mapOut; // Make an empty Map.

      // Fill the new Map with (possibly) shallow copies of all of the
      // original Map's data.  This is safe because Map is immutable,
      // so users can't change the original Map.
      mapOut.comm_              = mapIn.comm_;
      mapOut.indexBase_         = mapIn.indexBase_;
      mapOut.numGlobalElements_ = mapIn.numGlobalElements_;
      mapOut.numLocalElements_  = mapIn.numLocalElements_;
      mapOut.minMyGID_          = mapIn.minMyGID_;
      mapOut.maxMyGID_          = mapIn.maxMyGID_;
      mapOut.minAllGID_         = mapIn.minAllGID_;
      mapOut.maxAllGID_         = mapIn.maxAllGID_;
      mapOut.firstContiguousGID_= mapIn.firstContiguousGID_;
      mapOut.lastContiguousGID_ = mapIn.lastContiguousGID_;
      mapOut.uniform_           = mapIn.uniform_;
      mapOut.contiguous_        = mapIn.contiguous_;
      mapOut.distributed_       = mapIn.distributed_;
      {
        // mfh 25 Dec 2015, 11 Jan 2016: We really only need to make a
        // deep copy if the two Map types have different memory
        // spaces.  However, if you're calling clone(), it is likely
        // the case that the memory spaces differ, so it doesn't hurt
        // to make a deep copy here.
        Kokkos::View<GO*, Kokkos::LayoutLeft, out_device_type>
          lgMapOut ("lgMap", mapIn.lgMap_.dimension_0 ());
        Kokkos::deep_copy (lgMapOut, mapIn.lgMap_);
        mapOut.lgMap_ = lgMapOut; // cast to const

        // mfh 11 Apr 2016: We can't just assign mapIn.lgMapHost_ to
        // mapOut.lgMapHost_ either.  This is because the memory space
        // of the host mirror of a CudaUVMSpace View is also
        // CudaUVMSpace, but the memory space of the host mirror of a
        // HostSpace View is HostSpace.  We can't assign one View to
        // another View with a different memory space.
        //
        // What we _can_ do here, though, is avoid a deep_copy in case
        // we're not using CUDA, by exploiting host mirrors.

        static_assert (std::is_same<typename decltype (mapOut.lgMapHost_)::array_layout,
                         typename decltype (mapIn.lgMapHost_)::array_layout>::value,
          "mapOut.lgMapHost_ and MapIn.lgMapHost_ do not have the same "
          "array_layout.  Please report this bug to the Tpetra developers.");

        // lgMapOut is nonconst, so use it here instead of mapOut.lgMap_.
        auto lgMapHostOut = Kokkos::create_mirror_view (lgMapOut);
        Kokkos::deep_copy (lgMapHostOut, lgMapOut);
        mapOut.lgMapHost_ = lgMapHostOut;
      }
      // This makes a deep copy only if necessary.  We could have
      // defined operator= to do this, but that would violate
      // expectations.  (Kokkos::View::operator= only does a shallow
      // copy, EVER.)
      mapOut.glMap_ = out_table_type (mapIn.glMap_);
      // New Map gets the new Node instance.
      mapOut.node_ = nodeOut;

      // We could cleverly clone the Directory here if it is
      // initialized, but there is no harm in simply creating it
      // uninitialized.
      mapOut.directory_ = Teuchos::rcp (new out_dir_type ());

      return mapOut;
    }
  } // namespace Details


  template <class LocalOrdinal, class GlobalOrdinal, class Node>
  template <class NodeOut>
  Teuchos::RCP<const Map<LocalOrdinal, GlobalOrdinal, NodeOut> >
  Map<LocalOrdinal,GlobalOrdinal,Node>::
  clone (const Teuchos::RCP<NodeOut>& nodeOut) const
  {
    typedef Map<LocalOrdinal, GlobalOrdinal, Node> in_map_type;
    typedef Map<LocalOrdinal, GlobalOrdinal, NodeOut> out_map_type;
    typedef Details::MapCloner<out_map_type, in_map_type> cloner_type;
    // Copy constructor does a shallow copy.
    return Teuchos::rcp (new out_map_type (cloner_type::clone (*this, nodeOut)));
  }

  namespace Details {
    template <class LocalOrdinal,class GlobalOrdinal, class Node>
    bool
    isLocallyFitted (const Tpetra::Map<LocalOrdinal, GlobalOrdinal, Node>& map1,
                     const Tpetra::Map<LocalOrdinal, GlobalOrdinal, Node>& map2);
  } // namespace Details

} // namespace Tpetra

template <class LocalOrdinal, class GlobalOrdinal, class Node>
bool operator== (const Tpetra::Map<LocalOrdinal,GlobalOrdinal,Node> &map1,
                 const Tpetra::Map<LocalOrdinal,GlobalOrdinal,Node> &map2)
{ return map1.isSameAs (map2); }

template <class LocalOrdinal, class GlobalOrdinal, class Node>
bool operator!= (const Tpetra::Map<LocalOrdinal,GlobalOrdinal,Node> &map1,
                 const Tpetra::Map<LocalOrdinal,GlobalOrdinal,Node> &map2)
{ return ! map1.isSameAs (map2); }


#endif // TPETRA_MAP_DECL_HPP