Loading...
Searching...
No Matches
MatrixCSR< Scalar, Container, ColContainer, RowPtrContainer > Class Template Reference

Distributed sparse matrix using compressed sparse row storage. More...

`#include <MatrixCSR.h>`

## Public Types

using | value_type = Scalar
| Scalar type.
using | container_type = Container
| Matrix entries container type.
using | column_container_type = ColContainer
| Column index container type.
using | rowptr_container_type = RowPtrContainer
| Row pointer container type.

## Public Member Functions

template<int BS0 = 1, int BS1 = 1>
auto | mat_set_values ()
| Insertion functor for setting values in a matrix. It is typically used in finite element assembly functions.
template<int BS0 = 1, int BS1 = 1>
auto | mat_add_values ()
| Insertion functor for adding values to a matrix. It is typically used in finite element assembly functions.
| MatrixCSR (const SparsityPattern &p, BlockMode mode=BlockMode::compact)
| Create a distributed matrix.
| MatrixCSR (MatrixCSR &&A)=default
| MatrixCSR (const MatrixCSR &A)=default
template<typename Scalar0, typename Container0, typename ColContainer0, typename RowPtrContainer0>
| MatrixCSR (const MatrixCSR< Scalar0, Container0, ColContainer0, RowPtrContainer0 > &A)
| Copy-convert matrix, possibly using to different container types.
void | set (value_type x)
| Set all non-zero local entries to a value, including entries in ghost rows.
template<int BS0, int BS1>
void | set (std::span< const value_type > x, std::span< const std::int32_t > rows, std::span< const std::int32_t > cols)
| Set values in the matrix.
template<int BS0 = 1, int BS1 = 1>
void | add (std::span< const value_type > x, std::span< const std::int32_t > rows, std::span< const std::int32_t > cols)
| Accumulate values in the matrix.
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< value_type > | to_dense () const
| Copy to a dense matrix.
void | scatter_rev ()
| Transfer ghost row data to the owning ranks accumulating received values on the owned rows, and zeroing any existing data in ghost rows.
void | scatter_rev_begin ()
| Begin transfer of ghost row data to owning ranks, where it will be accumulated into existing owned rows.
void | scatter_rev_end ()
| End transfer of ghost row data to owning ranks.
double | squared_norm () const
| Compute the Frobenius norm squared across all processes.
void | mult (Vector< value_type > &x, Vector< value_type > &y)
| Compute the product y += Ax.
MPI_Comm | comm () const
| Get MPI communicator that matrix is defined on.
std::shared_ptr< const common::IndexMap > | index_map (int dim) const
| Index map for the row or column space.
container_type & | values ()
| Get local data values.
const container_type & | values () const
| Get local values (const version).
const rowptr_container_type & | row_ptr () const
| Get local row pointers.
const column_container_type & | cols () const
const rowptr_container_type & | 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.
std::array< int, 2 > | block_size () const
| Get block sizes.
BlockMode | block_mode () const
| Get 'block mode'.

## Detailed Description

template<typename Scalar, typename Container = std::vector<Scalar>, typename ColContainer = std::vector<std::int32_t>, typename RowPtrContainer = std::vector<std::int64_t>>
class dolfinx::la::MatrixCSR< Scalar, Container, ColContainer, RowPtrContainer >

Distributed sparse matrix using compressed sparse row storage.

Warning
  The class is experimental and subject to change.

The matrix storage format is compressed sparse row, and is partitioned by row across MPI ranks. The matrix can be assembled into using the usual DOLFINx assembly routines. Matrix internal data can be accessed for interfacing with other code.

Template Parameters

  Scalar | Scalar type of matrix entries
  Container | Container type for storing matrix entries
  ColContainer | Column index container type
  RowPtrContainer | Row pointer container type

## Constructor & Destructor Documentation

## MatrixCSR() [1/4]

template<class U, class V, class W, class X>

MatrixCSR | ( | const SparsityPattern & | p,
|  | BlockMode | mode = BlockMode::compact )

Create a distributed matrix.

The structure of the matrix depends entirely on the input SparsityPattern, which must be finalized. The matrix storage is distributed Compressed Sparse Row: the matrix is distributed by row across processes, and on each process, there is a list of column indices and matrix entries for each row stored. This exactly matches the layout of the SparsityPattern. There is some overlap of matrix rows between processes to allow for independent Finite Element assembly, after which, the ghost rows should be sent to the row owning processes by calling scatter_rev().

Note
  The block size of the matrix is given by the block size of the input SparsityPattern.

Parameters

  [in] | p | The sparsity pattern which describes the parallel distribution and the non-zero structure.
  [in] | mode | Block mode. When the block size is greater than one, the storage can be "compact" where each matrix entry refers to a block of data (stored row major), or "expanded" where each matrix entry is individual. In the "expanded" case, the sparsity is expanded for every entry in the block, and the block size of the matrix is set to (1, 1).

## MatrixCSR() [2/4]

