gko::matrix_data#

Host-side, executor-independent representation of a sparse matrix: a dim<2> size and a std::vector of (row, column, value) triples. Used as the assembly format that every Ginkgo matrix type knows how to ingest — load a Matrix Market file into a matrix_data, then read() it into the device-side Csr, Coo, Ell, … representation of your choice.

matrix_data is intentionally not a performance type — it lives on the host, sorts in row-major order, requires entries to be unique (row, col) pairs, and is meant for utility paths (I/O, assembly, test fixtures) rather than for in-kernel use.

For an overview of the assembly flow, see the matrix-data concept page.

template<typename ValueType = default_precision, typename IndexType = int32>
struct matrix_data#

This structure is used as an intermediate data type to store a sparse matrix.

The matrix is stored as a sequence of nonzero elements, where each element is a triple of the form (row_index, column_index, value).

Note

All Ginkgo functions returning such a structure will return the nonzeros sorted in row-major order.

Note

All Ginkgo functions that take this structure as input expect that the nonzeros are sorted in row-major order and that the index pair (row_index, column_index) of each nonzero is unique.

Note

This structure is not optimized for usual access patterns and it can only exist on the CPU. Thus, it should only be used for utility functions which do not have to be optimized for performance.

Template Parameters:

  • ValueType – type of matrix values stored in the structure

  • IndexType – type of matrix indexes stored in the structure

Public Functions

inline matrix_data(
dim<2> size_ = dim<2>{},
ValueType value = zero<ValueType>(),
)#

Initializes a matrix filled with the specified value.

Parameters:

  • size_ – dimensions of the matrix

  • value – value used to fill the elements of the matrix

template<typename RandomDistribution, typename RandomEngine>
inline matrix_data(
dim<2> size_,
RandomDistribution &&dist,
RandomEngine &&engine,
)#

Initializes a matrix with random values from the specified distribution.

Template Parameters:

  • RandomDistribution – random distribution type

  • RandomEngine – random engine type

Parameters:

  • size_ – dimensions of the matrix

  • dist – random distribution of the elements of the matrix

  • engine – random engine used to generate random values

inline matrix_data(
std::initializer_list<std::initializer_list<ValueType>> values,
)#

List-initializes the structure from a matrix of values.

Parameters:

values – a 2D braced-init-list of matrix values.

inline matrix_data(
dim<2> size_,
std::initializer_list<detail::input_triple<ValueType, IndexType>> nonzeros_,
)#

Initializes the structure from a list of nonzeros.

Parameters:

  • size_ – dimensions of the matrix

  • nonzeros_ – list of nonzero elements

inline matrix_data(dim<2> size_, const matrix_data &block)#

Initializes a matrix out of a matrix block via duplication.

Parameters:

  • size – size of the block-matrix (in blocks)

  • diag_block – matrix block used to fill the complete matrix

template<typename Accessor>
inline matrix_data(
const range<Accessor> &data,
)#

Initializes a matrix from a range.

Template Parameters:

Accessor – accessor type of the input range

Parameters:

data – range used to initialize the matrix

inline void sort_row_major()#

Sorts the nonzero vector so the values follow row-major order.

inline void ensure_row_major_order()#

Sorts the nonzero vector so the values follow row-major order.

inline void remove_zeros()#

Remove entries with value zero from the matrix data.

inline void sum_duplicates()#

Sum up all values that refer to the same matrix entry. The result is sorted in row-major order.

Public Members

dim<2> size#

Size of the matrix.

std::vector<nonzero_type> nonzeros#

A vector of tuples storing the non-zeros of the matrix.

The first two elements of the tuple are the row index and the column index of a matrix element, and its third element is the value at that position.

Public Static Functions

static inline matrix_data diag(dim<2> size_, ValueType value)#

Initializes a diagonal matrix.

Parameters:

  • size_ – dimensions of the matrix

  • value – value used to fill the elements of the matrix

Returns:

the diagonal matrix

static inline matrix_data diag(
dim<2> size_,
std::initializer_list<ValueType> nonzeros_,
)#

Initializes a diagonal matrix using a list of diagonal elements.

Parameters:

  • size_ – dimensions of the matrix

  • nonzeros_ – list of diagonal elements

Returns:

the diagonal matrix

static inline matrix_data diag(
dim<2> size_,
const matrix_data &block,
)#

Initializes a block-diagonal matrix.

Parameters:

  • size_ – the size of the matrix

  • diag_block – matrix used to fill diagonal blocks

Returns:

the block-diagonal matrix

template<typename ForwardIterator>
static inline matrix_data diag(
ForwardIterator begin,
ForwardIterator end,
)#

Initializes a block-diagonal matrix from a list of diagonal blocks.

Template Parameters:

ForwardIterator – type of list iterator

Parameters:

  • begin – the first iterator of the list

  • end – the last iterator of the list

Returns:

the block-diagonal matrix with diagonal blocks set to the blocks between begin (inclusive) and end (exclusive)

static inline matrix_data diag(
std::initializer_list<matrix_data> blocks,
)#

Initializes a block-diagonal matrix from a list of diagonal blocks.

Parameters:

blocks – a list of blocks to initialize from

Returns:

the block-diagonal matrix with diagonal blocks set to the blocks passed in blocks

template<typename RandomDistribution, typename RandomEngine>
static inline matrix_data cond(
size_type size,
remove_complex<ValueType> condition_number,
RandomDistribution &&dist,
RandomEngine &&engine,
size_type num_reflectors,
)#

Initializes a random dense matrix with a specific condition number.

The matrix is generated by applying a series of random Hausholder reflectors to a diagonal matrix with diagonal entries uniformly distributed between sqrt(condition_number) and 1/sqrt(condition_number).

Template Parameters:

  • RandomDistribution – the type of the random distribution

  • RandomEngine – the type of the random engine

Parameters:

  • size – number of rows and columns of the matrix

  • condition_number – condition number of the matrix

  • dist – random distribution used to generate reflectors

  • engine – random engine used to generate reflectors

  • num_reflectors – number of reflectors to apply from each side

Returns:

the dense matrix with the specified condition number

template<typename RandomDistribution, typename RandomEngine>
static inline matrix_data cond(
size_type size,
remove_complex<ValueType> condition_number,
RandomDistribution &&dist,
RandomEngine &&engine,
)#

Initializes a random dense matrix with a specific condition number.

The matrix is generated by applying a series of random Hausholder reflectors to a diagonal matrix with diagonal entries uniformly distributed between sqrt(condition_number) and 1/sqrt(condition_number).

This version of the function applies size - 1 reflectors to each side of the diagonal matrix.

Template Parameters:

  • RandomDistribution – the type of the random distribution

  • RandomEngine – the type of the random engine

Parameters:

  • size – number of rows and columns of the matrix

  • condition_number – condition number of the matrix

  • dist – random distribution used to generate reflectors

  • engine – random engine used to generate reflectors

Returns:

the dense matrix with the specified condition number

Entries#

template<typename ValueType, typename IndexType>
struct matrix_data_entry#

Type used to store nonzeros.