gko::batch::MultiVector#

The right-hand-side and solution container for batched solvers. Holds one dense block per batch item, with every item sharing the same (num_rows, num_rhs) shape. Backed by a single contiguous values array indexed by batch_id * num_rows * num_rhs.

template<typename ValueType = default_precision>
class MultiVector #

Inherits from

  • public gko::EnablePolymorphicObject<MultiVector<default_precision>>

  • public gko::EnablePolymorphicAssignment<MultiVector<default_precision>>

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

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

  • public ConvertibleTo<MultiVector<next_precision<default_precision>>>

MultiVector stores multiple vectors in a batched fashion and is useful for batched operations. For example, two batch items, each a 3 x 2 multi-vector, would be laid out as:

batch item 0      batch item 1
  1 2               3 4
  1 2               3 4
  1 2               3 4

In memory, both items are stored consecutively as a single row-major array:

[ 1 2  1 2  1 2 | 3 4  3 4  3 4 ]
  item 0          item 1

The accessor at() can be used to reach an individual entry of a specific batch item.

The values of the different batch items are stored consecutively and in each batch item, the multi-vectors are stored in a row-major fashion.

Template Parameters:

ValueType – precision of multi-vector elements

Public Functions

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

Creates a mutable view (of matrix::Dense type) of one item of the Batch MultiVector 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 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 matrix::Dense type) of one item of the Batch MultiVector 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 matrix::Dense object with the data from the batch item at the given index.

inline batch_dim<2> get_size() const#

Returns the batch size.

Returns:

the batch size

inline size_type get_num_batch_items() const#

Returns the number of batch items.

Returns:

the number of batch items

inline dim<2> get_common_size() const#

Returns the common size of the batch items.

Returns:

the common size stored

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 *get_values_for_item(size_type batch_id) noexcept#

Returns a pointer to the array of values of the multi-vector 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 multi-vector 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_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 &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 vector is stored at (e.g. trying to call this method on a GPU multi-vector from the OMP results in a runtime error)

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 vector is stored at (e.g. trying to call this method on a GPU multi-vector from the OMP results in a runtime error)

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 vector. 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 vector is stored at (e.g. trying to call this method on a GPU multi-vector from the OMP results in a runtime error)

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 vector is stored at (e.g. trying to call this method on a GPU multi-vector from the OMP results in a runtime error)

Parameters:

  • batch_id – the batch item index to be queried

  • row – the row of the requested element

  • col – the column of the requested element

void scale(ptr_param<const MultiVector<ValueType>> alpha)#

Scales the vector with a scalar (aka: BLAS scal).

Note

If alpha is 1x1 MultiVector matrix, the entire multi-vector (all batches) is scaled by alpha. If it is a MultiVector row vector of values, then i-th column of the vector is scaled with the i-th element of alpha (the number of columns of alpha has to match the number of columns of the multi-vector). If it is a MultiVector of the same size as this, then an element wise scaling is performed.

Parameters:

alpha – the scalar

void add_scaled(
ptr_param<const MultiVector<ValueType>> alpha,
ptr_param<const MultiVector<ValueType>> b,
)#

Adds b scaled by alpha to the vector (aka: BLAS axpy).

Note

If alpha is 1x1 MultiVector matrix, the entire multi-vector (all batches) is scaled by alpha. If it is a MultiVector row vector of values, then i-th column of the vector is scaled with the i-th element of alpha (the number of columns of alpha has to match the number of columns of the multi-vector).

Parameters:

  • alpha – the scalar

  • b – a multi-vector of the same dimension as this

void compute_dot(
ptr_param<const MultiVector<ValueType>> b,
ptr_param<MultiVector<ValueType>> result,
) const#

Computes the column-wise dot product of each multi-vector in this batch and its corresponding entry in b.

Parameters:

  • b – a MultiVector of same dimension as this

  • result – a MultiVector row vector, used to store the dot product

void compute_conj_dot(
ptr_param<const MultiVector<ValueType>> b,
ptr_param<MultiVector<ValueType>> result,
) const#

Computes the column-wise conjugate dot product of each multi-vector in this batch and its corresponding entry in b. If the vector has complex value_type, then the conjugate of this is taken.

Parameters:

  • b – a MultiVector of same dimension as this

  • result – a MultiVector row vector, used to store the dot product (the number of column in the vector must match the number of columns of this)

void compute_norm2(
ptr_param<MultiVector<remove_complex<ValueType>>> result,
) const#

Computes the Euclidean (L^2) norm of each multi-vector in this batch.

Parameters:

result – a MultiVector, used to store the norm (the number of columns in the vector must match the number of columns of this)

void fill(ValueType value)#

Fills the input MultiVector with a given value

Parameters:

value – the value to be filled

Public Static Functions

static std::unique_ptr<MultiVector> create_with_config_of(
ptr_param<const MultiVector> other,
)#

Creates a MultiVector with the configuration of another MultiVector.

Parameters:

other – The other multi-vector whose configuration needs to copied.

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

Creates an uninitialized multi-vector of the specified size.

Parameters:

  • exec – Executor associated to the vector

  • size – size of the batch multi vector

Returns:

A smart pointer to the newly created matrix.

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

Creates a MultiVector 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 vector.

Parameters:

  • exec – Executor associated to the vector

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

  • values – array of values

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

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

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

static std::unique_ptr<const MultiVector> 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 multi-vector from a constant array.

Parameters:

  • exec – the executor to create the vector on

  • size – the dimensions of the vector

  • values – the value array of the vector

  • stride – the row-stride of the vector

Returns:

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