gko::matrix::Fbcsr#

Fixed-size block CSR. Stores nonzeros as dense block_size × block_size sub-blocks indexed by CSR-style block-row pointers and block-column indices. The right choice for matrices arising from vector PDEs or finite-element systems with a small, fixed number of unknowns per mesh entity.

template<typename ValueType = default_precision, typename IndexType = int32>
class Fbcsr #

Inherits from

  • public gko::EnableLinOp<Fbcsr<default_precision, int32>>

  • public ConvertibleTo<Fbcsr<next_precision<default_precision>, int32>>

  • public ConvertibleTo<Fbcsr<next_precision<default_precision, 2>, int32>>

  • public ConvertibleTo<Fbcsr<next_precision<default_precision, 3>, int32>>

  • public ConvertibleTo<Dense<default_precision>>

  • public ConvertibleTo<Csr<default_precision, int32>>

  • public ConvertibleTo<SparsityCsr<default_precision, int32>>

  • public gko::DiagonalExtractable<default_precision>

  • public gko::ReadableFromMatrixData<default_precision, int32>

  • public gko::WritableToMatrixData<default_precision, int32>

  • public gko::Transposable

  • public gko::EnableAbsoluteComputation<remove_complex<Fbcsr<default_precision, int32>>>

Fixed-block compressed sparse row storage matrix format.

FBCSR is a matrix format meant for matrices having a natural block structure made up of small, dense, disjoint blocks. It is similar to CSR

The block size is expected to be known in advance and passed to the constructor.

See also

Csr. However, unlike Csr, each non-zero location stores a small dense block of entries having a constant size. This reduces the number of integers that need to be stored in order to refer to a given non-zero entry, and enables efficient implementation of certain block methods.

The nonzero elements are stored in a 1D array row-wise, and accompanied with a row pointer array which stores the starting index of each block-row. An additional block-column index array is used to identify the block-column of each nonzero block.

The Fbcsr LinOp supports different operations:

matrix::Fbcsr *A, *B, *C;      // matrices
matrix::Dense *b, *x;        // vectors tall-and-skinny matrices
matrix::Dense *alpha, *beta; // scalars of dimension 1x1

// Applying to Dense matrices computes an SpMV/SpMM product
A->apply(b, x)              // x = A*b
A->apply(alpha, b, beta, x) // x = alpha*A*b + beta*x

Note

The total number of rows and the number of columns are expected to be divisible by the block size.

Template Parameters:

  • ValueType – precision of matrix elements

  • IndexType – precision of matrix indexes

Public Functions

void convert_to(Csr<ValueType, IndexType> *result) const override#

Converts the matrix to CSR format

Note

Any explicit zeros in the original matrix are retained in the converted result.

void convert_to(
SparsityCsr<ValueType, IndexType> *result,
) const override#

Get the block sparsity pattern in CSR-like format

Note

The actual non-zero values are never copied; the result always has a value array of size 1 with the value 1.

void read(const mat_data &data) override#

Reads a matrix_data into Fbcsr format. Requires the block size to be set beforehand

See also

set_block_size.

Warning

Unlike Csr::read, here explicit non-zeros are NOT dropped.

virtual std::unique_ptr<LinOp> transpose() const override#

Returns a LinOp representing the transpose of the Transposable object.

Returns:

a pointer to the new transposed object

virtual std::unique_ptr<LinOp> conj_transpose() const override#

Returns a LinOp representing the conjugate transpose of the Transposable object.

Returns:

a pointer to the new conjugate transposed object

virtual std::unique_ptr<Diagonal<ValueType>> extract_diagonal(
) const override#

Extracts the diagonal entries of the matrix into a vector.

Parameters:

diag – the vector into which the diagonal will be written

virtual std::unique_ptr<absolute_type> compute_absolute(
) const override#

Gets the AbsoluteLinOp

Returns:

a pointer to the new absolute object

virtual void compute_absolute_inplace() override#

Compute absolute inplace on each element.

void sort_by_column_index()#

Sorts the values blocks and block-column indices in each row by column index

bool is_sorted_by_column_index() const#

Tests if all row entry pairs (value, col_idx) are sorted by column index

Returns:

True if all row entry pairs (value, col_idx) are sorted by column index

inline value_type *get_values() noexcept#
Returns:

The values of the matrix.

inline const value_type *get_const_values() const noexcept#

Note

This is the constant version of the function, which can be significantly more memory efficient than the non-constant version, so always prefer this version.

Returns:

The values of the matrix.

inline index_type *get_col_idxs() noexcept#
Returns:

The column indexes of the matrix.

inline const index_type *get_const_col_idxs() const noexcept#

Note

This is the constant version of the function, which can be significantly more memory efficient than the non-constant version, so always prefer this version.

Returns:

The column indexes of the matrix.

