gko::batch::matrix::Dense#

Batched dense matrix. Each item is a row-major dense block; storage is a single contiguous values array offset by batch_id * num_rows * num_cols. Use for batches of small dense systems whose dimensions are too small to fan out cuBLAS / cuSPARSE calls profitably.

template<typename ValueType = default_precision>
class Dense #

Inherits from

  • public gko::batch::EnableBatchLinOp<Dense<default_precision>>

  • public ConvertibleTo<Dense<next_precision<default_precision, 2>>>

  • public ConvertibleTo<Dense<next_precision<default_precision, 3>>>

  • public ConvertibleTo<Dense<next_precision<default_precision>>>

Dense is a batch matrix format which explicitly stores all values of the matrix in each of the batches.

The values in each of the batches are stored in row-major format (values belonging to the same row appear consecutive in the memory and the values of each batch item are also stored consecutively in memory).

Note

Though the storage layout is the same as the multi-vector object, the class semantics and the operations it aims to provide are different. Hence it is recommended to create multi-vector objects if the user means to view the data as a set of vectors.

Template Parameters:

ValueType – precision of matrix elements

Public Functions

std::unique_ptr<unbatch_type> create_view_for_item(
size_type item_id,
)#

Creates a mutable view (of gko::matrix::Dense type) of one item of the batch::matrix::Dense<value_type> object. Does not perform any deep copies, but only returns a view of the data.

Parameters:

item_id – The index of the batch item

Returns:

a gko::matrix::Dense object with the data from the batch item at the given index.

std::unique_ptr<const unbatch_type> create_const_view_for_item(
size_type item_id,
) const#

Creates a mutable view (of gko::matrix::Dense type) of one item of the batch::matrix::Dense<value_type> object. Does not perform any deep copies, but only returns a view of the data.

Parameters:

item_id – The index of the batch item

Returns:

a gko::matrix::Dense object with the data from the batch item at the given index.

inline size_type get_cumulative_offset(size_type batch_id) const#

Get the cumulative storage size offset

Parameters:

batch_id – the batch id

Returns:

the cumulative offset

inline value_type *get_values() noexcept#

Returns a pointer to the array of values of the multi-vector

Returns:

the pointer to the array of values

inline const value_type *get_const_values() const noexcept#

Returns a pointer to the array of values of the multi-vector

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 pointer to the array of values

inline value_type &at(
size_type batch_id,
size_type row,
size_type col,
)#

Returns a single element for a particular batch item.

Note

the method has to be called on the same Executor the matrix is stored at (e.g. trying to call this method on a GPU Dense object from the OMP may result in incorrect behaviour)

Parameters:

  • batch_id – the batch item index to be queried

  • row – the row of the requested element

  • col – the column of the requested element

inline value_type at(
size_type batch_id,
size_type row,
size_type col,
) const#

Returns a single element for a particular batch item.

Note

the method has to be called on the same Executor the matrix is stored at (e.g. trying to call this method on a GPU Dense object from the OMP may result in incorrect behaviour)

Parameters:

  • batch_id – the batch item index to be queried

  • row – the row of the requested element

  • col – the column of the requested element

inline ValueType &at(size_type batch_id, size_type idx) noexcept#

Returns a single element for a particular batch item.

Useful for iterating across all elements of the matrix. However, it is less efficient than the two-parameter variant of this method.

Note

the method has to be called on the same Executor the matrix is stored at (e.g. trying to call this method on a GPU Dense object from the OMP may result in incorrect behaviour)

Parameters:

  • batch_id – the batch item index to be queried

  • idx – a linear index of the requested element

inline ValueType at(size_type batch_id, size_type idx) const noexcept#

Returns a single element for a particular batch item.

Note

the method has to be called on the same Executor the matrix is stored at (e.g. trying to call this method on a GPU Dense object from the OMP may result in incorrect behaviour)

Parameters:

  • batch_id – the batch item index to be queried

  • row – the row of the requested element

  • col – the column of the requested element

inline value_type *get_values_for_item(size_type batch_id) noexcept#

Returns a pointer to the array of values of the matrix for a specific batch item.

Parameters:

batch_id – the id of the batch item.

Returns:

the pointer to the array of values

