Tpetra Matrix/Vector Services Version of the Day
Related Functions
Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node > Class Template Reference

Describes a parallel distribution of objects over processes. More...

#include <Tpetra_Map_decl.hpp>

Inheritance diagram for Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >:
Inheritance graph
[legend]

List of all members.

Public Member Functions

Constructors and destructor
 Map (global_size_t numGlobalElements, GlobalOrdinal indexBase, const Teuchos::RCP< const Teuchos::Comm< int > > &comm, LocalGlobal lg=GloballyDistributed, const Teuchos::RCP< Node > &node=Kokkos::DefaultNode::getDefaultNode())
 Constructor with Tpetra-defined contiguous uniform distribution.
 Map (global_size_t numGlobalElements, size_t numLocalElements, GlobalOrdinal indexBase, const Teuchos::RCP< const Teuchos::Comm< int > > &comm, const Teuchos::RCP< Node > &node=Kokkos::DefaultNode::getDefaultNode())
 Constructor with a user-defined contiguous distribution.
 Map (global_size_t numGlobalElements, const Teuchos::ArrayView< const GlobalOrdinal > &elementList, GlobalOrdinal indexBase, const Teuchos::RCP< const Teuchos::Comm< int > > &comm, const Teuchos::RCP< Node > &node=Kokkos::DefaultNode::getDefaultNode())
 Constructor with user-defined arbitrary (possibly noncontiguous) distribution.
 ~Map ()
 Destructor.
Attributes
global_size_t getGlobalNumElements () const
 The number of elements in this Map.
size_t getNodeNumElements () const
 The number of elements belonging to the calling node.
GlobalOrdinal getIndexBase () const
 The index base for this Map.
LocalOrdinal getMinLocalIndex () const
 The minimum local index.
LocalOrdinal getMaxLocalIndex () const
 The maximum local index on the calling process.
GlobalOrdinal getMinGlobalIndex () const
 The minimum global index owned by the calling process.
GlobalOrdinal getMaxGlobalIndex () const
 The maximum global index owned by the calling process.
GlobalOrdinal getMinAllGlobalIndex () const
 The minimum global index over all processes in the communicator.
GlobalOrdinal getMaxAllGlobalIndex () const
 The maximum global index over all processes in the communicator.
LocalOrdinal getLocalElement (GlobalOrdinal globalIndex) const
 The local index corresponding to the given global index.
GlobalOrdinal getGlobalElement (LocalOrdinal localIndex) const
 The global index corresponding to the given local index.
LookupStatus getRemoteIndexList (const Teuchos::ArrayView< const GlobalOrdinal > &GIDList, const Teuchos::ArrayView< int > &nodeIDList, const Teuchos::ArrayView< LocalOrdinal > &LIDList) const
 Return the process IDs and corresponding local IDs for the given global IDs.
LookupStatus getRemoteIndexList (const Teuchos::ArrayView< const GlobalOrdinal > &GIDList, const Teuchos::ArrayView< int > &nodeIDList) const
 Return the process IDs for the given global IDs.
Teuchos::ArrayView< const
GlobalOrdinal > 
getNodeElementList () const
 Return a view of the global indices owned by this node.
Boolean tests
bool isNodeLocalElement (LocalOrdinal localIndex) const
 True if the local index is valid for this Map on this node, else false.
bool isNodeGlobalElement (GlobalOrdinal globalIndex) const
 True if the global index is found in this Map on this node, else false.
bool isContiguous () const
 True if this Map is distributed contiguously, else false.
bool isDistributed () const
 Whether this Map is globally distributed or locally replicated.
bool isCompatible (const Map< LocalOrdinal, GlobalOrdinal, Node > &map) const
 True if and only if map is compatible with this Map.
bool isSameAs (const Map< LocalOrdinal, GlobalOrdinal, Node > &map) const
 True if and only if map is identical to this Map.
const Teuchos::RCP< const
Teuchos::Comm< int > > & 
getComm () const
 Accessors for the Teuchos::Comm and Kokkos Node objects.