template<typename Scalar, typename Container = std::vector<Scalar>, typename ColContainer = std::vector<std::int32_t>, typename RowPtrContainer = std::vector<std::int64_t>>

MatrixCSR | ( | MatrixCSR< Scalar, Container, ColContainer, RowPtrContainer > && | A | ) |

default

Move constructor

Todo
  Check handling of MPI_Request

## MatrixCSR() [3/4]

template<typename Scalar, typename Container = std::vector<Scalar>, typename ColContainer = std::vector<std::int32_t>, typename RowPtrContainer = std::vector<std::int64_t>>

MatrixCSR | ( | const MatrixCSR< Scalar, Container, ColContainer, RowPtrContainer > & | A | ) |

default

Copy constructor

Todo
  Check handling of MPI_Request

## MatrixCSR() [4/4]

template<typename Scalar, typename Container = std::vector<Scalar>, typename ColContainer = std::vector<std::int32_t>, typename RowPtrContainer = std::vector<std::int64_t>>
template<typename Scalar0, typename Container0, typename ColContainer0, typename RowPtrContainer0>

MatrixCSR | ( | const MatrixCSR< Scalar0, Container0, ColContainer0, RowPtrContainer0 > & | A | ) |

inline explicit

Copy-convert matrix, possibly using to different container types.

Examples of use for this constructor include copying a matrix to a different value type, or copying the matrix to a GPU.

Template Parameters

  Mat |

Parameters

  A | Matrix to copy.

## Member Function Documentation

## add()

template<typename Scalar, typename Container = std::vector<Scalar>, typename ColContainer = std::vector<std::int32_t>, typename RowPtrContainer = std::vector<std::int64_t>>
template<int BS0 = 1, int BS1 = 1>

