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

Implement mapping from global ID to process ID and local ID. More...

#include <Tpetra_Directory_decl.hpp>

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

List of all members.

Public Member Functions

Constructors/Destructor.
 Directory (const Teuchos::RCP< const Map< LocalOrdinal, GlobalOrdinal, Node > > &map)
 Constructor.
 ~Directory ()
 Destructor.
Query methods.
LookupStatus getDirectoryEntries (const Teuchos::ArrayView< const GlobalOrdinal > &globalIDs, const Teuchos::ArrayView< int > &nodeIDs) const
 Given a GID list, return the list of their owning process IDs.
LookupStatus getDirectoryEntries (const Teuchos::ArrayView< const GlobalOrdinal > &globalIDs, const Teuchos::ArrayView< int > &nodeIDs, const Teuchos::ArrayView< LocalOrdinal > &localIDs) const
 Given a GID list, return a list of their owning process IDs and their corresponding LIDs.

Detailed Description

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

Implement mapping from global ID to process ID and local ID.

This class is an implementation detail of Map. It is mainly of interest to Tpetra developers and does not normally appear in users' code.

Directory implements looking up the process IDs and local IDs corresponding to a given list of global IDs. Each Map owns a Directory object that does this. Map::getRemoteIndexList() calls the Map's directory's getDirectoryEntries() method directly. Directory has three different ways to perform this lookup, depending on the kind of Map.

1. If the user's Map is not distributed (i.e., is serial or locally replicated), then my process ID is the process ID for all global IDs. I can get the local ID (if requested) directly from the user's Map via its getLocalElement() method (which requires no communication).

2. If the user's Map is distributed but contiguous, then I build an array (replicated on all processes) that maps from each process ID to the minimum global ID that it owns. This trades time and communication for space ( $P + O(1)$ entries if there are P processes in the communicator), in that it allows lookups without communication (once the array has been built).

3. If the user's Map is distributed and noncontiguous, then I have to store a general mapping from global ID to (process ID, local ID). I can't afford to store the whole mapping redundantly on all processes, so I distribute it using another Map (the "directory Map"). This is a uniform linear Map whose keys are the global IDs.

This class is templated on the same LocalOrdinal and GlobalOrdinal types on which Map is templated. Just as with Map, the LocalOrdinal type defaults to int if omitted. The GlobalOrdinal type defaults to the LocalOrdinal type, and the Node type defaults to Kokkos' default node type.

Note:
(mfh 04 Jan 2012) To Epetra developers: This class corresponds roughly to Epetra_Directory or Epetra_BasicDirectory. Epetra_BlockMap creates its Epetra_Directory object on demand whenever the map's RemoteIDList() method is called. Tpetra::Map's getRemoteIndexList() method assumes that the map's directory already exists. Epetra_Directory is an abstract interface with one implementation (Epetra_BasicDirectory); Tpetra::Directory is a concrete implementation.

Definition at line 103 of file Tpetra_Directory_decl.hpp.


Constructor & Destructor Documentation

template<class LocalOrdinal , class GlobalOrdinal , class Node >
Tpetra::Directory< LocalOrdinal, GlobalOrdinal, Node >::Directory ( const Teuchos::RCP< const Map< LocalOrdinal, GlobalOrdinal, Node > > &  map) [explicit]

Constructor.

Parameters:
map[in] The Map object for which to create the Directory.
Note:
This constructor is invoked by Map's constructor, using the Map's this pointer as the input argument.

Definition at line 57 of file Tpetra_Directory_def.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >
Tpetra::Directory< LocalOrdinal, GlobalOrdinal, Node >::~Directory ( )

Destructor.

Definition at line 85 of file Tpetra_Directory_def.hpp.


Member Function Documentation

template<class LocalOrdinal , class GlobalOrdinal , class Node >
LookupStatus Tpetra::Directory< LocalOrdinal, GlobalOrdinal, Node >::getDirectoryEntries ( const Teuchos::ArrayView< const GlobalOrdinal > &  globalIDs,
const Teuchos::ArrayView< int > &  nodeIDs 
) const

Given a GID list, return the list of their owning process IDs.

Given a list globalIDs of global identifiers (GIDs), return the corresponding list nodeIDs of the process ranks which own those GIDs. Tpetra uses this to figure out the locations of nonlocal Map entries.

Parameters:
globalIDs[in] List of GIDs to look up.
nodeIDs[out] On input, an array view with the same number of entries as globalIDs. On output, nodeIDs[i] is the ID of the process which owns globalIDs[i]. If globalIDs[i] is not present in the directory (i.e., is not owned by any process in the Directory's communicator), nodeIDs[i] is -1.
Returns:
If at least one GID was not present in the directory, return IDNotPresent. Otherwise, return AllIDsPresent.
Note:
If nodeIDs.size() != globalIDs.size(), then this method throws a std::runtime_error exception.

Definition at line 88 of file Tpetra_Directory_def.hpp.

template<class LocalOrdinal , class GlobalOrdinal , class Node >
LookupStatus Tpetra::Directory< LocalOrdinal, GlobalOrdinal, Node >::getDirectoryEntries ( const Teuchos::ArrayView< const GlobalOrdinal > &  globalIDs,
const Teuchos::ArrayView< int > &  nodeIDs,
const Teuchos::ArrayView< LocalOrdinal > &  localIDs 
) const

Given a GID list, return a list of their owning process IDs and their corresponding LIDs.

Given a list globalIDs of global identifiers (GIDs), return the corresponding list nodeIDs of the process ranks which own those GIDs, as well as the list of the local identifiers (LIDs). Tpetra uses this to figure out the locations of nonlocal Map entries.

Parameters:
globalIDs[in] List of GIDs to look up.
nodeIDs[out] On input, an array view with the same number of entries as globalIDs. On output, nodeIDs[i] is the ID of the process which owns globalIDs[i]. If globalIDs[i] is not present in the directory (i.e., is not owned by any process in the Directory's communicator), then nodeIDs[i] == -1.
localIDs[out] On input, an array view with the same number of entries as globalIDs. On output, localIDs[i] is the local identifier corresponding to the global identifier globalIDs[i]. If globalIDs[i] is not present in the directory, then localIDs[i] == Teuchos::OrdinalTraits<LocalOrdinal>::invalid().
Returns:
If at least one GID was not present in the directory, return IDNotPresent. Otherwise, return AllIDsPresent.
Note:
If nodeIDs.size() != globalIDs.size() or localIDs.size() != globalIDs.size(), then this method throws a std::runtime_error exception.

Definition at line 96 of file Tpetra_Directory_def.hpp.


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