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.
Public Member Functions
Constructors/Destructor.
TEUCHOS_DEPRECATED	Directory (const map_type &map)
	Constructor.
TEUCHOS_DEPRECATED	Directory (const map_type &map, const Tpetra::Details::TieBreak< LocalOrdinal, GlobalOrdinal > &tie_break)
	Constructor (using a tie break class to decide ownership).
TEUCHOS_DEPRECATED	Directory (const Teuchos::RCP< const map_type > &map)
	Constructor (preserved for backwards compatibility with 11.4).
	Directory ()
	Default constructor: the only one you should use.
	~Directory ()
	Destructor.
void	initialize (const map_type &map)
	Initialize the Directory with its Map.
void	initialize (const map_type &map, const Tpetra::Details::TieBreak< LocalOrdinal, GlobalOrdinal > &tieBreak)
	Initialize the Directory, with its Map and a TieBreak object.
bool	initialized () const
	Whether the Directory is initialized.
template<class Node2 >
RCP< Directory< LocalOrdinal, GlobalOrdinal, Node2 > >	clone (const Map< LocalOrdinal, GlobalOrdinal, Node2 > &clone_map) const
	Clone the Directory for a different Node type, using a cloned Map.
Implementation of Teuchos::Describable.
std::string	description () const
	A one-line human-readable description of this object.
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.
LookupStatus TEUCHOS_DEPRECATED	getDirectoryEntries (const Teuchos::ArrayView< const GlobalOrdinal > &globalIDs, const Teuchos::ArrayView< int > &nodeIDs) const
	DEPRECATED method; does not work.
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.
LookupStatus TEUCHOS_DEPRECATED	getDirectoryEntries (const Teuchos::ArrayView< const GlobalOrdinal > &globalIDs, const Teuchos::ArrayView< int > &nodeIDs, const Teuchos::ArrayView< LocalOrdinal > &localIDs) const
	DEPRECATED method; does not work.
bool	isOneToOne (const map_type &map) const
	Whether the Directory's input Map is (globally) one to one.

Detailed Description

template<class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>
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 $O(1)$ 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 127 of file Tpetra_Directory_decl.hpp.

Member Typedef Documentation

template<class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>

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

Constructor & Destructor Documentation

template<class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>

TEUCHOS_DEPRECATED Tpetra::Directory< LocalOrdinal, GlobalOrdinal, Node >::Directory ( 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 LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>

TEUCHOS_DEPRECATED Tpetra::Directory< LocalOrdinal, GlobalOrdinal, Node >::Directory	(	const map_type &	map,
		const Tpetra::Details::TieBreak< LocalOrdinal, GlobalOrdinal > &	tie_break
	)		`[explicit]`

Constructor (using a tie break class to decide ownership).

Parameters:

map	[in] The Map object for which to create the Directory.
tie_break	[in] A TieBreak instance to determine ownership.

Note:: This constructor is NOT invoked by Map's constructor, and for now only works with noncontiguous Maps.

template<class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>

TEUCHOS_DEPRECATED Tpetra::Directory< LocalOrdinal, GlobalOrdinal, Node >::Directory ( const Teuchos::RCP< const map_type > & map ) [explicit]

Constructor (preserved for backwards compatibility with 11.4).

This constructor is DEPRECATED. Please use the constructor that takes a const map_type&.

template<class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>

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

Default constructor: the only one you should use.

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

template<class LO , class GO , class NT >

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

Destructor.

Definition at line 101 of file Tpetra_Directory_def.hpp.

Member Function Documentation

template<class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>

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

Initialize the Directory with its Map.

template<class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>

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

template<class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>

template<class Node2 >

RCP<Directory<LocalOrdinal,GlobalOrdinal,Node2> > Tpetra::Directory< LocalOrdinal, GlobalOrdinal, Node >::clone ( const Map< LocalOrdinal, GlobalOrdinal, Node2 > & clone_map ) const [inline]

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.

Definition at line 201 of file Tpetra_Directory_decl.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 339 of file Tpetra_Directory_def.hpp.

template<class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>

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 = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>

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

DEPRECATED method; does not work.

This method only exists so that the 11.4 backwards compatibility build passes. This method does NOT succeed. It throws an exception on all calling processes, in fact.

template<class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>

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 = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>

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

DEPRECATED method; does not work.

This method only exists so that the 11.4 backwards compatibility build passes. This method does NOT succeed. It throws an exception on all calling processes, in fact.

template<class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>

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:

Public Types

Public Member Functions

Detailed Description

template<class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type> class Tpetra::Directory< LocalOrdinal, GlobalOrdinal, Node >

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

template<class LocalOrdinal = Map<>::local_ordinal_type, class GlobalOrdinal = typename Map<LocalOrdinal>::global_ordinal_type, class Node = typename Map<LocalOrdinal, GlobalOrdinal>::node_type>
class Tpetra::Directory< LocalOrdinal, GlobalOrdinal, Node >