const Teuchos::RCP< Node > & getNode () const
 Get this Map's Node object.
std::string description () const
 Implementation of Teuchos::Describable.
void describe (Teuchos::FancyOStream &out, const Teuchos::EVerbosityLevel verbLevel=Teuchos::Describable::verbLevel_default) const
 Print this object with the given verbosity level to the given FancyOStream.

Related Functions

(Note that these are not member functions.)

template<class LocalOrdinal , class GlobalOrdinal >
Teuchos::RCP< const Map
< LocalOrdinal, GlobalOrdinal,
Kokkos::DefaultNode::DefaultNodeType > > 
createLocalMap (size_t numElements, const Teuchos::RCP< const Teuchos::Comm< int > > &comm)
 Non-member constructor for a locally replicated Map with the default Kokkos Node.
template<class LocalOrdinal , class GlobalOrdinal , class Node >
Teuchos::RCP< const Map
< LocalOrdinal, GlobalOrdinal,
Node > > 
createLocalMapWithNode (size_t numElements, const Teuchos::RCP< const Teuchos::Comm< int > > &comm, const Teuchos::RCP< Node > &node)
 Non-member constructor for a locally replicated Map with a specified Kokkos Node.
template<class LocalOrdinal , class GlobalOrdinal >
Teuchos::RCP< const Map
< LocalOrdinal, GlobalOrdinal,
Kokkos::DefaultNode::DefaultNodeType > > 
createUniformContigMap (global_size_t numElements, const Teuchos::RCP< const Teuchos::Comm< int > > &comm)
 Non-member constructor for a uniformly distributed, contiguous Map with the default Kokkos Node.
template<class LocalOrdinal , class GlobalOrdinal , class Node >
Teuchos::RCP< const Map
< LocalOrdinal, GlobalOrdinal,
Node > > 
createUniformContigMapWithNode (global_size_t numElements, const Teuchos::RCP< const Teuchos::Comm< int > > &comm, const Teuchos::RCP< Node > &node)
 Non-member constructor for a uniformly distributed, contiguous Map with a user-specified Kokkos Node.
template<class LocalOrdinal , class GlobalOrdinal >
Teuchos::RCP< const Map
< LocalOrdinal, GlobalOrdinal,
Kokkos::DefaultNode::DefaultNodeType > > 
createContigMap (global_size_t numElements, size_t localNumElements, const Teuchos::RCP< const Teuchos::Comm< int > > &comm)
 Non-member constructor for a (potentially) non-uniformly distributed, contiguous Map with the default Kokkos Node.
template<class LocalOrdinal , class GlobalOrdinal , class Node >
Teuchos::RCP< const Map
< LocalOrdinal, GlobalOrdinal,
Node > > 
createContigMapWithNode (global_size_t numElements, size_t localNumElements, const Teuchos::RCP< const Teuchos::Comm< int > > &comm, const Teuchos::RCP< Node > &node)
 Non-member constructor for a (potentially) non-uniformly distributed, contiguous Map with a user-specified Kokkos Node.
template<class LocalOrdinal , class GlobalOrdinal >
Teuchos::RCP< const Map
< LocalOrdinal, GlobalOrdinal,
Kokkos::DefaultNode::DefaultNodeType > > 
createNonContigMap (const ArrayView< const GlobalOrdinal > &elementList, const RCP< const Teuchos::Comm< int > > &comm)
 Non-member constructor for a non-contiguous Map with the default Kokkos Node.
template<class LocalOrdinal , class GlobalOrdinal , class Node >
Teuchos::RCP< const Map
< LocalOrdinal, GlobalOrdinal,
Node > > 
createNonContigMapWithNode (const ArrayView< const GlobalOrdinal > &elementList, const RCP< const Teuchos::Comm< int > > &comm, const RCP< Node > &node)
 Non-member constructor for a non-contiguous Map with a user-specified Kokkos Node.