void add | ( | std::span< const value_type > | x,
|  | std::span< const std::int32_t > | rows,
|  | 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 into.
  All indices are local to the calling MPI rank and entries may go into ghost rows.
  Use scatter_rev after all entries have been added to send ghost rows to owners. Adding more entries after scatter_rev is allowed, but another call to scatter_rev will then be required.

Template Parameters

  BS0 | Row block size of data
  BS1 | Column block size of data

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

## block_size()

template<typename Scalar, typename Container = std::vector<Scalar>, typename ColContainer = std::vector<std::int32_t>, typename RowPtrContainer = std::vector<std::int64_t>>

std::array< int, 2 > block_size | ( |  | ) | const

inline

Get block sizes.

Returns
  Block sizes for rows (0) and columns (1).

## cols()

template<typename Scalar, typename Container = std::vector<Scalar>, typename ColContainer = std::vector<std::int32_t>, typename RowPtrContainer = std::vector<std::int64_t>>

const column_container_type & cols | ( |  | ) | const

inline

Get local column indices

Note
  Includes columns in ghost rows

## index_map()

template<typename Scalar, typename Container = std::vector<Scalar>, typename ColContainer = std::vector<std::int32_t>, typename RowPtrContainer = std::vector<std::int64_t>>

std::shared_ptr< const common::IndexMap > index_map | ( | int | dim | ) | const

inline

Index map for the row or column space.

The row index map contains ghost entries for rows which may be inserted into and the column index map contains all local and ghost columns that may exist in the owned rows.

Returns
  Row (0) or column (1) index map.

## mat_add_values()

template<typename Scalar, typename Container = std::vector<Scalar>, typename ColContainer = std::vector<std::int32_t>, typename RowPtrContainer = std::vector<std::int64_t>>
template<int BS0 = 1, int BS1 = 1>

auto mat_add_values | ( |  | ) |

inline

Insertion functor for adding values to a matrix. It is typically used in finite element assembly functions.

Create a function to add values to a MatrixCSR. The function signature is int mat_add_fn(std::span<const std::int32_t rows, std::span<const std::int32_t cols, std::span<const value_type> data). The rows and columns use process local indexing, and the given rows and columns must pre-exist in the sparsity pattern of the matrix. Insertion into "ghost" rows (in the ghost region of the row IndexMap) is permitted, so long as there are correct entries in the sparsity pattern.

Note
  Using rows or columns which are not in the sparsity will result in undefined behaviour (or an assert failure in Debug mode).
  Matrix block size may be (1, 1) or (BS0, BS1)
  Data block size may be (1, 1) or (BS0, BS1)

Template Parameters

  BS0 | Row block size of data for insertion
  BS1 | Column block size of data for insertion

Returns
  Function for inserting values into A

## mat_set_values()

template<typename Scalar, typename Container = std::vector<Scalar>, typename ColContainer = std::vector<std::int32_t>, typename RowPtrContainer = std::vector<std::int64_t>>
template<int BS0 = 1, int BS1 = 1>

auto mat_set_values | ( |  | ) |

inline

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

Create a function to set values in a MatrixCSR. The function signature is int mat_set_fn(std::span<const std::int32_t rows, std::span<const std::int32_t cols, std::span<const value_type> data). The rows and columns use process local indexing, and the given rows and columns must pre-exist in the sparsity pattern of the matrix. Insertion into "ghost" rows (in the ghost region of the row IndexMap) is permitted, so long as there are correct entries in the sparsity pattern.

Note
  Using rows or columns which are not in the sparsity will result in undefined behaviour (or an assert failure in Debug mode).
  Matrix block size may be (1, 1) or (BS0, BS1)
  Data block size may be (1, 1) or (BS0, BS1)

Template Parameters

  BS0 | Row block size of data for insertion
  BS1 | Column block size of data for insertion

Returns
  Function for inserting values into A

## mult()

template<typename Scalar, typename V, typename W, typename X>

void mult | ( | Vector< value_type > & | x,
|  | Vector< value_type > & | y )

Compute the product y += Ax.

The vectors x and y must have parallel layouts that are compatible with A. In detail, x must have the same IndexMap as the matrix columns, A.index_map(1) and y must have the same owned indices as the matrix rows in A.index_map(0). Only owned entries of y are updated, so any ghost entries of y are not affected.

Parameters

  [in] | x | Vector to apply A to.
  [in,out] | y | Vector to accumulate the result into.

Computes y += A*x for a parallel CSR matrix A and parallel dense vectors x,y

## off_diag_offset()

template<typename Scalar, typename Container = std::vector<Scalar>, typename ColContainer = std::vector<std::int32_t>, typename RowPtrContainer = std::vector<std::int64_t>>

const rowptr_container_type & 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' by the caller if not required.

## row_ptr()

template<typename Scalar, typename Container = std::vector<Scalar>, typename ColContainer = std::vector<std::int32_t>, typename RowPtrContainer = std::vector<std::int64_t>>

const rowptr_container_type & row_ptr | ( |  | ) | const

inline

Get local row pointers.

Note
  Includes pointers to ghost rows

## scatter_rev()

template<typename Scalar, typename Container = std::vector<Scalar>, typename ColContainer = std::vector<std::int32_t>, typename RowPtrContainer = std::vector<std::int64_t>>

void scatter_rev | ( |  | ) |

inline

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

This process is analogous to scatter_rev for Vector except that the values are always accumulated on the owning process.

## scatter_rev_begin()

template<typename Scalar, typename Container = std::vector<Scalar>, typename ColContainer = std::vector<std::int32_t>, typename RowPtrContainer = std::vector<std::int64_t>>

void scatter_rev_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::scatter_rev_end(). Between the two calls matrix values must not be changed.
  This function does not change the matrix data. Data update only occurs with scatter_rev_end().

## scatter_rev_end()

template<typename Scalar, typename Container = std::vector<Scalar>, typename ColContainer = std::vector<std::int32_t>, typename RowPtrContainer = std::vector<std::int64_t>>

void scatter_rev_end | ( |  | ) |

inline

End transfer of ghost row data to owning ranks.

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

## set() [1/2]

template<typename Scalar, typename Container = std::vector<Scalar>, typename ColContainer = std::vector<std::int32_t>, typename RowPtrContainer = std::vector<std::int64_t>>
template<int BS0, int BS1>

void set | ( | std::span< const value_type > | x,
|  | std::span< const std::int32_t > | rows,
|  | 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 scatter_rev. Using before scatter_rev will set the values correctly, but incoming values may get added to them during a subsequent reverse scatter operation.

Template Parameters

  BS0 | Data row block size
  BS1 | Data column block size

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]

template<typename Scalar, typename Container = std::vector<Scalar>, typename ColContainer = std::vector<std::int32_t>, typename RowPtrContainer = std::vector<std::int64_t>>

void set | ( | value_type | x | ) |

inline

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

Deprecated
  Use std::ranges::fill(A.values(), x) instead.

Parameters

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

## squared_norm()

template<typename Scalar, typename Container = std::vector<Scalar>, typename ColContainer = std::vector<std::int32_t>, typename RowPtrContainer = std::vector<std::int64_t>>

double squared_norm | ( |  | ) | const

inline

Compute the Frobenius norm squared across all processes.

Note
  MPI Collective

## to_dense()

template<typename Scalar, typename Container = std::vector<Scalar>, typename ColContainer = std::vector<std::int32_t>, typename RowPtrContainer = std::vector<std::int64_t>>

std::vector< value_type > 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.
  If the block size is greater than 1, the entries are expanded.

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

## values() [1/2]

template<typename Scalar, typename Container = std::vector<Scalar>, typename ColContainer = std::vector<std::int32_t>, typename RowPtrContainer = std::vector<std::int64_t>>

container_type & values | ( |  | ) |

inline

Get local data values.

Note
  Includes ghost values.

## values() [2/2]

template<typename Scalar, typename Container = std::vector<Scalar>, typename ColContainer = std::vector<std::int32_t>, typename RowPtrContainer = std::vector<std::int64_t>>

const container_type & values | ( |  | ) | const

inline

Get local values (const version).

Note
  Includes ghost values

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

- /build/fenics-dolfinx-PdyzCE/fenics-dolfinx-0.10.0.post5/cpp/dolfinx/la/MatrixCSR.h