Sparse matrix used only for file input / output. More...

#include <Tpetra_Details_CooMatrix.hpp>

Inheritance diagram for Tpetra::Details::CooMatrix< SC, LO, GO, NT >:

Public Types
typedef char	packet_type
	This class transfers data as bytes (MPI_BYTE). More...

typedef SC	scalar_type
	Type of each entry (value) in the sparse matrix. More...

typedef ::Tpetra::Map< local_ordinal_type, global_ordinal_type, node_type >	map_type
	Type of the Map specialization to give to the constructor. More...

Typedefs
typedef device_type::execution_space	execution_space
	The Kokkos execution space. More...

Public Member Functions
	CooMatrix ()
	Default constructor. More...

	CooMatrix (const ::Teuchos::RCP< const map_type > &map)
	Constructor that takes a Map. More...

virtual	~CooMatrix ()
	Destructor (virtual for memory safety of derived classes). More...

void	sumIntoGlobalValue (const GO gblRowInd, const GO gblColInd, const SC &val)
	Insert one entry locally into the sparse matrix, if it does not exist there yet. If it does exist, sum the values. More...

void	sumIntoGlobalValues (const GO gblRowInds[], const GO gblColInds[], const SC vals[], const std::size_t numEnt)
	Insert multiple entries locally into the sparse matrix. More...

void	sumIntoGlobalValues (std::initializer_list< GO > gblRowInds, std::initializer_list< GO > gblColInds, std::initializer_list< SC > vals, const std::size_t numEnt)
	Initializer-list overload of the above method (which see). More...

std::size_t	getLclNumEntries () const
	Number of entries in the sparse matrix on the calling process. More...

void	fillComplete (const ::Teuchos::RCP< const ::Teuchos::Comm< int > > &comm)
	Tell the matrix that you are done inserting entries locally, and that the matrix should build its Map now. More...

void	fillComplete ()
	Special version of fillComplete that assumes that the matrix already has a Map, and reuses its communicator to create a new Map. More...

bool	localError () const
	Whether this object had an error on the calling process. More...

std::string	errorMessages () const
	The current stream of error messages. More...

virtual std::string	description () const
	One-line descriptiion of this object; overrides Teuchos::Describable method. More...

virtual void	describe (Teuchos::FancyOStream &out, const Teuchos::EVerbosityLevel verbLevel=Teuchos::Describable::verbLevel_default) const
	Print a descriptiion of this object to the given output stream; overrides Teuchos::Describable method. More...

Public methods for redistributing data
void	doImport (const SrcDistObject &source, const Import< LO, GO, NT > &importer, CombineMode CM)
	Import data into this object using an Import object ("forward mode"). More...

void	doImport (const SrcDistObject &source, const Export< LO, GO, NT > &exporter, CombineMode CM)
	Import data into this object using an Export object ("reverse mode"). More...

void	doExport (const SrcDistObject &source, const Export< LO, GO, NT > &exporter, CombineMode CM)
	Export data into this object using an Export object ("forward mode"). More...

void	doExport (const SrcDistObject &source, const Import< LO, GO, NT > &importer, CombineMode CM)
	Export data into this object using an Import object ("reverse mode"). More...

Attribute accessor methods
bool	isDistributed () const
	Whether this is a globally distributed object. More...

virtual Teuchos::RCP< const map_type >	getMap () const
	The Map describing the parallel distribution of this object. More...

I/O methods
void	print (std::ostream &os) const
	Print this object to the given output stream. More...

Methods for use only by experts
virtual void	removeEmptyProcessesInPlace (const Teuchos::RCP< const map_type > &newMap)
	Remove processes which contain no entries in this object's Map. More...

Protected Types
enum	ReverseOption
	Whether the data transfer should be performed in forward or reverse mode. More...

Protected Member Functions
virtual size_t	constantNumberOfPackets () const
	By returning 0, tell DistObject that this class may not necessarily have a constant number of "packets" per local index. More...

virtual bool	checkSizes (const ::Tpetra::SrcDistObject &source)
	Compare the source and target (this) objects for compatibility. More...

virtual bool	useNewInterface ()
	Whether the subclass implements the "old" or "new" (Kokkos-friendly) interface (it implements the "new" interface). More...

virtual void	copyAndPermuteNew (const ::Tpetra::SrcDistObject &sourceObject, const size_t numSameIDs, const ::Kokkos::DualView< const LO , device_type > &permuteToLIDs, const ::Kokkos::DualView< const LO , device_type > &permuteFromLIDs)
	While we do use the "new" Kokkos::DualView - based interface, we don't currently use device Views. More...

virtual void	packAndPrepareNew (const ::Tpetra::SrcDistObject &sourceObject, const ::Kokkos::DualView< const local_ordinal_type , device_type > &exportLIDs, ::Kokkos::DualView< packet_type , device_type > &exports, const ::Kokkos::DualView< size_t *, device_type > &numPacketsPerLID, size_t &constantNumPackets, ::Tpetra::Distributor &)
	While we do use the "new" Kokkos::DualView - based interface, we don't currently use device Views. More...

virtual void	unpackAndCombineNew (const ::Kokkos::DualView< const local_ordinal_type , device_type > &importLIDs, const ::Kokkos::DualView< const packet_type , device_type > &imports, const ::Kokkos::DualView< const size_t *, device_type > &numPacketsPerLID, const size_t, ::Tpetra::Distributor &, const ::Tpetra::CombineMode)
	While we do use the "new" Kokkos::DualView - based interface, we don't currently use device Views. More...

virtual void	doTransfer (const SrcDistObject &src, CombineMode CM, size_t numSameIDs, const Teuchos::ArrayView< const local_ordinal_type > &permuteToLIDs, const Teuchos::ArrayView< const local_ordinal_type > &permuteFromLIDs, const Teuchos::ArrayView< const local_ordinal_type > &remoteLIDs, const Teuchos::ArrayView< const local_ordinal_type > &exportLIDs, Distributor &distor, ReverseOption revOp)
	Redistribute data across memory images. More...

virtual void	createViews () const
	Hook for creating a const view. More...