inline const value_type *get_const_values_for_item(
size_type batch_id,
) const noexcept#

Returns a pointer to the array of values of the matrix for a specific batch item.

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.

Parameters:

batch_id – the id of the batch item.

Returns:

the pointer to the array of values

inline size_type get_num_stored_elements() const noexcept#

Returns the number of elements explicitly stored in the batch matrix, cumulative across all the batch items.

Returns:

the number of elements explicitly stored in the vector, cumulative across all the batch items

inline size_type get_num_elements_per_item() const noexcept#

Returns the number of stored elements in each batch item.

Returns:

the number of stored elements per batch item.

void apply(
ptr_param<const MultiVector<value_type>> b,
ptr_param<MultiVector<value_type>> x,
)#

Apply the matrix to a multi-vector. Represents the matrix vector multiplication, x = A * b, where x and b are both multi-vectors.

Parameters:

  • b – the multi-vector to be applied to

  • x – the output multi-vector

void apply(
ptr_param<const MultiVector<value_type>> alpha,
ptr_param<const MultiVector<value_type>> b,
ptr_param<const MultiVector<value_type>> beta,
ptr_param<MultiVector<value_type>> x,
)#

Apply the matrix to a multi-vector with a linear combination of the given input vector. Represents the matrix vector multiplication, x = alpha * A

  • b + beta * x, where x and b are both multi-vectors.

Parameters:

  • alpha – the scalar to scale the matrix-vector product with

  • b – the multi-vector to be applied to

  • beta – the scalar to scale the x vector with

  • x – the output multi-vector

void scale(
const array<value_type> &row_scale,
const array<value_type> &col_scale,
)#

Performs in-place row and column scaling for this matrix.

Parameters:

  • row_scale – the row scalars

  • col_scale – the column scalars

void scale_add(
ptr_param<const MultiVector<value_type>> alpha,
ptr_param<const batch::matrix::Dense<value_type>> b,
)#

Performs the operation this = alpha*this + b.

Note

Performs the operation in-place for this batch matrix

Parameters:

  • alpha – the scalar to multiply this matrix

  • b – the matrix to add

void add_scaled_identity(
ptr_param<const MultiVector<value_type>> alpha,
ptr_param<const MultiVector<value_type>> beta,
)#

Performs the operation this = alpha*I + beta*this.

Note

Performs the operation in-place for this batch matrix

Parameters:

  • alpha – the scalar for identity

  • beta – the scalar to multiply this matrix

Public Static Functions

static std::unique_ptr<Dense> create(
std::shared_ptr<const Executor> exec,
const batch_dim<2> &size = batch_dim<2>{},
)#

Creates an uninitialized Dense matrix of the specified size.

Parameters:

  • exec – Executor associated to the matrix

  • size – size of the matrix

Returns:

A smart pointer to the newly created matrix.

static std::unique_ptr<Dense> create(
std::shared_ptr<const Executor> exec,
const batch_dim<2> &size,
array<value_type> values,
)#

Creates a Dense matrix from an already allocated (and initialized) array.

Note

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

Parameters:

  • exec – Executor associated to the matrix

  • size – sizes of the batch matrices in a batch_dim object

  • values – array of matrix values

Returns:

A smart pointer to the newly created matrix.

template<typename InputValueType>
static inline std::unique_ptr<Dense> create(
std::shared_ptr<const Executor> exec,
const batch_dim<2> &size,
std::initializer_list<InputValueType> values,
)#

create(std::shared_ptr<const Executor>,const batch_dim<2>&, array<value_type>)

create(std::shared_ptr<const Executor>,const batch_dim<2>&, array<value_type>)

static std::unique_ptr<const Dense> create_const(
std::shared_ptr<const Executor> exec,
const batch_dim<2> &sizes,
gko::detail::const_array_view<ValueType> &&values,
)#

Creates a constant (immutable) batch dense matrix from a constant array.

Parameters:

  • exec – the executor to create the matrix on

  • size – the dimensions of the matrix

  • values – the value array of the matrix

Returns:

A smart pointer to the constant matrix wrapping the input array (if it resides on the same executor as the matrix) or a copy of the array on the correct executor.

Returns:

A smart pointer to the newly created matrix.