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>

Inherits Describable.

List of all members.

Public Types
typedef Map< LocalOrdinal, GlobalOrdinal, Node >	map_type
	Type of the Map specialization to give to the constructor.
Public Member Functions
Constructors/Destructor.
	Directory (const Teuchos::RCP< const map_type > &map)
	Constructor.
	~Directory ()
	Destructor.
Implementation of Teuchos::Describable.
std::string	description () const
	A one-line human-readable description of this object.
Query methods.
LookupStatus	getDirectoryEntries (const Teuchos::ArrayView< const GlobalOrdinal > &globalIDs, const Teuchos::ArrayView< int > &nodeIDs) const
	Given a global ID 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 global ID list, return a list of their owning process IDs and their corresponding local IDs.

---

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. If using this with a Map, the template parameters of Directory should always be the same as the template parameters of Map.

Template Parameters:

LocalOrdinal	Same as Map's LocalOrdinal template parameter. The type of local IDs.
GlobalOrdinal	Same as Map's GlobalOrdinal template parameter. The type of global IDs. Defaults to the same type as LocalOrdinal.
Node	Same as Map's Node template parameter. Defaults to the default Kokkos Node type.

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 ( entries in the array 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 contiguous Map whose keys are the global IDs. (Contiguity of the directory Map prevents infinite corecursion between Map's constructor and Directory's constructor.)

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.

(mfh 10 May 2012) To Tpetra developers: The current design of Directory is suboptimal. Currently, the Directory has to ask the Map what kind of Map it is (e.g., globally distributed? contiguous?) in order to figure out how to represent its data. This is suboptimal, because the Map already knows what kind of Map it is, based on which Map constructor was invoked. Thus, it should be the Map that specifies which kind of Directory to create. I've broken up Directory into an interface and an implementation (Details::Directory and its subclasses) in preparation for making this change.

Definition at line 131 of file Tpetra_Directory_decl.hpp.

---

Member Typedef Documentation

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

typedef Map<LocalOrdinal, GlobalOrdinal, Node> Tpetra::Directory< LocalOrdinal, GlobalOrdinal, Node >::map_type

Type of the Map specialization to give to the constructor.

Definition at line 134 of file Tpetra_Directory_decl.hpp.

---

Constructor & Destructor Documentation

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

Tpetra::Directory< LocalOrdinal, GlobalOrdinal, Node >::Directory

(

const Teuchos::RCP< const map_type > &

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.

template<class LO , class GO , class NT >

Tpetra::Directory< LO, GO, NT >::~Directory

(

)

Destructor.

Definition at line 89 of file Tpetra_Directory_def.hpp.

---

Member Function Documentation

template<class LO , class GO , class NT >

std::string Tpetra::Directory< LO, GO, NT >::description

(

)

const

A one-line human-readable description of this object.

Definition at line 114 of file Tpetra_Directory_def.hpp.

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

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

Given a global ID 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 global IDs 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 global ID 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.

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

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 global ID list, return a list of their owning process IDs and their corresponding local IDs.

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 global IDs 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 global ID 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.

---

The documentation for this class was generated from the following files:

• Tpetra_Directory_decl.hpp
• Tpetra_Directory_def.hpp