virtual void	createViewsNonConst (KokkosClassic::ReadWriteOption rwo)
	Hook for creating a nonconst view. More...

virtual void	releaseViews () const
	Hook for releasing views. More...

void	reallocImportsIfNeeded (const size_t newSize, const bool debug=false)
	Reallocate imports_ if needed. More...

Methods implemented by subclasses and used by doTransfer().
The doTransfer() method uses the subclass' implementations of these methods to implement data transfer. Subclasses of DistObject must implement these methods. This is an instance of the Template Method Pattern. ("Template" here doesn't mean "C++ template"; it means "pattern with holes that are filled in by the subclass' method implementations.")
virtual bool	checkSizes (const SrcDistObject &source)=0
	Compare the source and target (this) objects for compatibility. More...

virtual void	copyAndPermute (const SrcDistObject &source, size_t numSameIDs, const Teuchos::ArrayView< const local_ordinal_type > &permuteToLIDs, const Teuchos::ArrayView< const local_ordinal_type > &permuteFromLIDs)
	Perform copies and permutations that are local to this process. More...

virtual void	copyAndPermuteNew (const SrcDistObject &source, const size_t numSameIDs, const Kokkos::DualView< const local_ordinal_type , device_type > &permuteToLIDs, const Kokkos::DualView< const local_ordinal_type , device_type > &permuteFromLIDs)

virtual void	packAndPrepare (const SrcDistObject &source, const Teuchos::ArrayView< const local_ordinal_type > &exportLIDs, Teuchos::Array< packet_type > &exports, const Teuchos::ArrayView< size_t > &numPacketsPerLID, size_t &constantNumPackets, Distributor &distor)
	Perform any packing or preparation required for communication. More...

virtual void	packAndPrepareNew (const SrcDistObject &source, const Kokkos::DualView< const local_ordinal_type , device_type > &exportLIDs, Kokkos::DualView< packet_type , device_type > &exports, const Kokkos::DualView< size_t *, device_type > &numPacketsPerLID, size_t &constantNumPackets, Distributor &distor)

virtual void	unpackAndCombine (const Teuchos::ArrayView< const local_ordinal_type > &importLIDs, const Teuchos::ArrayView< const packet_type > &imports, const Teuchos::ArrayView< size_t > &numPacketsPerLID, size_t constantNumPackets, Distributor &distor, CombineMode CM)
	Perform any unpacking and combining after communication (old version that uses Teuchos memory management classes to hold data). More...

virtual void	unpackAndCombineNew (const Kokkos::DualView< const local_ordinal_type , device_type > &importLIDs, const Kokkos::DualView< const packet_type , device_type > &imports, const Kokkos::DualView< const size_t *, device_type > &numPacketsPerLID, const size_t constantNumPackets, Distributor &distor, const CombineMode CM)
	Perform any unpacking and combining after communication (new version that uses Kokkos data structures to hold data). More...

Protected Attributes
Teuchos::RCP< const map_type >	map_
	The Map over which this object is distributed. More...

Kokkos::DualView< packet_type *, execution_space >	imports_
	Buffer into which packed data are imported (received from other processes). More...

Kokkos::DualView< size_t *, execution_space >	numImportPacketsPerLID_
	Number of packets to receive for each receive operation. More...

Kokkos::DualView< packet_type *, device_type >	exports_
	Buffer from which packed data are exported (sent to other processes). More...

Kokkos::DualView< size_t *, execution_space >	numExportPacketsPerLID_
	Number of packets to send for each send operation. More...

Detailed Description

template<class SC, class LO = ::Tpetra::DistObject<char>::local_ordinal_type, class GO = ::Tpetra::DistObject<char>::global_ordinal_type, class NT = ::Tpetra::DistObject<char>::node_type>
class Tpetra::Details::CooMatrix< SC, LO, GO, NT >

Sparse matrix used only for file input / output.

This class stores a sparse matrix in coordinate format. It is meant only to help file input and output. Thus, it implements DistObject, but does NOT implement RowMatrix or even Operator.

Unlike other DistObject subclasses in Tpetra, this class' constructor need not necessarily take a Map. If the class does NOT have a Map, it builds its Map at fillComplete(), after construction, as a function of the input indices.

Users are only allowed to insert matrix entries if the class does NOT have a Map. Insertion is local to each process. Users insert entries by calling sumIntoGlobalValue(). Each entry is a "triple" consisting of a global row index, a global column index, and a matrix value. Users call fillComplete() when they are done inserting entries. At that point, the object builds its Map. (Unlike CrsMatrix, this class does NOT allow multiple resumeFill() / fillComplete() cycles.)

Once the class has a Map, users may apply DistObject methods like doImport() and doExport() to redistribute the data. The target of an Import or Export must have a Map, and users may not have inserted entries into it.

Here is an example of how to use this class:

Tpetra::Details::CooMatrix<double, int, long long> A_in;
for (size_t k = 0; k < numEntriesToInsert; ++k) {
  long long gblRowInd, gblColInd;
  double val;
  // We don't implement this here.  You have to do it.
  readEntryFromFile (&gblRowInd, &gblColInd, &val);
  A_in.sumIntoGlobalValue (gblRowInd, gblColInd, val);
}
// You are responsible for supplying the output matrix's
// communicator and Map.
A_in.fillComplete (comm);
Teuchos::RCP<const Tpetra::Map<int, long long> > outMap = ...;
Tpetra::Details::CooMatrix<double, int, long long> A_out (rowMap);
Tpetra::Export<int, long long> exporter (A_in.getMap (), outMap);
A_out.doExport (A_in, exporter, Tpetra::ADD);

Definition at line 573 of file Tpetra_Details_CooMatrix.hpp.

Member Typedef Documentation

◆ packet_type

template<class SC, class LO = ::Tpetra::DistObject<char>::local_ordinal_type, class GO = ::Tpetra::DistObject<char>::global_ordinal_type, class NT = ::Tpetra::DistObject<char>::node_type>

typedef char Tpetra::Details::CooMatrix< SC, LO, GO, NT >::packet_type

This class transfers data as bytes (MPI_BYTE).

