Distributed CSR matrix that manages storage and GPU-friendly partitions. More...

#include <AMReX_SpMatrix.H>

Classes
struct	CommMV

struct	CommTR

struct	RemoteRowsMM
	Rows of another matrix fetched for SpGEMM. Column indices are global. More...

Public Types
using	value_type = T

template<class U >
using	allocator_type = Allocator< U >

template<class U >
using	container_type = PODVector< U, Allocator< U > >

using	csr_type = CSR< T, container_type >

using	AllocT = Allocator< T >

Public Member Functions
	SpMatrix ()=default

	SpMatrix (AlgPartition partition, int nnz_per_row)
	Construct a sparse matrix with a fixed number of nonzeros per row.

	SpMatrix (AlgPartition partition, csr_type csr)
	Construct a sparse matrix from a given Partition and CSR.

	SpMatrix (SpMatrix const &)=delete

SpMatrix &	operator= (SpMatrix const &)=delete

	SpMatrix (SpMatrix &&)=default

SpMatrix &	operator= (SpMatrix &&)=default

	~SpMatrix ()=default

void	define (AlgPartition partition, int nnz_per_row)
	Allocate storage for a default-constructed matrix with a fixed number of nonzeros per row.

void	define (AlgPartition partition, T const mat, Long const col_index, Long nentries, Long const *row_offset, CsrSorted is_sorted, CsrValid is_valid)
	Define a default-constructed matrix from given CSR arrays.

void	define (AlgPartition partition, csr_type csr, CsrSorted is_sorted)
	Define a default-constructed matrix from a given CSR.

AlgPartition const &	partition () const
	Row partition describing how matrix rows are distributed across ranks.

AlgPartition const &	columnPartition () const
	Return the column partition used for matrix-vector and matrix-matrix multiplications.

Long	numLocalRows () const
	Number of rows owned by this rank.

Long	numGlobalRows () const
	Global row count.

Long	numLocalNonZeros () const
	Number of nonzeros stored locally.

Long	globalRowBegin () const
	Inclusive global index begin on this process.

Long	globalRowEnd () const
	Exclusive global index end on this process.

T *	data ()
	Don't use this beyond initial setup.

Long *	columnIndex ()
	Don't use this beyond initial setup.

Long *	rowOffset ()
	Don't use this beyond initial setup.

void	printToFile (std::string const &file) const

template<typename F >
void	setVal (F const &f, CsrSorted is_sorted)
	Initialize matrix entries using a row-wise functor.

void	sortCSR ()

void	setColumnPartition (AlgPartition const &col_partition)

AlgVector< T, AllocT > const &	diagonalVector () const
	Return diagonal elements in a square matrix.

AlgVector< T, AllocT >	rowSum () const
	Sum the values in each local row and return the result as an AlgVector.

ParCsr< T >	parcsr ()
	Build GPU-friendly CSR views split into diagonal/off-diagonal blocks.

ParCsr< T const >	parcsr () const
	Const variant of parcsr().

ParCsr< T const >	const_parcsr () const
	Const-qualified alias of parcsr() for convenience.

void	define_doit (int nnz_per_row)
	Private helper (exposed for CUDA) that allocates fixed-connectivity matrices with `nnz_per_row` entries.

template<typename I >
void	define_and_filter_doit (T const mat, Long const col_index, Long nentries, Long const *row_offset)
	Private helper (exposed for CUDA) that copies/filters CSR arrays into device storage.

void	startComm_mv (AlgVector< T, AllocT > const &x)
	Prepare halo exchanges for a subsequent SpMV using `x` as the source vector.

void	finishComm_mv (AlgVector< T, AllocT > &y)
	Finish halo exchanges and accumulate contributions into `y`.

void	startComm_tr (AlgPartition const &col_partition)
	Initiate communication required to build the transpose with column partition `col_partition`.

void	finishComm_tr (SpMatrix< T, Allocator > &AT)
	Complete transpose communication, writing the assembled matrix into `AT`.

void	split_csr (AlgPartition const &col_partition)

template<typename C >
void	update_remote_col_index (C &csrr, bool in_device_memory)