inline index_type *get_row_ptrs() noexcept#
Returns:

The row pointers of the matrix.

inline const index_type *get_const_row_ptrs() const noexcept#

Note

This is the constant version of the function, which can be significantly more memory efficient than the non-constant version, so always prefer this version.

Returns:

The row pointers of the matrix.

inline size_type get_num_stored_elements() const noexcept#
Returns:

The number of elements explicitly stored in the matrix

inline size_type get_num_stored_blocks() const noexcept#
Returns:

The number of non-zero blocks explicitly stored in the matrix

inline int get_block_size() const noexcept#
Returns:

The fixed block size for this matrix

inline index_type get_num_block_rows() const noexcept#
Returns:

The number of block-rows in the matrix

inline index_type get_num_block_cols() const noexcept#
Returns:

The number of block-columns in the matrix

Fbcsr &operator=(const Fbcsr&)#

Copy-assigns an Fbcsr matrix. Preserves the executor, copies data and block size from the input.

Fbcsr &operator=(Fbcsr&&)#

Move-assigns an Fbcsr matrix. Preserves the executor, moves the data over preserving size and stride. Leaves the moved-from object in an empty state (0x0 with no nonzeros, but valid row pointers).

Fbcsr(const Fbcsr&)#

Copy-constructs an Ell matrix. Inherits executor and data.

Fbcsr(Fbcsr&&)#

Move-constructs an Fbcsr matrix. Inherits executor and data. The moved-from object is empty (0x0 with no nonzeros, but valid row pointers).

Public Static Functions

static std::unique_ptr<Fbcsr> create(
std::shared_ptr<const Executor> exec,
int block_size = 1,
)#

Creates an uninitialized FBCSR matrix with the given block size.

Parameters:

  • exec – Executor associated to the matrix

  • block_size – The desired size of the dense square nonzero blocks; defaults to 1.

Returns:

A smart pointer to the newly created matrix.

static std::unique_ptr<Fbcsr> create(
std::shared_ptr<const Executor> exec,
const dim<2> &size,
size_type num_nonzeros,
int block_size,
)#

Creates an uninitialized FBCSR matrix of the specified size.

Parameters:

  • exec – Executor associated to the matrix

  • size – size of the matrix

  • num_nonzeros – number of stored nonzeros. It needs to be a multiple of block_size * block_size.

  • block_size – size of the small dense square blocks

Returns:

A smart pointer to the newly created matrix.

static std::unique_ptr<Fbcsr> create(
std::shared_ptr<const Executor> exec,
const dim<2> &size,
int block_size,
array<value_type> values,
array<index_type> col_idxs,
array<index_type> row_ptrs,
)#

Creates a FBCSR matrix from already allocated (and initialized) row pointer, column index and value arrays.

Note

If one of row_ptrs, col_idxs or values is not an rvalue, not an array of IndexType, IndexType and ValueType, respectively, or is on the wrong executor, an internal copy of that array will be created, and the original array data will not be used in the matrix.

Parameters:

  • exec – Executor associated to the matrix

  • size – size of the matrix

  • block_size – Size of the small square dense nonzero blocks

  • values – the value array of the matrix, stored in column-major order for each block

  • col_idxs – the block column index array of the matrix

  • row_ptrs – the block row pointer array of the matrix

Returns:

A smart pointer to the newly created matrix.

template<typename InputValueType, typename InputColumnIndexType, typename InputRowPtrType>
static inline std::unique_ptr<Fbcsr> create(
std::shared_ptr<const Executor> exec,
const dim<2> &size,
int block_size,
std::initializer_list<InputValueType> values,
std::initializer_list<InputColumnIndexType> col_idxs,
std::initializer_list<InputRowPtrType> row_ptrs,
)#

create(std::shared_ptr<const Executor>,const dim<2>&, int, array<value_type>, array<index_type>,array<index_type>)

create(std::shared_ptr<const Executor>,const dim<2>&, int, array<value_type>, array<index_type>,array<index_type>)

static std::unique_ptr<const Fbcsr> create_const(
std::shared_ptr<const Executor> exec,
const dim<2> &size,
int blocksize,
gko::detail::const_array_view<ValueType> &&values,
gko::detail::const_array_view<IndexType> &&col_idxs,
gko::detail::const_array_view<IndexType> &&row_ptrs,
)#

Creates a constant (immutable) Fbcsr matrix from a constant array.

Parameters:

  • exec – the executor to create the matrix on

  • size – the dimensions of the matrix

  • blocksize – the block size of the matrix

  • values – the value array of the matrix, stored in column-major order for each block

  • col_idxs – the block column index array of the matrix

  • row_ptrs – the block row pointer array of the matrix

Returns:

A smart pointer to the constant matrix wrapping the input arrays (if they reside on the same executor as the matrix) or a copy of the arrays on the correct executor.