`gko::matrix::Ell`#

Equal-length rows. Pads every row to the longest row’s nonzero count and stores values/columns in a regular 2-D layout. Memory-efficient only for matrices with a uniform nonzero distribution; well suited to GPU SpMV with predictable access patterns.

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

Inherits from

public gko::EnableLinOp<Ell<default_precision, int32>>
public ConvertibleTo<Ell<next_precision<default_precision>, int32>>
public ConvertibleTo<Ell<next_precision<default_precision, 2>, int32>>
public ConvertibleTo<Ell<next_precision<default_precision, 3>, int32>>
public ConvertibleTo<Dense<default_precision>>
public ConvertibleTo<Csr<default_precision, int32>>
public gko::DiagonalExtractable<default_precision>
public gko::ReadableFromMatrixData<default_precision, int32>
public gko::WritableToMatrixData<default_precision, int32>
public gko::EnableAbsoluteComputation<remove_complex<Ell<default_precision, int32>>>

ELL is a matrix format where stride with explicit zeros is used such that all rows have the same number of stored elements. The number of elements stored in each row is the largest number of nonzero elements in any of the rows (obtainable through get_num_stored_elements_per_row() method). This removes the need of a row pointer like in the CSR format, and allows for SIMD processing of the distinct rows. For efficient processing, the nonzero elements and the corresponding column indices are stored in column-major fashion. The columns are padded to the length by user-defined stride parameter whose default value is the number of rows of the matrix.

This implementation uses the column index value invalid_index<IndexType>() to mark padding entries that are not part of the sparsity pattern.

Template Parameters:

ValueType – precision of matrix elements
IndexType – precision of matrix indexes

Public Functions

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.

inline value_type *get_values() noexcept#

Returns the values of the matrix.

Returns:: the values of the matrix.

inline const value_type *get_const_values() const noexcept#

Returns the values of the matrix.

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.

Returns:: the column indexes of the matrix.

inline const index_type *get_const_col_idxs() const noexcept#

Returns the column indexes of the matrix.

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 size_type get_num_stored_elements_per_row() const noexcept#

Returns the number of stored elements per row.

Returns:: the number of stored elements per row.

inline size_type get_stride() const noexcept#

Returns the stride of the matrix.

Returns:: the stride of the matrix.

inline size_type get_num_stored_elements() const noexcept#

Returns the number of elements explicitly stored in the matrix.

Returns:: the number of elements explicitly stored in the matrix

inline value_type &val_at(size_type row, size_type idx) noexcept#

Returns the idx-th non-zero element of the row-th row .

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 matrix from the OMP results in a runtime error)

Parameters:

row – the row of the requested element
idx – the idx-th stored element of the row

inline value_type val_at(size_type row, size_type idx) const noexcept#

Returns the idx-th non-zero element of the row-th row .

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 matrix from the OMP results in a runtime error)

Parameters:

row – the row of the requested element
idx – the idx-th stored element of the row

inline index_type &col_at(size_type row, size_type idx) noexcept#

Returns the idx-th column index of the row-th row .

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 matrix from the OMP results in a runtime error)

Parameters:

row – the row of the requested element
idx – the idx-th stored element of the row

inline index_type col_at(size_type row, size_type idx) const noexcept#

Returns the idx-th column index of the row-th row .

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 matrix from the OMP results in a runtime error)

Parameters:

row – the row of the requested element
idx – the idx-th stored element of the row

device_view get_device_view()#: get the non-owning device view

const_device_view get_const_device_view() const#: get the const non-owning device view

Ell &operator=(const Ell&)#: Copy-assigns an Ell matrix. Preserves the executor, reallocates the matrix with minimal stride if the dimensions don’t match, then copies the data over, ignoring padding.

Ell &operator=(Ell&&)#: Move-assigns an Ell matrix. Preserves the executor, moves the data over preserving size and stride. Leaves the moved-from object in an empty state (0x0 with empty Array).

Ell(const Ell&)#: Copy-constructs an Ell matrix. Inherits executor and dimensions, but copies data without padding.

Ell(Ell&&)#: Move-constructs an Ell matrix. Inherits executor, dimensions and data with padding. The moved-from object is empty (0x0 with empty Array).

Public Static Functions

static std::unique_ptr<Ell> create( std::shared_ptr<const Executor> exec, const dim<2> &size = {}, size_type num_stored_elements_per_row = 0, size_type stride = 0, )#

Creates an uninitialized Ell matrix of the specified size.

Parameters:

exec – Executor associated to the matrix
size – size of the matrix
num_stored_elements_per_row – the number of stored elements per row
stride – stride of the columns. If it is set to 0, size[0] will be used instead.

Returns:

A smart pointer to the newly created matrix.

static std::unique_ptr<Ell> create( std::shared_ptr<const Executor> exec, const dim<2> &size, array<value_type> values, array<index_type> col_idxs, size_type num_stored_elements_per_row, size_type stride, )#

Creates an ELL matrix from already allocated (and initialized) column index and value arrays.

Note

If one of col_idxs or values is not an rvalue, not an array of 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
values – array of matrix values
col_idxs – array of column indexes
num_stored_elements_per_row – the number of stored elements per row
stride – stride of the rows

Returns:

A smart pointer to the newly created matrix.

template<typename InputValueType, typename InputColumnIndexType> static inline std::unique_ptr<Ell> create( std::shared_ptr<const Executor> exec, const dim<2> &size, std::initializer_list<InputValueType> values, std::initializer_list<InputColumnIndexType> col_idxs, size_type num_stored_elements_per_row, size_type stride, )#

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

static std::unique_ptr<const Ell> create_const( std::shared_ptr<const Executor> exec, const dim<2> &size, gko::detail::const_array_view<ValueType> &&values, gko::detail::const_array_view<IndexType> &&col_idxs, size_type num_stored_elements_per_row, size_type stride, )#

Creates a constant (immutable) Ell matrix from a set of constant arrays.

Parameters:

exec – the executor to create the matrix on
size – the dimensions of the matrix
values – the value array of the matrix
col_idxs – the column index array of the matrix
num_stored_elements_per_row – the number of stored nonzeros per row
stride – the column-stride of the value and column index array

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.

gko::matrix::Ell#

`gko::matrix::Ell`#