template<class LocalOrdinal , class GlobalOrdinal , class Node >
Teuchos::RCP< const Map
< LocalOrdinal, GlobalOrdinal,
Node > > 
createWeightedContigMapWithNode (int thisNodeWeight, global_size_t numElements, const Teuchos::RCP< const Teuchos::Comm< int > > &comm, const Teuchos::RCP< Node > &node)
 Non-member constructor for a contiguous Map with user-defined weights and a user-specified Kokkos Node.
template<class LocalOrdinal , class GlobalOrdinal , class Node >
Teuchos::RCP< const Map
< LocalOrdinal, GlobalOrdinal,
Node > > 
createOneToOne (Teuchos::RCP< const Map< LocalOrdinal, GlobalOrdinal, Node > > &M)
 Creates a one-to-one version of the given Map where each GID is owned by only one process.
template<class LocalOrdinal , class GlobalOrdinal , class Node >
bool operator== (const Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node > &map1, const Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node > &map2)
 True if map1 is the same as (in the sense of isSameAs()) map2, else false.
template<class LocalOrdinal , class GlobalOrdinal , class Node >
bool operator!= (const Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node > &map1, const Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node > &map2)
 True if map1 is not the same as (in the sense of isSameAs()) map2, else false.

Detailed Description

template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
class Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >

Describes a parallel distribution of objects over processes.

Template Parameters:
LocalOrdinalThe type of local indices. Should be an integer, and generally should be signed. A good model of LocalOrdinal is int. (In Epetra, this is always just int.)
GlobalOrdinalThe type of global indices. Should be an integer, and generally should be signed. Also, sizeof(GlobalOrdinal) should be greater than to equal to sizeof(LocalOrdinal). For example, if LocalOrdinal is int, good models of GlobalOrdinal are int, long, long long (if the configure-time option Teuchos_ENABLE_LONG_LONG was set), or ptrdiff_t.
NodeA class implementing on-node shared-memory parallel operations. It must implement the Kokkos Node API. The default Node type should suffice for most users. The actual default type depends on your Trilinos build options.

This class describes a distribution of data elements over one or more processes in a communicator. Each element has a global index (of type GlobalOrdinal) uniquely associated to it. Each global index in the Map is "owned" by one or more processes in the Map's communicator. The user gets to decide what an "element" means; examples include a row or column of a sparse matrix (as in CrsMatrix), or a row of one or more vectors (as in MultiVector).

Prerequisites

Before reading the rest of this documentation, it helps to know something about the Teuchos memory management classes, in particular Teuchos::RCP, Teuchos::ArrayRCP, and Teuchos::ArrayView. You should also know a little bit about MPI (the Message Passing Interface for distributed-memory programming). You won't have to use MPI directly to use Map, but it helps to be familiar with the general idea of distributed storage of data over a communicator.

Map concepts

Local and global indices

The distinction between local and global indices and types might confuse new Tpetra users. Global indices represent the elements of a distributed object (such as rows or columns of a CrsMatrix, or rows of a MultiVector) uniquely over the entire object, which may be distributed over multiple processes. Local indices are local to the process that owns them. If global index G is owned by process P, then there is a unique local index L on process P corresponding to G. If the local index L is valid on process P, then there is a unique global index G owned by P corresponding to the pair (L, P). However, multiple processes might own the same global index (an "overlapping Map"), so a global index G might correspond to multiple (L, P) pairs. In summary, local indices on a process correspond to object elements (e.g., sparse matrix rows or columns) owned by that process.

Tpetra differs from Epetra in that local and global indices may have different types. In Epetra, local and global indices both have type int. In Tpetra, you get to pick the type of each. For example, you can use a 64-bit integer GlobalOrdinal type to solve problems with more than $2^{31}$ unknowns, but a 32-bit integer LocalOrdinal type to save bandwidth in sparse matrix-vector multiply.

Contiguous or noncontiguous