Definition at line 576 of file Tpetra_Details_CooMatrix.hpp.

◆ scalar_type

template<class SC, class LO = ::Tpetra::DistObject<char>::local_ordinal_type, class GO = ::Tpetra::DistObject<char>::global_ordinal_type, class NT = ::Tpetra::DistObject<char>::node_type>

typedef SC Tpetra::Details::CooMatrix< SC, LO, GO, NT >::scalar_type

Type of each entry (value) in the sparse matrix.

Definition at line 578 of file Tpetra_Details_CooMatrix.hpp.

◆ map_type

template<class SC, class LO = ::Tpetra::DistObject<char>::local_ordinal_type, class GO = ::Tpetra::DistObject<char>::global_ordinal_type, class NT = ::Tpetra::DistObject<char>::node_type>

typedef ::Tpetra::Map<local_ordinal_type, global_ordinal_type, node_type> Tpetra::Details::CooMatrix< SC, LO, GO, NT >::map_type

Type of the Map specialization to give to the constructor.

Definition at line 584 of file Tpetra_Details_CooMatrix.hpp.

◆ execution_space

typedef device_type::execution_space Tpetra::DistObject< char , LO , GO , NT , NT ::classic >::execution_space

inherited

The Kokkos execution space.

Definition at line 235 of file Tpetra_DistObject_decl.hpp.

Member Enumeration Documentation

◆ ReverseOption

enum Tpetra::DistObject::ReverseOption

protectedinherited

Whether the data transfer should be performed in forward or reverse mode.

"Reverse mode" means calling doExport() with an Import object, or calling doImport() with an Export object. "Forward mode" means calling doExport() with an Export object, or calling doImport() with an Import object.

Definition at line 477 of file Tpetra_DistObject_decl.hpp.

Constructor & Destructor Documentation

◆ CooMatrix() [1/2]

template<class SC, class LO = ::Tpetra::DistObject<char>::local_ordinal_type, class GO = ::Tpetra::DistObject<char>::global_ordinal_type, class NT = ::Tpetra::DistObject<char>::node_type>

Tpetra::Details::CooMatrix< SC, LO, GO, NT >::CooMatrix ( )

inline

Default constructor.

This creates the object with a null Map. Users may insert entries into this object, until they call fillComplete. This object may NOT be the target of an Import or Export operation.

Definition at line 600 of file Tpetra_Details_CooMatrix.hpp.

◆ CooMatrix() [2/2]

template<class SC, class LO = ::Tpetra::DistObject<char>::local_ordinal_type, class GO = ::Tpetra::DistObject<char>::global_ordinal_type, class NT = ::Tpetra::DistObject<char>::node_type>

Tpetra::Details::CooMatrix< SC, LO, GO, NT >::CooMatrix ( const ::Teuchos::RCP< const map_type > & map )

inline

Constructor that takes a Map.

Parameters

map	[in] Input Map.

If map is nonnull, then users may use this object ONLY as the target of an Import or Export operation. They may NOT insert entries into it.

Definition at line 613 of file Tpetra_Details_CooMatrix.hpp.

◆ ~CooMatrix()

template<class SC, class LO = ::Tpetra::DistObject<char>::local_ordinal_type, class GO = ::Tpetra::DistObject<char>::global_ordinal_type, class NT = ::Tpetra::DistObject<char>::node_type>

virtual Tpetra::Details::CooMatrix< SC, LO, GO, NT >::~CooMatrix ( )

inlinevirtual

Destructor (virtual for memory safety of derived classes).

Definition at line 620 of file Tpetra_Details_CooMatrix.hpp.

Member Function Documentation

◆ sumIntoGlobalValue()

template<class SC, class LO = ::Tpetra::DistObject<char>::local_ordinal_type, class GO = ::Tpetra::DistObject<char>::global_ordinal_type, class NT = ::Tpetra::DistObject<char>::node_type>

void Tpetra::Details::CooMatrix< SC, LO, GO, NT >::sumIntoGlobalValue	(	const GO	gblRowInd,
		const GO	gblColInd,
		const SC &	val
	)

inline

Insert one entry locally into the sparse matrix, if it does not exist there yet. If it does exist, sum the values.

Parameters

gblRowInd	[in] Global row index of the entry to insert.
gblColInd	[in] Global column index of the entry to insert.
val	[in] Value of the matrix entry to insert / sum.

Definition at line 629 of file Tpetra_Details_CooMatrix.hpp.

◆ sumIntoGlobalValues() [1/2]

template<class SC, class LO = ::Tpetra::DistObject<char>::local_ordinal_type, class GO = ::Tpetra::DistObject<char>::global_ordinal_type, class NT = ::Tpetra::DistObject<char>::node_type>

void Tpetra::Details::CooMatrix< SC, LO, GO, NT >::sumIntoGlobalValues	(	const GO	gblRowInds[],
		const GO	gblColInds[],
		const SC	vals[],
		const std::size_t	numEnt
	)

inline

Insert multiple entries locally into the sparse matrix.

This works like multiple calls to sumIntoGlobalValue.

Parameters

gblRowInd	[in] Global row indices of the entries to insert.
gblColInd	[in] Global column indices of the entries to insert.
val	[in] Values of the matrix entries to insert / sum.
numEnt	[in] Number of entries to insert.

Definition at line 645 of file Tpetra_Details_CooMatrix.hpp.

◆ sumIntoGlobalValues() [2/2]

template<class SC, class LO = ::Tpetra::DistObject<char>::local_ordinal_type, class GO = ::Tpetra::DistObject<char>::global_ordinal_type, class NT = ::Tpetra::DistObject<char>::node_type>

void Tpetra::Details::CooMatrix< SC, LO, GO, NT >::sumIntoGlobalValues	(	std::initializer_list< GO >	gblRowInds,
		std::initializer_list< GO >	gblColInds,
		std::initializer_list< SC >	vals,
		const std::size_t	numEnt
	)

inline

Initializer-list overload of the above method (which see).

Definition at line 655 of file Tpetra_Details_CooMatrix.hpp.

◆ getLclNumEntries()