void	prepare_comm_mv (AlgPartition const &col_partition)

void	pack_buffer_mv (AlgVector< T, AllocT > const &v)

void	unpack_buffer_mv (AlgVector< T, AllocT > &v)

void	comm_tr_recv_wait ()

void	comm_tr_clear ()

void	unpack_buffer_tr (CommTR const &ctr, AlgPartition const &col_partition)

void	expand_remote_row_offset () const

CsrView< T const >	remote_full_const_view () const
	Off-diagonal part with the full (untrimmed) row offsets.

RemoteRowsMM	fetch_remote_rows_mm (SpMatrix< T, Allocator > const &B)

Public Attributes
struct amrex::SpMatrix::CommMV	m_comm_mv

struct amrex::SpMatrix::CommTR	m_comm_tr

Friends
template<typename U >
class	AMG

template<typename U , template< typename > class M, typename N >
void	SpMV (AlgVector< U, N > &y, SpMatrix< U, M > const &A, AlgVector< U, N > const &x)

template<typename U , template< typename > class M>
SpMatrix< U, M >	transpose (SpMatrix< U, M > const &A, AlgPartition const &col_partition)

template<typename U , template< typename > class M>
SpMatrix< U, M >	SpGEMM (SpMatrix< U, M > const &A, SpMatrix< U, M > const &B, AlgPartition const &col_partition)

Detailed Description

template<typename T, template< typename > class Allocator = DefaultAllocator>
class amrex::SpMatrix< T, Allocator >

Distributed CSR matrix that manages storage and GPU-friendly partitions.

Member Typedef Documentation

◆ allocator_type

template<typename T , template< typename > class Allocator = DefaultAllocator>

template<class U >

using amrex::SpMatrix< T, Allocator >::allocator_type = Allocator<U>

◆ AllocT

template<typename T , template< typename > class Allocator = DefaultAllocator>

using amrex::SpMatrix< T, Allocator >::AllocT = Allocator<T>

◆ container_type

template<typename T , template< typename > class Allocator = DefaultAllocator>

template<class U >

using amrex::SpMatrix< T, Allocator >::container_type = PODVector<U,Allocator<U> >

◆ csr_type

template<typename T , template< typename > class Allocator = DefaultAllocator>

using amrex::SpMatrix< T, Allocator >::csr_type = CSR<T,container_type>

◆ value_type

template<typename T , template< typename > class Allocator = DefaultAllocator>

using amrex::SpMatrix< T, Allocator >::value_type = T

Constructor & Destructor Documentation

◆ SpMatrix() [1/5]

template<typename T , template< typename > class Allocator = DefaultAllocator>

amrex::SpMatrix< T, Allocator >::SpMatrix ( )

default

◆ SpMatrix() [2/5]

template<typename T , template< typename > class Allocator>

amrex::SpMatrix< T, Allocator >::SpMatrix	(	AlgPartition	partition,
		int	nnz_per_row
	)

Construct a sparse matrix with a fixed number of nonzeros per row.

This constructor allocates the required storage and initializes the row offsets. The matrix entries themselves are left uninitialized. Matrix values can be written through the pointer returned by data() and the corresponding column indices through the pointer returned by the columnIndex(). Alternatively, the matrix may be initialized using setVal(). In either case, the CSR data must not contain duplicated entries or invalid entries (i.e., negative column indices). If the matrix is set manually through pointers and the entries within each row are not sorted by column index, the user must call sortCSR after all data have been set.

Parameters

partition	Parallel partition information.
nnz_per_row	Number of nonzeros per row.

◆ SpMatrix() [3/5]

template<typename T , template< typename > class Allocator>

amrex::SpMatrix< T, Allocator >::SpMatrix	(	AlgPartition	partition,
		csr_type	csr
	)

Construct a sparse matrix from a given Partition and CSR.

The input CSR represents the portion of the matrix local to this process. It must be both sorted and valid. Moreover, it should not have duplicated entries.

Parameters

partition	Parallel partition information.
csr	CSR represents of the matrix local to this process.

◆ SpMatrix() [4/5]

template<typename T , template< typename > class Allocator = DefaultAllocator>

amrex::SpMatrix< T, Allocator >::SpMatrix ( SpMatrix< T, Allocator > const & )

delete

◆ SpMatrix() [5/5]

template<typename T , template< typename > class Allocator = DefaultAllocator>

amrex::SpMatrix< T, Allocator >::SpMatrix ( SpMatrix< T, Allocator > && )

default

◆ ~SpMatrix()

template<typename T , template< typename > class Allocator = DefaultAllocator>

amrex::SpMatrix< T, Allocator >::~SpMatrix ( )

default

Member Function Documentation

◆ columnIndex()

template<typename T , template< typename > class Allocator = DefaultAllocator>

Long * amrex::SpMatrix< T, Allocator >::columnIndex ( )

inline

Don't use this beyond initial setup.

◆ columnPartition()

template<typename T , template< typename > class Allocator = DefaultAllocator>

AlgPartition const & amrex::SpMatrix< T, Allocator >::columnPartition ( ) const

inline

Return the column partition used for matrix-vector and matrix-matrix multiplications.

This partition corresponds to the row partition of the vector or matrix appearing on the right-hand side of a multiplication.

◆ comm_tr_clear()

template<typename T , template< typename > class Allocator>

void amrex::SpMatrix< T, Allocator >::comm_tr_clear ( )

◆ comm_tr_recv_wait()

template<typename T , template< typename > class Allocator>

void amrex::SpMatrix< T, Allocator >::comm_tr_recv_wait ( )

◆ const_parcsr()

template<typename T , template< typename > class Allocator>

ParCsr< T const > amrex::SpMatrix< T, Allocator >::const_parcsr ( ) const

Const-qualified alias of parcsr() for convenience.

◆ data()

template<typename T , template< typename > class Allocator = DefaultAllocator>

T * amrex::SpMatrix< T, Allocator >::data ( )

inline

Don't use this beyond initial setup.

◆ define() [1/3]

template<typename T , template< typename > class Allocator>

void amrex::SpMatrix< T, Allocator >::define	(	AlgPartition	partition,
		csr_type	csr,
		CsrSorted	is_sorted
	)

Define a default-constructed matrix from a given CSR.

The input CSR represents the portion of the matrix local to this process. It must be valid. Moreover, it should not have duplicated entries.

Parameters

partition	Parallel partition information.
csr	CSR represents of the matrix local to this process.
is_sorted	Indicates whether the CSR entries are sorted (within each row).

◆ define() [2/3]

template<typename T , template< typename > class Allocator>

void amrex::SpMatrix< T, Allocator >::define	(	AlgPartition	partition,
		int	nnz_per_row
	)

Allocate storage for a default-constructed matrix with a fixed number of nonzeros per row.

This allocates the required storage and initializes the row offsets. The matrix entries themselves are left uninitialized. Matrix values can be written through the pointer returned by data() and the corresponding column indices through the pointer returned by the columnIndex(). Alternatively, the matrix may be initialized using setVal().

Parameters

partition	Parallel partition information.
nnz_per_row	Number of nonzeros per row.

◆ define() [3/3]

template<typename T , template< typename > class Allocator>

void amrex::SpMatrix< T, Allocator >::define	(	AlgPartition	partition,
		T const *	mat,
		Long const *	col_index,
		Long	nentries,
		Long const *	row_offset,
		CsrSorted	is_sorted,
		CsrValid	is_valid
	)

Define a default-constructed matrix from given CSR arrays.

The CSR arrays describe the portion of the matrix local to this process.

If is_valid indicates that the input CSR may contain invalid entries, this function will filter the input and omit such entries from the resulting matrix. An entry is considered invalid if its column index is negative. In addition, when is_valid is false, this function also removes entries whose values are zero. The input CSR is not allowed to contain duplicated valid entries.

It is not an error to specify is_sorted = false when the input CSR is in fact sorted, nor to specify is_valid = false when the input CSR contains no invalid entries. In these cases, the result is correct, but the function may perform unnecessary work and therefore result in a performance penalty. If the input properties are not known, it is safe to set both flags to false.

The input data can be freed after this function call. For GPU builds, the data are expected to be in GPU memory.

Parameters

partition	Parallel partition information.
mat	CSR values array (length `nentries`).
col_index	CSR column indices array (length `nentries`).
nentries	Number of entries.
row_offset	CSR row offsets array (length `num_local_rows + 1`).
is_sorted	Indicates whether the CSR entries are sorted (within each row).
is_valid	Indicates whether the input CSR is guaranteed to be valid (i.e., contains no negative column indices).

◆ define_and_filter_doit()

template<typename T , template< typename > class Allocator>

template<typename I >

void amrex::SpMatrix< T, Allocator >::define_and_filter_doit	(	T const *	mat,
		Long const *	col_index,
		Long	nentries,
		Long const *	row_offset
	)

Private helper (exposed for CUDA) that copies/filters CSR arrays into device storage.

Template Parameters

I	Prefix-scan index type.

Parameters

mat	Input values array.
col_index	Input column indices.
nentries	Number of candidate entries.
row_offset	Row offsets array.

◆ define_doit()

template<typename T , template< typename > class Allocator>

void amrex::SpMatrix< T, Allocator >::define_doit ( int nnz_per_row )

Private helper (exposed for CUDA) that allocates fixed-connectivity matrices with nnz_per_row entries.

◆ diagonalVector()

template<typename T , template< typename > class Allocator>

AlgVector< T, Allocator< T > > const & amrex::SpMatrix< T, Allocator >::diagonalVector ( ) const

Return diagonal elements in a square matrix.

◆ expand_remote_row_offset()

template<typename T , template< typename > class Allocator>

void amrex::SpMatrix< T, Allocator >::expand_remote_row_offset ( ) const

◆ fetch_remote_rows_mm()

template<typename T , template< typename > class Allocator>

auto amrex::SpMatrix< T, Allocator >::fetch_remote_rows_mm ( SpMatrix< T, Allocator > const & B )

Fetch the rows of B listed in m_remote_cols_v. This matrix must already be split with B's row partition. Collective.

◆ finishComm_mv()

template<typename T , template< typename > class Allocator>

void amrex::SpMatrix< T, Allocator >::finishComm_mv ( AlgVector< T, AllocT > & y )

Finish halo exchanges and accumulate contributions into y.

◆ finishComm_tr()

template<typename T , template< typename > class Allocator>

void amrex::SpMatrix< T, Allocator >::finishComm_tr ( SpMatrix< T, Allocator > & AT )

Complete transpose communication, writing the assembled matrix into AT.

◆ globalRowBegin()

template<typename T , template< typename > class Allocator = DefaultAllocator>

Long amrex::SpMatrix< T, Allocator >::globalRowBegin ( ) const

inline

Inclusive global index begin on this process.

◆ globalRowEnd()

template<typename T , template< typename > class Allocator = DefaultAllocator>

Long amrex::SpMatrix< T, Allocator >::globalRowEnd ( ) const

inline

Exclusive global index end on this process.

◆ numGlobalRows()

template<typename T , template< typename > class Allocator = DefaultAllocator>

Long amrex::SpMatrix< T, Allocator >::numGlobalRows ( ) const

inline

Global row count.

◆ numLocalNonZeros()

template<typename T , template< typename > class Allocator = DefaultAllocator>

Long amrex::SpMatrix< T, Allocator >::numLocalNonZeros ( ) const

inline

Number of nonzeros stored locally.

◆ numLocalRows()

template<typename T , template< typename > class Allocator = DefaultAllocator>

Long amrex::SpMatrix< T, Allocator >::numLocalRows ( ) const

inline

Number of rows owned by this rank.

◆ operator=() [1/2]

template<typename T , template< typename > class Allocator = DefaultAllocator>

SpMatrix & amrex::SpMatrix< T, Allocator >::operator= ( SpMatrix< T, Allocator > && )

default

◆ operator=() [2/2]

template<typename T , template< typename > class Allocator = DefaultAllocator>

SpMatrix & amrex::SpMatrix< T, Allocator >::operator= ( SpMatrix< T, Allocator > const & )

delete

◆ pack_buffer_mv()

template<typename T , template< typename > class Allocator>

void amrex::SpMatrix< T, Allocator >::pack_buffer_mv ( AlgVector< T, AllocT > const & v )

◆ parcsr() [1/2]

template<typename T , template< typename > class Allocator>

ParCsr< T > amrex::SpMatrix< T, Allocator >::parcsr ( )

Build GPU-friendly CSR views split into diagonal/off-diagonal blocks.

The returned structure aliases the underlying storage; do not outlive this matrix.

◆ parcsr() [2/2]

template<typename T , template< typename > class Allocator>

ParCsr< T const > amrex::SpMatrix< T, Allocator >::parcsr ( ) const

Const variant of parcsr().

◆ partition()

template<typename T , template< typename > class Allocator = DefaultAllocator>

AlgPartition const & amrex::SpMatrix< T, Allocator >::partition ( ) const

inline

Row partition describing how matrix rows are distributed across ranks.

◆ prepare_comm_mv()

template<typename T , template< typename > class Allocator>

void amrex::SpMatrix< T, Allocator >::prepare_comm_mv ( AlgPartition const & col_partition )

◆ printToFile()

template<typename T , template< typename > class Allocator>

void amrex::SpMatrix< T, Allocator >::printToFile ( std::string const & file ) const

◆ remote_full_const_view()

template<typename T , template< typename > class Allocator>

CsrView< T const > amrex::SpMatrix< T, Allocator >::remote_full_const_view ( ) const

Off-diagonal part with the full (untrimmed) row offsets.

◆ rowOffset()

template<typename T , template< typename > class Allocator = DefaultAllocator>

Long * amrex::SpMatrix< T, Allocator >::rowOffset ( )

inline

Don't use this beyond initial setup.

◆ rowSum()

template<typename T , template< typename > class Allocator>

AlgVector< T, Allocator< T > > amrex::SpMatrix< T, Allocator >::rowSum ( ) const

Sum the values in each local row and return the result as an AlgVector.

Each MPI rank receives the row sums for the rows it owns; if further reductions are needed they should be performed on the returned vector.

◆ setColumnPartition()

template<typename T , template< typename > class Allocator>

void amrex::SpMatrix< T, Allocator >::setColumnPartition ( AlgPartition const & col_partition )

Set column partition. This is usually not needed to be called by the user.

◆ setVal()

template<typename T , template< typename > class Allocator>

template<typename F >

void amrex::SpMatrix< T, Allocator >::setVal	(	F const &	f,
		CsrSorted	is_sorted
	)

Initialize matrix entries using a row-wise functor.

The functor must have the signature

void(Long row, Long* col, T* val)

amrex::Long

amrex_long Long

Definition AMReX_INT.H:30

and is responsible for setting the global column indices and values for the row specified by the global row index. The two pointers point to the beginning of the specified row.

This function is intended to be used after define(AlgPartition,int), when the storage has been allocated. It should only be used during initial matrix setup and not for modifying an already assembled matrix.

The CSR data must not contain duplicated entries or invalid entries (i.e., negative column indices).

Parameters

f	Functor `void(Long,Long,T)`
is_sorted	Indicates whether the CSR entries are sorted (within each row).

◆ sortCSR()

template<typename T , template< typename > class Allocator>

void amrex::SpMatrix< T, Allocator >::sortCSR ( )

Sort CSR by column index withint each row. This is intended to be used after the user sets the matrix manually or with setVal.

◆ split_csr()

template<typename T , template< typename > class Allocator>

void amrex::SpMatrix< T, Allocator >::split_csr ( AlgPartition const & col_partition )

◆ startComm_mv()

template<typename T , template< typename > class Allocator>

void amrex::SpMatrix< T, Allocator >::startComm_mv ( AlgVector< T, AllocT > const & x )

Prepare halo exchanges for a subsequent SpMV using x as the source vector.

Must be paired with finishComm_mv(); only available when MPI is enabled.

◆ startComm_tr()

template<typename T , template< typename > class Allocator>

void amrex::SpMatrix< T, Allocator >::startComm_tr ( AlgPartition const & col_partition )

Initiate communication required to build the transpose with column partition col_partition.

◆ unpack_buffer_mv()

template<typename T , template< typename > class Allocator>

void amrex::SpMatrix< T, Allocator >::unpack_buffer_mv ( AlgVector< T, AllocT > & v )

◆ unpack_buffer_tr()

template<typename T , template< typename > class Allocator>

void amrex::SpMatrix< T, Allocator >::unpack_buffer_tr	(	CommTR const &	ctr,
		AlgPartition const &	col_partition
	)

◆ update_remote_col_index()

template<typename T , template< typename > class Allocator>

template<typename C >

void amrex::SpMatrix< T, Allocator >::update_remote_col_index	(	C &	csrr,
		bool	in_device_memory
	)

Friends And Related Symbol Documentation

◆ AMG

template<typename T , template< typename > class Allocator = DefaultAllocator>

template<typename U >

friend class AMG

friend

◆ SpGEMM

template<typename T , template< typename > class Allocator = DefaultAllocator>

template<typename U , template< typename > class M>

SpMatrix< U, M > SpGEMM	(	SpMatrix< U, M > const &	A,
		SpMatrix< U, M > const &	B,
		AlgPartition const &	col_partition
	)

friend

◆ SpMV

template<typename T , template< typename > class Allocator = DefaultAllocator>

template<typename U , template< typename > class M, typename N >

void SpMV	(	AlgVector< U, N > &	y,
		SpMatrix< U, M > const &	A,
		AlgVector< U, N > const &	x
	)

friend

◆ transpose

template<typename T , template< typename > class Allocator = DefaultAllocator>

template<typename U , template< typename > class M>

SpMatrix< U, M > transpose	(	SpMatrix< U, M > const &	A,
		AlgPartition const &	col_partition
	)

friend

Member Data Documentation

◆ m_comm_mv

template<typename T , template< typename > class Allocator = DefaultAllocator>

struct amrex::SpMatrix::CommMV amrex::SpMatrix< T, Allocator >::m_comm_mv

◆ m_comm_tr

template<typename T , template< typename > class Allocator = DefaultAllocator>

struct amrex::SpMatrix::CommTR amrex::SpMatrix< T, Allocator >::m_comm_tr

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

/home/runner/work/amrex/amrex/Src/LinearSolvers/AMReX_SpMatrix.H

Classes

Public Types

Public Member Functions

Public Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ allocator_type

◆ AllocT

◆ container_type

◆ csr_type

◆ value_type

Constructor & Destructor Documentation

◆ SpMatrix() [1/5]

◆ SpMatrix() [2/5]

◆ SpMatrix() [3/5]

◆ SpMatrix() [4/5]

◆ SpMatrix() [5/5]

◆ ~SpMatrix()

Member Function Documentation

◆ columnIndex()

◆ columnPartition()

◆ comm_tr_clear()

◆ comm_tr_recv_wait()

◆ const_parcsr()

◆ data()

◆ define() [1/3]

◆ define() [2/3]

◆ define() [3/3]

◆ define_and_filter_doit()

◆ define_doit()

◆ diagonalVector()

◆ expand_remote_row_offset()

◆ fetch_remote_rows_mm()

◆ finishComm_mv()

◆ finishComm_tr()

◆ globalRowBegin()

◆ globalRowEnd()

◆ numGlobalRows()

◆ numLocalNonZeros()

◆ numLocalRows()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ pack_buffer_mv()

◆ parcsr() [1/2]

◆ parcsr() [2/2]

◆ partition()

◆ prepare_comm_mv()

◆ printToFile()

◆ remote_full_const_view()

◆ rowOffset()

◆ rowSum()

◆ setColumnPartition()

◆ setVal()

◆ sortCSR()

◆ split_csr()

◆ startComm_mv()

◆ startComm_tr()

◆ unpack_buffer_mv()

◆ unpack_buffer_tr()

◆ update_remote_col_index()

Friends And Related Symbol Documentation

◆ AMG

◆ SpGEMM

◆ SpMV

◆ transpose

Member Data Documentation

◆ m_comm_mv

◆ m_comm_tr