A Map is contiguous when each process' list of global IDs forms an interval and is strictly increasing, and the globally minimum global ID equals the index base. Map optimizes for the contiguous case. In particular, noncontiguous Maps require communication in order to figure out which process owns a particular global ID. (This communication happens in getRemoteIndexList().)

Globally distributed or locally replicated

"Globally distributed" means that all of the following are true:

1. The map's communicator has more than one process. 2. There is at least one process in the map's communicator, whose local number of elements does not equal the number of global elements. (That is, not all the elements are replicated over all the processes.)

If at least one of the above are not true, then the map is "locally replicated." (The two are mutually exclusive.)

Examples:

CrsMatrix_BlockExtraction.cpp, LocalMatOpExample.cpp, and Tpetra_Power_Method.cpp.

Definition at line 161 of file Tpetra_Map_decl.hpp.


Constructor & Destructor Documentation

template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >::Map ( global_size_t  numGlobalElements,
GlobalOrdinal  indexBase,
const Teuchos::RCP< const Teuchos::Comm< int > > &  comm,
LocalGlobal  lg = GloballyDistributed,
const Teuchos::RCP< Node > &  node = Kokkos::DefaultNode::getDefaultNode() 
)

Constructor with Tpetra-defined contiguous uniform distribution.

This constructor produces a Map with the given number of elements distributed among processes in the given communicator, so that the subsets of global elements are nonoverlapping, contiguous, and as evenly distributed across the processes as possible.

