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.

Public Types
typedef Map< LocalOrdinal, GlobalOrdinal, Node >	map_type
	Type of the Map specialization to give to the constructor. More...

Public Member Functions
Constructors/Destructor.
	Directory ()
	Default constructor: the only one you should use. More...
	~Directory ()
	Destructor. More...
void	initialize (const map_type &map)
	Initialize the Directory with its Map. More...
void	initialize (const map_type &map, const Tpetra::Details::TieBreak< LocalOrdinal, GlobalOrdinal > &tieBreak)
	Initialize the Directory, with its Map and a TieBreak object. More...
bool	initialized () const
	Whether the Directory is initialized. More...
Implementation of Teuchos::Describable.
Clone the Directory for a different Node type, using a cloned Map. Warning This is an advanced method for use by experts only. Template Parameters Node2 Kokkos Node type, possibly different from Node (the third template parameter of this class). Parameters clone_map [in] The result of calling the clone() method on the original Map given to this instance's constructor. "Clone" in this case means make a shallow copy of the data, except for the Kokkos Node instance, which is distinct (and may even have a different type). Both Map and Directory provide clone(). Cloning is much faster than creating a Map or Directory with exactly the same data but a different Node instance. It is useful for creating a copy of a Tpetra object such as a MultiVector or CrsMatrix (distributed over a given Map) for a different Kokkos Node type, for example if creating a host (CPU) copy of a device (GPU) object.
std::string	description () const
	A one-line human-readable description of this object. More...
Query methods.
LookupStatus	getDirectoryEntries (const map_type &map, 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. More...
LookupStatus	getDirectoryEntries (const map_type &map, 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. More...
bool	isOneToOne (const map_type &map) const
	Whether the Directory's input Map is (globally) one to one. More...

Detailed Description

template<class LocalOrdinal, class GlobalOrdinal, class Node>
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	The type of local indices. See the documentation of Map for requirements.
GlobalOrdinal	The type of global indices. See the documentation of Map for requirements.
Node	The Kokkos Node type. See the documentation of Map for requirements.

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 four 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. The Directory gets 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, contiguous, and uniform, the Directory computes a global ID's process ID and local ID on that process using a simple mathematical formula. This requires arithmetic operations per global ID, and no additional storage (beyond what the Map already stores).
3. If the user's Map is distributed, contiguous, but not uniform, then the Directory builds 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+1 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).
4. If the user's Map is distributed and noncontiguous, then the Directory must store a general mapping from global ID to (process ID, local ID). It can't afford to store the whole mapping redundantly on all processes, so the Directory distributes it using another Map (the "directory Map"). This is a contiguous uniform 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

To Tpetra developers: As of fall 2013, Directory no longer keeps a reference to the Map that created it. This will facilitate Tpetra's port to use (new) Kokkos data structures and handle semantics, by removing this circular dependency.

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 126 of file Tpetra_Directory_decl.hpp.

Member Typedef Documentation

template<class LocalOrdinal, class GlobalOrdinal, class Node>

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 129 of file Tpetra_Directory_decl.hpp.

Constructor & Destructor Documentation

template<class LO , class GO , class NT >

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

(

)

Default constructor: the only one you should use.

To initialize the Directory, call the appropriate initialize() overload.

Definition at line 53 of file Tpetra_Directory_def.hpp.

template<class LO , class GO , class NT >

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

(

)

Destructor.

Definition at line 58 of file Tpetra_Directory_def.hpp.

Member Function Documentation

template<class LocalOrdinal, class GlobalOrdinal, class Node>

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

(

const map_type &

map

)

Initialize the Directory with its Map.

template<class LocalOrdinal, class GlobalOrdinal, class Node>

void Tpetra::Directory< LocalOrdinal, GlobalOrdinal, Node >::initialize	(	const map_type &	map,
		const Tpetra::Details::TieBreak< LocalOrdinal, GlobalOrdinal > &	tieBreak
	)

Initialize the Directory, with its Map and a TieBreak object.

template<class LO , class GO , class NT >

bool Tpetra::Directory< LO, GO, NT >::initialized

(

)

const

Whether the Directory is initialized.

Definition at line 67 of file Tpetra_Directory_def.hpp.

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 270 of file Tpetra_Directory_def.hpp.

template<class LocalOrdinal, class GlobalOrdinal, class Node>

LookupStatus Tpetra::Directory< LocalOrdinal, GlobalOrdinal, Node >::getDirectoryEntries	(	const map_type &	map,
		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

map	[in] The Map given to this Directory instance's constructor.
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 std::runtime_error.

template<class LocalOrdinal, class GlobalOrdinal, class Node>

LookupStatus Tpetra::Directory< LocalOrdinal, GlobalOrdinal, Node >::getDirectoryEntries	(	const map_type &	map,
		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

map	[in] The Map given to this Directory instance's constructor.
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 std::runtime_error.

template<class LocalOrdinal, class GlobalOrdinal, class Node>

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

(

const map_type &

map

)

const

Whether the Directory's input Map is (globally) one to one.

This method should always be treated as a collective on all processes in the given Map's communicator, which must be the same as the input Map's communicator. Not all implementations necessarily communicate.

---

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

• Tpetra_Directory_decl.hpp
• Tpetra_Directory_def.hpp