template<class SC, class LO = ::Tpetra::DistObject<char>::local_ordinal_type, class GO = ::Tpetra::DistObject<char>::global_ordinal_type, class NT = ::Tpetra::DistObject<char>::node_type>

std::size_t Tpetra::Details::CooMatrix< SC, LO, GO, NT >::getLclNumEntries ( ) const

inline

Number of entries in the sparse matrix on the calling process.

Definition at line 666 of file Tpetra_Details_CooMatrix.hpp.

◆ fillComplete() [1/2]

template<class SC, class LO = ::Tpetra::DistObject<char>::local_ordinal_type, class GO = ::Tpetra::DistObject<char>::global_ordinal_type, class NT = ::Tpetra::DistObject<char>::node_type>

void Tpetra::Details::CooMatrix< SC, LO, GO, NT >::fillComplete ( const ::Teuchos::RCP< const ::Teuchos::Comm< int > > & comm )

inline

Tell the matrix that you are done inserting entries locally, and that the matrix should build its Map now.

This is the preferred version of fillComplete().

Precondition: The matrix does not yet have a Map.; fillComplete() has never been called before on this object.

Postcondition: The matrix has a Map.

Parameters

comm	[in] Input communicator to use for the Map.

Definition at line 716 of file Tpetra_Details_CooMatrix.hpp.

◆ fillComplete() [2/2]

template<class SC, class LO = ::Tpetra::DistObject<char>::local_ordinal_type, class GO = ::Tpetra::DistObject<char>::global_ordinal_type, class NT = ::Tpetra::DistObject<char>::node_type>

void Tpetra::Details::CooMatrix< SC, LO, GO, NT >::fillComplete ( )

inline

Special version of fillComplete that assumes that the matrix already has a Map, and reuses its communicator to create a new Map.

DO NOT call this method unless you know what you are doing.

Precondition: The matrix DOES have a (nonnull) Map with a nonnull communicator.

Definition at line 735 of file Tpetra_Details_CooMatrix.hpp.

◆ localError()

template<class SC, class LO = ::Tpetra::DistObject<char>::local_ordinal_type, class GO = ::Tpetra::DistObject<char>::global_ordinal_type, class NT = ::Tpetra::DistObject<char>::node_type>

bool Tpetra::Details::CooMatrix< SC, LO, GO, NT >::localError ( ) const

inline

Whether this object had an error on the calling process.

Import and Export operations using this object as the target of the Import or Export may incur local errors, for example due to invalid rows or incorrectly sized data. On local error detection, we don't want to throw an exception right away, because not all processes may throw an exception; this inconsistency across processes can result in deadlock or put Tpetra in an incorrect state. Instead, we set a local error flag on the affected process, and ignore the incorrect data. If you want to check whether any process experienced an error, you must do a reduction or all-reduce over this flag. Every time you initiate a new Import or Export with this object as the target, we clear this flag.

Definition at line 759 of file Tpetra_Details_CooMatrix.hpp.

◆ errorMessages()

template<class SC, class LO = ::Tpetra::DistObject<char>::local_ordinal_type, class GO = ::Tpetra::DistObject<char>::global_ordinal_type, class NT = ::Tpetra::DistObject<char>::node_type>

std::string Tpetra::Details::CooMatrix< SC, LO, GO, NT >::errorMessages ( ) const

inline

The current stream of error messages.

This is only nonempty on the calling process if localError() returns true. In that case, it stores a stream of human-readable, endline-separated error messages encountered during an Import or Export cycle. Every time you initiate a new Import or Export with this object as the target, we clear this stream.

If you want to print this, you are responsible for ensuring that it is valid for the calling MPI process to print to whatever output stream you use. On some MPI implementations, you may need to send the string to Process 0 in MPI_COMM_WORLD for printing.

Note to developers: we clear the stream at the beginning of checkSizes().

Definition at line 780 of file Tpetra_Details_CooMatrix.hpp.

◆ description()

template<class SC, class LO = ::Tpetra::DistObject<char>::local_ordinal_type, class GO = ::Tpetra::DistObject<char>::global_ordinal_type, class NT = ::Tpetra::DistObject<char>::node_type>

virtual std::string Tpetra::Details::CooMatrix< SC, LO, GO, NT >::description ( ) const

inlinevirtual

One-line descriptiion of this object; overrides Teuchos::Describable method.

Reimplemented from Tpetra::DistObject< char, LO, GO, NT >.

Definition at line 822 of file Tpetra_Details_CooMatrix.hpp.

◆ describe()

template<class SC, class LO = ::Tpetra::DistObject<char>::local_ordinal_type, class GO = ::Tpetra::DistObject<char>::global_ordinal_type, class NT = ::Tpetra::DistObject<char>::node_type>

virtual void Tpetra::Details::CooMatrix< SC, LO, GO, NT >::describe	(	Teuchos::FancyOStream &	out,
		const Teuchos::EVerbosityLevel	verbLevel = `Teuchos::Describable::verbLevel_default`
	)		const

inlinevirtual

Print a descriptiion of this object to the given output stream; overrides Teuchos::Describable method.

Reimplemented from Tpetra::DistObject< char, LO, GO, NT >.

Definition at line 842 of file Tpetra_Details_CooMatrix.hpp.

◆ constantNumberOfPackets()

template<class SC, class LO = ::Tpetra::DistObject<char>::local_ordinal_type, class GO = ::Tpetra::DistObject<char>::global_ordinal_type, class NT = ::Tpetra::DistObject<char>::node_type>

virtual size_t Tpetra::Details::CooMatrix< SC, LO, GO, NT >::constantNumberOfPackets ( ) const

inlineprotectedvirtual

By returning 0, tell DistObject that this class may not necessarily have a constant number of "packets" per local index.

Reimplemented from Tpetra::DistObject< char, LO, GO, NT >.

Definition at line 966 of file Tpetra_Details_CooMatrix.hpp.

◆ checkSizes() [1/2]

template<class SC, class LO = ::Tpetra::DistObject<char>::local_ordinal_type, class GO = ::Tpetra::DistObject<char>::global_ordinal_type, class NT = ::Tpetra::DistObject<char>::node_type>