Parameters:
numGlobalElements[in] Number of elements in the Map (over all processes)
indexBase[in] The base of both local and global indices in the Map. C and C++ programmers would normally use zero, and Fortran programmers (if you are using Tpetra from Fortran) would use one. For this Map constructor, the index base will also be the smallest global ID in the Map. (If you don't know what this should be, use zero.)
comm[in] Communicator over which to distribute the elements.
node[in/out] Kokkos Node instance. The type of this object must match the type of the Node template parameter of Map. If Node is not the same as the default Node type Kokkos::DefaultNode::DefaultNodeType, you will need to provide a nondefault value.
template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >::Map ( global_size_t  numGlobalElements,
size_t  numLocalElements,
GlobalOrdinal  indexBase,
const Teuchos::RCP< const Teuchos::Comm< int > > &  comm,
const Teuchos::RCP< Node > &  node = Kokkos::DefaultNode::getDefaultNode() 
)

Constructor with a user-defined contiguous distribution.

If N is the sum of numLocalElements over all processes, then this constructor produces a nonoverlapping Map distributed over the processes in the given communicator, with numLocalElements contiguous elements on the calling process.

Parameters:
numGlobalElements[in] If numGlobalElements == Teuchos::OrdinalTraits<global_size_t>::invalid(), the number of global elements will be computed (via a global communication) as the sum of the counts of local elements. Otherwise, it must equal the sum of the local elements over all processes. This will only be checked if Trilinos' Teuchos package was built with debug support (CMake Boolean option TEUCHOS_ENABLE_DEBUG=ON). If verification fails, the constructor will throw std::invalid_argument.
numLocalElements[in] Number of elements that the calling process will own in the Map.
indexBase[in] The base of both local and global indices in the Map. C and C++ programmers would normally use zero, and Fortran programmers (if you are using Tpetra from Fortran) would use one. For this Map constructor, the index base will also be the smallest global ID in the Map. (If you don't know what this should be, use zero.)
comm[in] Communicator over which to distribute the elements.
node[in/out] Kokkos Node instance. The type of this object must match the type of the Node template parameter of Map. If Node is not the same as the default Node type Kokkos::DefaultNode::DefaultNodeType, you will need to provide a nondefault value.
template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >::Map ( global_size_t  numGlobalElements,
const Teuchos::ArrayView< const GlobalOrdinal > &  elementList,
GlobalOrdinal  indexBase,
const Teuchos::RCP< const Teuchos::Comm< int > > &  comm,
const Teuchos::RCP< Node > &  node = Kokkos::DefaultNode::getDefaultNode() 
)

Constructor with user-defined arbitrary (possibly noncontiguous) distribution.

Call this constructor if you have an arbitrary list of global IDs that you want each process in the given communicator to own. Those IDs need not be contiguous, and the sets of global IDs on different processes may overlap. This is the constructor to use to make an overlapping distribution.

Parameters:
numGlobalElements[in] If numGlobalElements == Teuchos::OrdinalTraits<global_size_t>::invalid(), the number of global elements will be computed (via a global communication) as the sum of the counts of local elements. Otherwise, it must equal the sum of the local elements over all processes. This will only be checked if Trilinos' Teuchos package was built with debug support (CMake Boolean option TEUCHOS_ENABLE_DEBUG=ON). If verification fails, the constructor will throw std::invalid_argument.
elementList[in] List of global IDs owned by the calling process.
indexBase[in] The base of both local and global indices in the Map. C and C++ programmers would normally use zero, and Fortran programmers (if you are using Tpetra from Fortran) would use one. (If you don't know what this should be, use zero.)
comm[in] Communicator over which to distribute the elements.
node[in/out] Kokkos Node instance. The type of this object must match the type of the Node template parameter of Map. If Node is not the same as the default Node type Kokkos::DefaultNode::DefaultNodeType, you will need to provide a nondefault value.
template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >::~Map ( )

Destructor.


Member Function Documentation

template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
global_size_t Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >::getGlobalNumElements ( ) const [inline]

The number of elements in this Map.

Definition at line 291 of file Tpetra_Map_decl.hpp.

template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
size_t Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >::getNodeNumElements ( ) const [inline]

The number of elements belonging to the calling node.

Definition at line 294 of file Tpetra_Map_decl.hpp.

template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
GlobalOrdinal Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >::getIndexBase ( ) const [inline]

The index base for this Map.

Definition at line 297 of file Tpetra_Map_decl.hpp.

template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
LocalOrdinal Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >::getMinLocalIndex ( ) const [inline]

The minimum local index.

Definition at line 300 of file Tpetra_Map_decl.hpp.

template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
LocalOrdinal Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >::getMaxLocalIndex ( ) const [inline]

The maximum local index on the calling process.

If getNodeNumElements() == 0, this returns Teuchos::OrdinalTraits<LO>::invalid().

Definition at line 308 of file Tpetra_Map_decl.hpp.

template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
GlobalOrdinal Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >::getMinGlobalIndex ( ) const [inline]

The minimum global index owned by the calling process.

Definition at line 323 of file Tpetra_Map_decl.hpp.

template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
GlobalOrdinal Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >::getMaxGlobalIndex ( ) const [inline]

The maximum global index owned by the calling process.

Definition at line 326 of file Tpetra_Map_decl.hpp.

template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
GlobalOrdinal Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >::getMinAllGlobalIndex ( ) const [inline]

The minimum global index over all processes in the communicator.

Definition at line 329 of file Tpetra_Map_decl.hpp.

template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
GlobalOrdinal Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >::getMaxAllGlobalIndex ( ) const [inline]

The maximum global index over all processes in the communicator.

Definition at line 332 of file Tpetra_Map_decl.hpp.

template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
LocalOrdinal Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >::getLocalElement ( GlobalOrdinal  globalIndex) const

The local index corresponding to the given global index.

If the given global index is not owned by this process, return Teuchos::OrdinalTraits<LocalOrdinal>::invalid().

template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
GlobalOrdinal Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >::getGlobalElement ( LocalOrdinal  localIndex) const

The global index corresponding to the given local index.

If the given local index is not valid on the calling process, return Teuchos::OrdinalTraits<GlobalOrdinal>::invalid().

template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
LookupStatus Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >::getRemoteIndexList ( const Teuchos::ArrayView< const GlobalOrdinal > &  GIDList,
const Teuchos::ArrayView< int > &  nodeIDList,
const Teuchos::ArrayView< LocalOrdinal > &  LIDList 
) const

Return the process IDs and corresponding local IDs for the given global IDs.

This operation should always be called as a collective over all processes in the communicator. For a distributed noncontiguous Map, this operation requires communication.

Parameters:
GIDList[in] List of global IDs for which to find process IDs and local IDs. These global IDs need not be owned by the calling process. Indeed, they need not be owned by any process.
nodeIDList[out] List of process IDs corresponding to the given global IDs. If a global ID does not belong to any process, the resulting process ID is -1.
LIDList[out] List of local IDs (that is, the local ID on the process that owns them) corresponding the given global IDs. If a global ID does not have a local ID, the resulting local ID is Teuchos::OrdinalTraits<LocalOrdinal>::invalid().
Precondition:
nodeIDList.size() == GIDList.size()
LIDList.size() == GIDList.size()
Returns:
IDNotPresent indicates that for at least one global ID, we could not find the corresponding process ID. Otherwise, return AllIDsPresent.
Note:
This is crucial technology used in Export, Import, CrsGraph, and CrsMatrix.
template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
LookupStatus Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >::getRemoteIndexList ( const Teuchos::ArrayView< const GlobalOrdinal > &  GIDList,
const Teuchos::ArrayView< int > &  nodeIDList 
) const

Return the process IDs for the given global IDs.

This operation should always be called as a collective over all processes in the communicator. For a distributed noncontiguous Map, this operation requires communication.

Parameters:
GIDList[in] List of global IDs for which to find process IDs and local IDs. These global IDs need not be owned by the calling process. Indeed, they need not be owned by any process.
nodeIDList[out] List of process IDs corresponding to the given global IDs. If a global ID does not belong to any process, the resulting process ID is -1.
Precondition:
nodeIDList.size() == GIDList.size()
Returns:
IDNotPresent indicates that for at least one global ID, we could not find the corresponding process ID. Otherwise, return AllIDsPresent.
Note:
For a distributed noncontiguous Map, this operation requires communication. This is crucial technology used in Export, Import, CrsGraph, and CrsMatrix.
template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
Teuchos::ArrayView<const GlobalOrdinal> Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >::getNodeElementList ( ) const

Return a view of the global indices owned by this node.

template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
bool Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >::isNodeLocalElement ( LocalOrdinal  localIndex) const

True if the local index is valid for this Map on this node, else false.

template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
bool Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >::isNodeGlobalElement ( GlobalOrdinal  globalIndex) const

True if the global index is found in this Map on this node, else false.

template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
bool Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >::isContiguous ( ) const

True if this Map is distributed contiguously, else false.

Currently, creating this Map using the constructor for a user-defined arbitrary distribution (that takes a list of global elements owned on each process) means that this method always returns false. We currently make no effort to test whether the user-provided global indices are actually contiguous on all the processes. Many operations may be faster for contiguous Maps. Thus, if you know the indices are contiguous on all processes, you should consider using one of the constructors for contiguous elements.

template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
bool Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >::isDistributed ( ) const

Whether this Map is globally distributed or locally replicated.

Returns:
True if this Map is globally distributed, else false.

"Globally distributed" means that all of the following are true:

1. The map's communicator has more than one process.

2. There is at least one process in the map's communicator, whose local number of elements does not equal the number of global elements. (That is, not all the elements are replicated over all the processes.)

If at least one of the above are not true, then the map is "locally replicated." (The two are mutually exclusive.)

Calling this method requires no communication or computation, because the result is precomputed in Map's constructors.

template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
bool Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >::isCompatible ( const Map< LocalOrdinal, GlobalOrdinal, Node > &  map) const

True if and only if map is compatible with this Map.

Two Maps are "compatible" if all of the following are true: 1. They have the same global number of elements. 2. They have the same number of local elements on each process.

Determining #2 requires communication (a reduction over this Map's communicator). This method assumes that the input Map is valid on all processes in this Map's communicator.

Compatibility is useful for determining correctness of certain operations, like assigning one MultiVector X to another Y. If X and Y have the same number of columns, and if their Maps are compatible, then it is legal to assign X to Y or to assign Y to X.

Notes for Tpetra developers:

If the input Map and this Map have different communicators, the behavior of this method is currently undefined. In general, Tpetra currently assumes that if users instigate interactions between Tpetra objects, then those Tpetra objects have the same communicator. Also, defining semantics of interaction between Tpetra objects with different communicators may be tricky. It seems like two Maps could be compatible even if they had different communicators, as long as their communicators have the same number of processes. Could two Maps with different communicators be the same (in the sense of isSameAs())? It's not clear.

Checking whether two communicators are the same would require extending Teuchos::Comm to provide a comparison operator. This could be implemented for MPI communicators by returning true if MPI_Comm_compare() returns MPI_IDENT, and false otherwise. (Presumably, MPI_Comm_compare() works even if the two communicators have different process counts; the MPI 2.2 standard doesn't say otherwise.) All serial communicators have the same context and contain the same number of processes, so all serial communicators are equal.

template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
bool Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >::isSameAs ( const Map< LocalOrdinal, GlobalOrdinal, Node > &  map) const

True if and only if map is identical to this Map.

"Identical" is stronger than "compatible." Two Maps are identical if all of the following are true: 1. They have the same min and max global indices. 2. They have the same global number of elements. 3. They are either both distributed, or both not distributed. 4. Their index bases are the same. 5. They have the same number of local elements on each process. 6. They have the same global indices on each process.

#2 and #5 are exactly "compatibility" (see isCompatible()). Thus, "identical" includes, but is stronger than, "compatible."

A Map corresponds to a block permutation over process ranks and global element indices. Two Maps with different numbers of processes in their communicators cannot be compatible, let alone identical. Two identical Maps correspond to the same permutation.

Notes for Tpetra developers:

If the input Map and this Map have different communicators, the behavior of this method is currently undefined. See further notes on isCompatible().

template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
const Teuchos::RCP<const Teuchos::Comm<int> >& Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >::getComm ( ) const

Accessors for the Teuchos::Comm and Kokkos Node objects.

Get this Map's Comm object.

template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
const Teuchos::RCP<Node>& Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >::getNode ( ) const

Get this Map's Node object.

template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
std::string Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >::description ( ) const [virtual]

Implementation of Teuchos::Describable.

Return a simple one-line description of this object.

Reimplemented from Teuchos::Describable.

template<class LocalOrdinal, class GlobalOrdinal = LocalOrdinal, class Node = Kokkos::DefaultNode::DefaultNodeType>
void Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node >::describe ( Teuchos::FancyOStream out,
const Teuchos::EVerbosityLevel  verbLevel = Teuchos::Describable::verbLevel_default 
) const [virtual]

Print this object with the given verbosity level to the given FancyOStream.

Reimplemented from Teuchos::Describable.


Friends And Related Function Documentation

template<class LocalOrdinal , class GlobalOrdinal >
Teuchos::RCP< const Map< LocalOrdinal, GlobalOrdinal, Kokkos::DefaultNode::DefaultNodeType > > createLocalMap ( size_t  numElements,
const Teuchos::RCP< const Teuchos::Comm< int > > &  comm 
) [related]

Non-member constructor for a locally replicated Map with the default Kokkos Node.

This method returns a Map instantiated on the Kokkos default node type, Kokkos::DefaultNode::DefaultNodeType.

The Map is configured to use zero-based indexing.

template<class LocalOrdinal , class GlobalOrdinal , class Node >
Teuchos::RCP< const Map< LocalOrdinal, GlobalOrdinal, Node > > createLocalMapWithNode ( size_t  numElements,
const Teuchos::RCP< const Teuchos::Comm< int > > &  comm,
const Teuchos::RCP< Node > &  node 
) [related]

Non-member constructor for a locally replicated Map with a specified Kokkos Node.

The Map is configured to use zero-based indexing.

template<class LocalOrdinal , class GlobalOrdinal >
Teuchos::RCP< const Map< LocalOrdinal, GlobalOrdinal, Kokkos::DefaultNode::DefaultNodeType > > createUniformContigMap ( global_size_t  numElements,
const Teuchos::RCP< const Teuchos::Comm< int > > &  comm 
) [related]

Non-member constructor for a uniformly distributed, contiguous Map with the default Kokkos Node.

This method returns a Map instantiated on the Kokkos default node type, Kokkos::DefaultNode::DefaultNodeType.

The Map is configured to use zero-based indexing.

template<class LocalOrdinal , class GlobalOrdinal , class Node >
Teuchos::RCP< const Map< LocalOrdinal, GlobalOrdinal, Node > > createUniformContigMapWithNode ( global_size_t  numElements,
const Teuchos::RCP< const Teuchos::Comm< int > > &  comm,
const Teuchos::RCP< Node > &  node 
) [related]

Non-member constructor for a uniformly distributed, contiguous Map with a user-specified Kokkos Node.

The Map is configured to use zero-based indexing.

template<class LocalOrdinal , class GlobalOrdinal >
Teuchos::RCP< const Map< LocalOrdinal, GlobalOrdinal, Kokkos::DefaultNode::DefaultNodeType > > createContigMap ( global_size_t  numElements,
size_t  localNumElements,
const Teuchos::RCP< const Teuchos::Comm< int > > &  comm 
) [related]

Non-member constructor for a (potentially) non-uniformly distributed, contiguous Map with the default Kokkos Node.

This method returns a Map instantiated on the Kokkos default node type, Kokkos::DefaultNode::DefaultNodeType.

The Map is configured to use zero-based indexing.

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

Non-member constructor for a (potentially) non-uniformly distributed, contiguous Map with a user-specified Kokkos Node.

The Map is configured to use zero-based indexing.

template<class LocalOrdinal , class GlobalOrdinal >
Teuchos::RCP< const Map< LocalOrdinal, GlobalOrdinal, Kokkos::DefaultNode::DefaultNodeType > > createNonContigMap ( const ArrayView< const GlobalOrdinal > &  elementList,
const RCP< const Teuchos::Comm< int > > &  comm 
) [related]

Non-member constructor for a non-contiguous Map with the default Kokkos Node.

This method returns a Map instantiated on the Kokkos default node type, Kokkos::DefaultNode::DefaultNodeType.

The Map is configured to use zero-based indexing.

template<class LocalOrdinal , class GlobalOrdinal , class Node >
Teuchos::RCP< const Map< LocalOrdinal, GlobalOrdinal, Node > > createNonContigMapWithNode ( const ArrayView< const GlobalOrdinal > &  elementList,
const RCP< const Teuchos::Comm< int > > &  comm,
const RCP< Node > &  node 
) [related]

Non-member constructor for a non-contiguous Map with a user-specified Kokkos Node.

The Map is configured to use zero-based indexing.

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

Non-member constructor for a contiguous Map with user-defined weights and a user-specified Kokkos Node.

The Map is configured to use zero-based indexing.

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

Creates a one-to-one version of the given Map where each GID is owned by only one process.

The user must guarantee there are no duplicate GID on the same processor. Unexepected behavior may result.

template<class LocalOrdinal , class GlobalOrdinal , class Node >
bool operator== ( const Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node > &  map1,
const Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node > &  map2 
) [related]

True if map1 is the same as (in the sense of isSameAs()) map2, else false.

Definition at line 782 of file Tpetra_Map_decl.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >
bool operator!= ( const Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node > &  map1,
const Tpetra::Map< LocalOrdinal, GlobalOrdinal, Node > &  map2 
) [related]

True if map1 is not the same as (in the sense of isSameAs()) map2, else false.

Definition at line 789 of file Tpetra_Map_decl.hpp.


The documentation for this class was generated from the following file:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines