Distributed sparse matrix. More...

#include <MatrixCSR.h>

Public Types
using	value_type = T
	The value type.

using	allocator_type = Allocator
	The allocator type.

Public Member Functions
auto	mat_set_values ()
	Insertion functor for setting values in matrix. It is typically used in finite element assembly functions. More...

auto	mat_add_values ()
	Insertion functor for accumulating values in matrix. It is typically used in finite element assembly functions. More...

	MatrixCSR (const SparsityPattern &p, const Allocator &alloc=Allocator())
	Create a distributed matrix. More...

	MatrixCSR (MatrixCSR &&A)=default
	Move constructor. More...

void	set (T x)
	Set all non-zero local entries to a value including entries in ghost rows. More...

void	set (const std::span< const T > &x, const std::span< const std::int32_t > &rows, const std::span< const std::int32_t > &cols)
	Set values in the matrix. More...

void	add (const std::span< const T > &x, const std::span< const std::int32_t > &rows, const std::span< const std::int32_t > &cols)
	Accumulate values in the matrix. More...

std::int32_t	num_owned_rows () const
	Number of local rows excluding ghost rows.

std::int32_t	num_all_rows () const
	Number of local rows including ghost rows.

std::vector< T >	to_dense () const
	Copy to a dense matrix. More...

void	finalize ()
	Transfer ghost row data to the owning ranks accumulating received values on the owned rows, and zeroing any existing data in ghost rows.

void	finalize_begin ()
	Begin transfer of ghost row data to owning ranks, where it will be accumulated into existing owned rows. More...

void	finalize_end ()
	End transfer of ghost row data to owning ranks. More...

double	norm_squared () const
	Compute the Frobenius norm squared.

const std::array< std::shared_ptr< const common::IndexMap >, 2 > &	index_maps () const
	Index maps for the row and column space. The row IndexMap contains ghost entries for rows which may be inserted into and the column IndexMap contains all local and ghost columns that may exist in the owned rows. More...

std::vector< T > &	values ()
	Get local data values. More...

const std::vector< T > &	values () const
	Get local values (const version) More...

const std::vector< std::int32_t > &	row_ptr () const
	Get local row pointers. More...

const std::vector< std::int32_t > &	cols () const
	Get local column indices. More...

const std::vector< std::int32_t > &	off_diag_offset () const
	Get the start of off-diagonal (unowned columns) on each row, allowing the matrix to be split (virtually) into two parts. Operations (such as matrix-vector multiply) between the owned parts of the matrix and vector can then be performed separately from operations on the unowned parts. More...

Detailed Description

template<typename T, class Allocator = std::allocator<T>>
class dolfinx::la::MatrixCSR< T, Allocator >

Distributed sparse matrix.

The matrix storage format is compressed sparse row. The matrix is partitioned row-wise across MPI rank.

Template Parameters

T	The data type for the matrix
Allocator	The memory allocator type for the data storage

Note: Highly "experimental" storage of a matrix in CSR format which can be assembled into using the usual dolfinx assembly routines Matrix internal data can be accessed for interfacing with other code.

Todo:: Handle block sizes

Constructor & Destructor Documentation

◆ MatrixCSR() [1/2]

MatrixCSR	(	const SparsityPattern &	p,
		const Allocator &	alloc = `Allocator()`
	)

inline

Create a distributed matrix.

Parameters

[in]	p	The sparsty pattern the describes the parallel distribution and the non-zero structure
[in]	alloc	The memory allocator for the data storafe

◆ MatrixCSR() [2/2]

MatrixCSR ( MatrixCSR< T, Allocator > && A )

default

Move constructor.

Todo:: Check handling of MPI_Request

Member Function Documentation

◆ add()

void add	(	const std::span< const T > &	x,
		const std::span< const std::int32_t > &	rows,
		const std::span< const std::int32_t > &	cols
	)

inline

Accumulate values in the matrix.

Note: Only entries included in the sparsity pattern used to initialize the matrix can be accumulated in to; All indices are local to the calling MPI rank and entries may go into ghost rows.; Use finalize after all entries have been added to send ghost rows to owners. Adding more entries after finalize is allowed, but another call to finalize will then be required.

Parameters

[in]	x	The `m` by `n` dense block of values (row-major) to add to the matrix
[in]	rows	The row indices of `x`
[in]	cols	The column indices of `x`

◆ cols()

const std::vector<std::int32_t>& cols ( ) const

inline

Get local column indices.

Note: Includes columns in ghost rows

◆ finalize_begin()

void finalize_begin ( )

inline

Begin transfer of ghost row data to owning ranks, where it will be accumulated into existing owned rows.

Note: Calls to this function must be followed by MatrixCSR::finalize_end(). Between the two calls matrix values must not be changed.; This function does not change the matrix data. Data update only occurs with finalize_end().

◆ finalize_end()

void finalize_end ( )

inline

End transfer of ghost row data to owning ranks.

Note: Must be preceded by MatrixCSR::finalize_begin(); Matrix data received from other processes will be accumulated into locally owned rows, and ghost rows will be zeroed.

◆ index_maps()

const std::array<std::shared_ptr<const common::IndexMap>, 2>& index_maps ( ) const

inline

Index maps for the row and column space. The row IndexMap contains ghost entries for rows which may be inserted into and the column IndexMap contains all local and ghost columns that may exist in the owned rows.

Returns: Row (0) and column (1) index maps

◆ mat_add_values()

auto mat_add_values ( )

inline

Insertion functor for accumulating values in matrix. It is typically used in finite element assembly functions.

Parameters

A	Matrix to insert into

Returns: Function for inserting values into A

◆ mat_set_values()

auto mat_set_values ( )

inline

Insertion functor for setting values in matrix. It is typically used in finite element assembly functions.

Parameters

A	Matrix to insert into

Returns: Function for inserting values into A

Todo:: clarify setting on non-owned enrties

◆ off_diag_offset()

const std::vector<std::int32_t>& off_diag_offset ( ) const

inline

Get the start of off-diagonal (unowned columns) on each row, allowing the matrix to be split (virtually) into two parts. Operations (such as matrix-vector multiply) between the owned parts of the matrix and vector can then be performed separately from operations on the unowned parts.

Note: Includes ghost rows, which should be truncated manually if not required.

◆ row_ptr()

const std::vector<std::int32_t>& row_ptr ( ) const

inline

Get local row pointers.

Note: Includes pointers to ghost rows

◆ set() [1/2]

void set	(	const std::span< const T > &	x,
		const std::span< const std::int32_t > &	rows,
		const std::span< const std::int32_t > &	cols
	)

inline

Set values in the matrix.

Note: Only entries included in the sparsity pattern used to initialize the matrix can be set; All indices are local to the calling MPI rank and entries cannot be set in ghost rows.; This should be called after finalize. Using before finalize will set the values correctly, but incoming values may get added to them during a subsequent finalize operation.

Parameters

[in]	x	The `m` by `n` dense block of values (row-major) to set in the matrix
[in]	rows	The row indices of `x`
[in]	cols	The column indices of `x`

◆ set() [2/2]

void set ( T x )

inline

Set all non-zero local entries to a value including entries in ghost rows.

Parameters

[in] x The value to set non-zero matrix entries to

◆ to_dense()

std::vector<T> to_dense ( ) const

inline

Copy to a dense matrix.

Note: This function is typically used for debugging and not used in production; Ghost rows are also returned, and these can be truncated manually by using num_owned_rows() if required.

Returns: Dense copy of the part of the matrix on the calling rank. Storage is row-major.

◆ values() [1/2]

std::vector<T>& values ( )

inline

Get local data values.

Note: Includes ghost values

◆ values() [2/2]

const std::vector<T>& values ( ) const

inline

Get local values (const version)

Note: Includes ghost values

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

/__w/dolfinx/dolfinx/cpp/dolfinx/la/MatrixCSR.h

Public Types

Public Member Functions

Detailed Description

template<typename T, class Allocator = std::allocator<T>> class dolfinx::la::MatrixCSR< T, Allocator >

Constructor & Destructor Documentation

◆ MatrixCSR() [1/2]

◆ MatrixCSR() [2/2]

Member Function Documentation

◆ add()

◆ cols()

◆ finalize_begin()

◆ finalize_end()

◆ index_maps()

◆ mat_add_values()

◆ mat_set_values()

◆ off_diag_offset()

◆ row_ptr()

◆ set() [1/2]

◆ set() [2/2]

◆ to_dense()

◆ values() [1/2]

◆ values() [2/2]

template<typename T, class Allocator = std::allocator<T>>
class dolfinx::la::MatrixCSR< T, Allocator >