virtual bool Tpetra::Details::CooMatrix< SC, LO, GO, NT >::checkSizes ( const ::Tpetra::SrcDistObject & source )

inlineprotectedvirtual

Compare the source and target (this) objects for compatibility.

Returns: True if they are compatible, else false.

Definition at line 974 of file Tpetra_Details_CooMatrix.hpp.

◆ useNewInterface()

template<class SC, class LO = ::Tpetra::DistObject<char>::local_ordinal_type, class GO = ::Tpetra::DistObject<char>::global_ordinal_type, class NT = ::Tpetra::DistObject<char>::node_type>

virtual bool Tpetra::Details::CooMatrix< SC, LO, GO, NT >::useNewInterface ( )

inlineprotectedvirtual

Whether the subclass implements the "old" or "new" (Kokkos-friendly) interface (it implements the "new" interface).

Reimplemented from Tpetra::DistObject< char, LO, GO, NT >.

Definition at line 999 of file Tpetra_Details_CooMatrix.hpp.

◆ copyAndPermuteNew()

template<class SC, class LO = ::Tpetra::DistObject<char>::local_ordinal_type, class GO = ::Tpetra::DistObject<char>::global_ordinal_type, class NT = ::Tpetra::DistObject<char>::node_type>

virtual void Tpetra::Details::CooMatrix< SC, LO, GO, NT >::copyAndPermuteNew	(	const ::Tpetra::SrcDistObject &	sourceObject,
		const size_t	numSameIDs,
		const ::Kokkos::DualView< const LO *, device_type > &	permuteToLIDs,
		const ::Kokkos::DualView< const LO *, device_type > &	permuteFromLIDs
	)

inlineprotectedvirtual

While we do use the "new" Kokkos::DualView - based interface, we don't currently use device Views.

Definition at line 1004 of file Tpetra_Details_CooMatrix.hpp.

◆ packAndPrepareNew()

template<class SC, class LO = ::Tpetra::DistObject<char>::local_ordinal_type, class GO = ::Tpetra::DistObject<char>::global_ordinal_type, class NT = ::Tpetra::DistObject<char>::node_type>

virtual void Tpetra::Details::CooMatrix< SC, LO, GO, NT >::packAndPrepareNew	(	const ::Tpetra::SrcDistObject &	sourceObject,
		const ::Kokkos::DualView< const local_ordinal_type *, device_type > &	exportLIDs,
		::Kokkos::DualView< packet_type *, device_type > &	exports,
		const ::Kokkos::DualView< size_t *, device_type > &	numPacketsPerLID,
		size_t &	constantNumPackets,
		::Tpetra::Distributor &
	)

inlineprotectedvirtual

While we do use the "new" Kokkos::DualView - based interface, we don't currently use device Views.

Definition at line 1200 of file Tpetra_Details_CooMatrix.hpp.

◆ unpackAndCombineNew() [1/2]

template<class SC, class LO = ::Tpetra::DistObject<char>::local_ordinal_type, class GO = ::Tpetra::DistObject<char>::global_ordinal_type, class NT = ::Tpetra::DistObject<char>::node_type>

virtual void Tpetra::Details::CooMatrix< SC, LO, GO, NT >::unpackAndCombineNew	(	const ::Kokkos::DualView< const local_ordinal_type *, device_type > &	importLIDs,
		const ::Kokkos::DualView< const packet_type *, device_type > &	imports,
		const ::Kokkos::DualView< const size_t *, device_type > &	numPacketsPerLID,
		const size_t	,
		::Tpetra::Distributor &	,
		const ::Tpetra::CombineMode
	)

inlineprotectedvirtual

While we do use the "new" Kokkos::DualView - based interface, we don't currently use device Views.

Definition at line 1400 of file Tpetra_Details_CooMatrix.hpp.

◆ doImport() [1/2]

void Tpetra::DistObject< char , LO , GO , NT , NT ::classic >::doImport	(	const SrcDistObject< char, LO, GO, NT > &	source,
		const Import< LO , GO , NT > &	importer,
		CombineMode	CM
	)

inherited

Import data into this object using an Import object ("forward mode").

The input DistObject is always the source of the data redistribution operation, and the *this object is always the target.

If you don't know the difference between forward and reverse mode, then you probably want forward mode. Use this method with your precomputed Import object if you want to do an Import, else use doExport() with a precomputed Export object.

Parameters

source	[in] The "source" object for redistribution.
importer	[in] Precomputed data redistribution plan. Its source Map must be the same as the input DistObject's Map, and its target Map must be the same as `this->getMap()`.
CM	[in] How to combine incoming data with the same global index.

Definition at line 248 of file Tpetra_DistObject_def.hpp.

◆ doImport() [2/2]

void Tpetra::DistObject< char , LO , GO , NT , NT ::classic >::doImport	(	const SrcDistObject< char, LO, GO, NT > &	source,
		const Export< LO , GO , NT > &	exporter,
		CombineMode	CM
	)

inherited

Import data into this object using an Export object ("reverse mode").

The input DistObject is always the source of the data redistribution operation, and the *this object is always the target.

If you don't know the difference between forward and reverse mode, then you probably want forward mode. Use the version of doImport() that takes a precomputed Import object in that case.

Parameters

source	[in] The "source" object for redistribution.
exporter	[in] Precomputed data redistribution plan. Its target Map must be the same as the input DistObject's Map, and its source Map must be the same as `this->getMap()`. (Note the difference from forward mode.)
CM	[in] How to combine incoming data with the same global index.

Definition at line 310 of file Tpetra_DistObject_def.hpp.

◆ doExport() [1/2]

void Tpetra::DistObject< char , LO , GO , NT , NT ::classic >::doExport	(	const SrcDistObject< char, LO, GO, NT > &	source,
		const Export< LO , GO , NT > &	exporter,
		CombineMode	CM
	)

inherited

Export data into this object using an Export object ("forward mode").

The input DistObject is always the source of the data redistribution operation, and the *this object is always the target.

If you don't know the difference between forward and reverse mode, then you probably want forward mode. Use this method with your precomputed Export object if you want to do an Export, else use doImport() with a precomputed Import object.

Parameters

source	[in] The "source" object for redistribution.
exporter	[in] Precomputed data redistribution plan. Its source Map must be the same as the input DistObject's Map, and its target Map must be the same as `this->getMap()`.
CM	[in] How to combine incoming data with the same global index.

Definition at line 279 of file Tpetra_DistObject_def.hpp.

◆ doExport() [2/2]

void Tpetra::DistObject< char , LO , GO , NT , NT ::classic >::doExport	(	const SrcDistObject< char, LO, GO, NT > &	source,
		const Import< LO , GO , NT > &	importer,
		CombineMode	CM
	)

inherited

Export data into this object using an Import object ("reverse mode").

The input DistObject is always the source of the data redistribution operation, and the *this object is always the target.

If you don't know the difference between forward and reverse mode, then you probably want forward mode. Use the version of doExport() that takes a precomputed Export object in that case.

Parameters

source	[in] The "source" object for redistribution.
importer	[in] Precomputed data redistribution plan. Its target Map must be the same as the input DistObject's Map, and its source Map must be the same as `this->getMap()`. (Note the difference from forward mode.)
CM	[in] How to combine incoming data with the same global index.

Definition at line 342 of file Tpetra_DistObject_def.hpp.

◆ isDistributed()

bool Tpetra::DistObject< char , LO , GO , NT , NT ::classic >::isDistributed ( ) const

inherited

Whether this is a globally distributed object.

For a definition of "globally distributed" (and its opposite, "locally replicated"), see the documentation of Map's isDistributed() method.

Definition at line 374 of file Tpetra_DistObject_def.hpp.

◆ getMap()

virtual Teuchos::RCP<const map_type> Tpetra::DistObject< char , LO , GO , NT , NT ::classic >::getMap ( ) const

inlinevirtualinherited

The Map describing the parallel distribution of this object.

Note that some Tpetra objects might be distributed using multiple Map objects. For example, CrsMatrix has both a row Map and a column Map. It is up to the subclass to decide which Map to use when invoking the DistObject constructor.

Definition at line 373 of file Tpetra_DistObject_decl.hpp.

◆ print()

void Tpetra::DistObject< char , LO , GO , NT , NT ::classic >::print ( std::ostream & os ) const

inherited

Print this object to the given output stream.

We generally assume that all MPI processes can print to the given stream.

Definition at line 1224 of file Tpetra_DistObject_def.hpp.

◆ removeEmptyProcessesInPlace()

void Tpetra::DistObject< char , LO , GO , NT , NT ::classic >::removeEmptyProcessesInPlace ( const Teuchos::RCP< const map_type > & newMap )

virtualinherited

Remove processes which contain no entries in this object's Map.

Warning: This method is ONLY for use by experts. We highly recommend using the nonmember function of the same name defined in this file.; We make NO promises of backwards compatibility. This method may change or disappear at any time.

On input, this object is distributed over the Map returned by getMap() (the "original Map," with its communicator, the "original communicator"). The input newMap of this method must be the same as the result of calling getMap()->removeEmptyProcesses(). On processes in the original communicator which contain zero entries ("excluded processes," as opposed to "included processes"), the input newMap must be Teuchos::null (which is what getMap()->removeEmptyProcesses() returns anyway).

On included processes, reassign this object's Map (that would be returned by getMap()) to the input newMap, and do any work that needs to be done to restore correct semantics. On excluded processes, free any data that needs freeing, and do any other work that needs to be done to restore correct semantics.

This method has collective semantics over the original communicator. On exit, the only method of this object which is safe to call on excluded processes is the destructor. This implies that subclasses' destructors must not contain communication operations.

Returns: The object's new Map. Its communicator is a new communicator, distinct from the old Map's communicator, which contains a subset of the processes in the old communicator.

Note: The name differs from Map's method removeEmptyProcesses(), in order to emphasize that the operation on DistObject happens in place, modifying the input, whereas the operation removeEmptyProcess() on Map does not modify the input.; To implementers of DistObject subclasses: The default implementation of this class throws std::logic_error.

Definition at line 210 of file Tpetra_DistObject_def.hpp.

◆ doTransfer()

void Tpetra::DistObject< char , LO , GO , NT , NT ::classic >::doTransfer	(	const SrcDistObject< char, LO, GO, NT > &	src,
		CombineMode	CM,
		size_t	numSameIDs,
		const Teuchos::ArrayView< const local_ordinal_type > &	permuteToLIDs,
		const Teuchos::ArrayView< const local_ordinal_type > &	permuteFromLIDs,
		const Teuchos::ArrayView< const local_ordinal_type > &	remoteLIDs,
		const Teuchos::ArrayView< const local_ordinal_type > &	exportLIDs,
		Distributor &	distor,
		ReverseOption	revOp
	)

protectedvirtualinherited

Redistribute data across memory images.

Parameters

src	[in] The source object, to redistribute into the target object, which is `*this` object.
CM	[in] The combine mode that describes how to combine values that map to the same global ID on the same process.
permuteToLIDs	[in] See copyAndPermute().
permuteFromLIDs	[in] See copyAndPermute().
remoteLIDs	[in] List of entries (as local IDs) in the destination object to receive from other processes.
exportLIDs	[in] See packAndPrepare().
distor	[in/out] The Distributor object that knows how to redistribute data.
revOp	[in] Whether to do a forward or reverse mode redistribution.

Definition at line 388 of file Tpetra_DistObject_def.hpp.

◆ checkSizes() [2/2]

virtual bool Tpetra::DistObject< char , LO , GO , NT , NT ::classic >::checkSizes ( const SrcDistObject< char, LO, GO, NT > & source )

protectedpure virtualinherited

Compare the source and target (this) objects for compatibility.

Returns: True if they are compatible, else false.

◆ copyAndPermute()

virtual void Tpetra::DistObject< char , LO , GO , NT , NT ::classic >::copyAndPermute	(	const SrcDistObject< char, LO, GO, NT > &	source,
		size_t	numSameIDs,
		const Teuchos::ArrayView< const local_ordinal_type > &	permuteToLIDs,
		const Teuchos::ArrayView< const local_ordinal_type > &	permuteFromLIDs
	)

inlineprotectedvirtualinherited

Perform copies and permutations that are local to this process.

Parameters

source	[in] On entry, the source object, from which we are distributing. We distribute to the destination object, which is `*this` object.
numSameIDs	[in] The umber of elements that are the same on the source and destination (this) objects. These elements are owned by the same process in both the source and destination objects. No permutation occurs.
numPermuteIDs	[in] The number of elements that are locally permuted between the source and destination objects.
permuteToLIDs	[in] List of the elements that are permuted. They are listed by their LID in the destination object.
permuteFromLIDs	[in] List of the elements that are permuted. They are listed by their LID in the source object.

Definition at line 611 of file Tpetra_DistObject_decl.hpp.

◆ packAndPrepare()

virtual void Tpetra::DistObject< char , LO , GO , NT , NT ::classic >::packAndPrepare	(	const SrcDistObject< char, LO, GO, NT > &	source,
		const Teuchos::ArrayView< const local_ordinal_type > &	exportLIDs,
		Teuchos::Array< packet_type > &	exports,
		const Teuchos::ArrayView< size_t > &	numPacketsPerLID,
		size_t &	constantNumPackets,
		Distributor &	distor
	)

inlineprotectedvirtualinherited

Perform any packing or preparation required for communication.

Parameters

source	[in] Source object for the redistribution.
exportLIDs	[in] List of the entries (as local IDs in the source object) we will be sending to other images.
exports	[out] On exit, the buffer for data to send.
numPacketsPerLID	[out] On exit, the implementation of this method must do one of two things: set numPacketsPerLID[i] to contain the number of packets to be exported for exportLIDs[i] and set constantNumPackets to zero, or set constantNumPackets to a nonzero value. If the latter, the implementation need not fill numPacketsPerLID.
constantNumPackets	[out] On exit, 0 if numPacketsPerLID has variable contents (different size for each LID). If nonzero, then it is expected that the number of packets per LID is constant, and that constantNumPackets is that value.
distor	[in] The Distributor object we are using.

Definition at line 646 of file Tpetra_DistObject_decl.hpp.

◆ unpackAndCombine()

virtual void Tpetra::DistObject< char , LO , GO , NT , NT ::classic >::unpackAndCombine	(	const Teuchos::ArrayView< const local_ordinal_type > &	importLIDs,
		const Teuchos::ArrayView< const packet_type > &	imports,
		const Teuchos::ArrayView< size_t > &	numPacketsPerLID,
		size_t	constantNumPackets,
		Distributor &	distor,
		CombineMode	CM
	)

inlineprotectedvirtualinherited

Perform any unpacking and combining after communication (old version that uses Teuchos memory management classes to hold data).

Parameters

importLIDs	[in] List of the entries (as LIDs in the destination object) we received from other images.
imports	[in] Buffer containing data we received.
numPacketsPerLID	[in] If constantNumPackets is zero, then numPacketsPerLID[i] contains the number of packets imported for importLIDs[i].
constantNumPackets	[in] If nonzero, then numPacketsPerLID is constant (same value in all entries) and constantNumPackets is that value. If zero, then numPacketsPerLID[i] is the number of packets imported for importLIDs[i].
distor	[in] The Distributor object we are using.
CM	[in] The combine mode to use when combining the imported entries with existing entries.

Definition at line 687 of file Tpetra_DistObject_decl.hpp.

◆ unpackAndCombineNew() [2/2]

virtual void Tpetra::DistObject< char , LO , GO , NT , NT ::classic >::unpackAndCombineNew	(	const Kokkos::DualView< const local_ordinal_type *, device_type > &	importLIDs,
		const Kokkos::DualView< const packet_type *, device_type > &	imports,
		const Kokkos::DualView< const size_t *, device_type > &	numPacketsPerLID,
		const size_t	constantNumPackets,
		Distributor &	distor,
		const CombineMode	CM
	)

inlineprotectedvirtualinherited

Perform any unpacking and combining after communication (new version that uses Kokkos data structures to hold data).

The imports input argument controls whether this method should unpack on host or unpack on device.

Parameters

importLIDs	[in] List of the entries (as LIDs in the destination object) we received from other images.
imports	[in] Buffer containing data we received.
numPacketsPerLID	[in] If constantNumPackets is zero, then numPacketsPerLID[i] contains the number of packets imported for importLIDs[i].
constantNumPackets	[in] If nonzero, then numPacketsPerLID is constant (same value in all entries) and constantNumPackets is that value. If zero, then numPacketsPerLID[i] is the number of packets imported for importLIDs[i].
distor	[in] The Distributor object we are using.
CM	[in] The combine mode to use when combining the imported entries with existing entries.

Definition at line 721 of file Tpetra_DistObject_decl.hpp.

◆ createViews()

void Tpetra::DistObject< char , LO , GO , NT , NT ::classic >::createViews ( ) const

protectedvirtualinherited

Hook for creating a const view.

doTransfer() calls this on the source object. By default, it does nothing, but the source object can use this as a hint to fetch data from a compute buffer on an off-CPU device (such as a GPU) into host memory.

Definition at line 1239 of file Tpetra_DistObject_def.hpp.

◆ createViewsNonConst()

void Tpetra::DistObject< char , LO , GO , NT , NT ::classic >::createViewsNonConst ( KokkosClassic::ReadWriteOption rwo )

protectedvirtualinherited

Hook for creating a nonconst view.

doTransfer() calls this on the destination (*this) object. By default, it does nothing, but the destination object can use this as a hint to fetch data from a compute buffer on an off-CPU device (such as a GPU) into host memory.

Parameters

rwo [in] Whether to create a write-only or a read-and-write view. For Kokkos Node types where compute buffers live in a separate memory space (e.g., in the device memory of a discrete accelerator like a GPU), a write-only view only requires copying from host memory to the compute buffer, whereas a read-and-write view requires copying both ways (once to read, from the compute buffer to host memory, and once to write, back to the compute buffer).

Definition at line 1245 of file Tpetra_DistObject_def.hpp.

◆ releaseViews()

void Tpetra::DistObject< char , LO , GO , NT , NT ::classic >::releaseViews ( ) const

protectedvirtualinherited

Hook for releasing views.

Note: This is no longer called (and is therefore no longer needed) for subclasses for which useNewInterface() returns true.

doTransfer() calls this on both the source and destination objects, once it no longer needs to access that object's data. By default, this method does nothing. Implementations may use this as a hint to free host memory which is a view of a compute buffer, once the host memory view is no longer needed. Some implementations may prefer to mirror compute buffers in host memory; for these implementations, releaseViews() may do nothing.

Definition at line 1251 of file Tpetra_DistObject_def.hpp.

◆ reallocImportsIfNeeded()

void Tpetra::DistObject< char , LO , GO , NT , NT ::classic >::reallocImportsIfNeeded	(	const size_t	newSize,
		const bool	debug = `false`
	)

protectedinherited

Reallocate imports_ if needed.

This unfortunately must be declared protected, for the same reason that imports_ is declared protected.

Parameters

newSize	[in] New size of imports_.
debug	[in] Whether to print (copious) debug output to stderr.

Definition at line 444 of file Tpetra_DistObject_def.hpp.

Member Data Documentation

◆ map_

Teuchos::RCP<const map_type> Tpetra::DistObject< char , LO , GO , NT , NT ::classic >::map_

protectedinherited

The Map over which this object is distributed.

Definition at line 772 of file Tpetra_DistObject_decl.hpp.

◆ imports_

Kokkos::DualView<packet_type*, execution_space> Tpetra::DistObject< char , LO , GO , NT , NT ::classic >::imports_

protectedinherited

Buffer into which packed data are imported (received from other processes).

Unfortunately, I had to declare these protected, because CrsMatrix uses them at one point. Please, nobody else use them.

Definition at line 781 of file Tpetra_DistObject_decl.hpp.

◆ numImportPacketsPerLID_

Kokkos::DualView<size_t*, execution_space> Tpetra::DistObject< char , LO , GO , NT , NT ::classic >::numImportPacketsPerLID_

protectedinherited

Number of packets to receive for each receive operation.

This array is used in Distributor::doPosts() (and doReversePosts()) when starting the ireceive operation.

This may be ignored in doTransfer() if constantNumPackets is nonzero, indicating a constant number of packets per LID. (For example, MultiVector sets the constantNumPackets output argument of packAndPrepare() to the number of columns in the multivector.)

Unfortunately, I had to declare this protected, because CrsMatrix uses it at one point. Please, nobody else use it.

Definition at line 806 of file Tpetra_DistObject_decl.hpp.

◆ exports_

Kokkos::DualView<packet_type*, device_type> Tpetra::DistObject< char , LO , GO , NT , NT ::classic >::exports_

protectedinherited

Buffer from which packed data are exported (sent to other processes).

Unfortunately, I had to declare this protected, because CrsMatrix uses it at one point. Please, nobody else use it.

Definition at line 813 of file Tpetra_DistObject_decl.hpp.

◆ numExportPacketsPerLID_

Kokkos::DualView<size_t*, execution_space> Tpetra::DistObject< char , LO , GO , NT , NT ::classic >::numExportPacketsPerLID_

protectedinherited

Number of packets to send for each send operation.

This array is used in Distributor::doPosts() (and doReversePosts()) for preparing for the send operation.

This may be ignored in doTransfer() if constantNumPackets is nonzero, indicating a constant number of packets per LID. (For example, MultiVector sets the constantNumPackets output argument of packAndPrepare() to the number of columns in the multivector.)

Unfortunately, I had to declare this protected, because CrsMatrix uses them at one point. Please, nobody else use it.

Definition at line 828 of file Tpetra_DistObject_decl.hpp.

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

Tpetra_Details_CooMatrix.hpp

Public Types

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Detailed Description

template<class SC, class LO = ::Tpetra::DistObject<char>::local_ordinal_type, class GO = ::Tpetra::DistObject<char>::global_ordinal_type, class NT = ::Tpetra::DistObject<char>::node_type> class Tpetra::Details::CooMatrix< SC, LO, GO, NT >

Member Typedef Documentation

◆ packet_type

◆ scalar_type

◆ map_type

◆ execution_space

Member Enumeration Documentation

◆ ReverseOption

Constructor & Destructor Documentation

◆ CooMatrix() [1/2]

◆ CooMatrix() [2/2]

◆ ~CooMatrix()

Member Function Documentation

◆ sumIntoGlobalValue()

◆ sumIntoGlobalValues() [1/2]

◆ sumIntoGlobalValues() [2/2]

◆ getLclNumEntries()

◆ fillComplete() [1/2]

◆ fillComplete() [2/2]

◆ localError()

◆ errorMessages()

◆ description()

◆ describe()

◆ constantNumberOfPackets()

◆ checkSizes() [1/2]

◆ useNewInterface()

◆ copyAndPermuteNew()

◆ packAndPrepareNew()

◆ unpackAndCombineNew() [1/2]

◆ doImport() [1/2]

◆ doImport() [2/2]

◆ doExport() [1/2]

◆ doExport() [2/2]

◆ isDistributed()

◆ getMap()

◆ print()

◆ removeEmptyProcessesInPlace()

◆ doTransfer()

◆ checkSizes() [2/2]

◆ copyAndPermute()

◆ packAndPrepare()

◆ unpackAndCombine()

◆ unpackAndCombineNew() [2/2]

◆ createViews()

◆ createViewsNonConst()

◆ releaseViews()

◆ reallocImportsIfNeeded()

Member Data Documentation

◆ map_

◆ imports_

◆ numImportPacketsPerLID_

◆ exports_

◆ numExportPacketsPerLID_

template<class SC, class LO = ::Tpetra::DistObject<char>::local_ordinal_type, class GO = ::Tpetra::DistObject<char>::global_ordinal_type, class NT = ::Tpetra::DistObject<char>::node_type>
class Tpetra::Details::CooMatrix< SC, LO, GO, NT >