Autodocs

template<class ScalarType>
class SparseMatrix

class provides a primitive tool handle sparse matrices.

Template parameters

• class ScalarType: The primitive data type that is used to represent the matrix. The class allows real and complex types, e.g., double or std::complex<double>.

  It is possible to evaluate the type using the danceq::is_complex<ScalarType> function:

  ScalarType c;
  if constexpr (function_space::is_complex<ScalarType>()){
      c.real(1.);
      c.imag(0.);
  } else {
      c = 1.;
  }
  

Things to know

• The class does not provide any complex functionality and is mainly used by the Operator class to manage local tensor products.

• It is only built for square matrices.

• It only contains three data members, dim, range, and data, that provide full access to the matrix:

  for(uint64_t i = 0UL; i < dim; i++){
      for(uint64_t j = range[i]; j < range[i+1]; j++){
          std::cout << "Element at (" << i << "," << data[j].first << "): " << data[j].second;
      }
  }
  

• For a given row, the column elements in data are in ascending order.

• The debugging level can be adjusted from 0 (no debugging) to 10 (maximal debugging):

  #define dbug_level 10; // 10 maximal debugging, 0 is no debugging
  

Public Types

using scalartype = ScalarType

ScalarType.

The ScalarType can be accessed via:

Operator<T,ScalarType>::scalartype

Public Functions

SparseMatrix(void)

Default constructor with dimension zero.

SparseMatrix(const uint64_t dim_)

Constructor for the null matrix with the given dimension.

SparseMatrix(const std::vector<std::vector<ScalarType>> &matrix)

Constructor with dense matrix using std::vector.

Parameters:

matrix – Dense matrix

SparseMatrix(const std::vector<uint64_t> &range_, const std::vector<std::pair<uint64_t, ScalarType>> &data_)

Constructor with given range and data.

The column indices of data_ have to be in ascending order for each row and match range_.

Parameters:

• range_ – range

• data_ – data

SparseMatrix<ScalarType> operator*(const SparseMatrix<ScalarType> &other) const

Overloaded multiplication.

Parameters:

other – Input matrix.

Returns:

this*other

SparseMatrix<ScalarType> operator+(const SparseMatrix<ScalarType> &other) const

Overloaded addition.

Parameters:

other – Input matrix.

Returns:

this+other

SparseMatrix<ScalarType> operator-(const SparseMatrix<ScalarType> &other) const

Overloaded subtraction.

Parameters:

other – Input matrix.

Returns:

this-other

SparseMatrix<ScalarType> &operator=(const SparseMatrix<ScalarType> &other)

Overloaded equality.

Parameters:

other – Input matrix.

Returns:

other

SparseMatrix<ScalarType> tensor_product(const SparseMatrix<ScalarType> &other) const

Tensor product between two matrices.

Returns the tensor product of this and other. The return matrix has the dimension this-> get_dim() times other. get_dim().

\[\mathrm{this} \otimes \mathrm{other}\]

Parameters:

other – Input matrix.

Returns:

this X other

SparseMatrix<ScalarType> T(void) const

Returns the transpose of the matrix.

Returns:

Transposed matrix of other

int32_t scale(ScalarType factor)

Scales matrix.

Parameters:

factor – Factor for scaling

Returns:

error_code

std::vector<uint64_t> get_range(void) const

Returns range.

Returns a copy of range.

Returns:

range.

std::vector<uint64_t> *get_range_ptr(void)

Returns pointer to range.

Returns a pointer to range.

Returns:

Pointer to range.

std::vector<std::pair<uint64_t, ScalarType>> *get_data_ptr(void)

Returns pointer to data.

Returns a pointer to data.

Returns:

Pointer to data.

std::vector<std::pair<uint64_t, ScalarType>> get_data(void) const

Returns pointer to data.

Returns a copy of data.

Returns:

data.

uint64_t get_dim(void) const

Returns dim.

Returns dim.

Returns:

dim.

std::pair<typename std::vector<std::pair<uint64_t, ScalarType>>::const_iterator, typename std::vector<std::pair<uint64_t, ScalarType>>::const_iterator> get_data_iter_of_row(const uint64_t row) const

Returns const iterators marking the range of the given row.

The const_iterator mark the range of given row:

uint64_t row = 42;
const auto iter_pair = matrix.get_data_iter_of_row(row);

for(auto iter = iter_pair.first; iter != iter_pair.second; iter++){

    std::cout << "Row " << row << " has an entry in column " << iter->first << " with value " << iter->second << std::endl;

}

Parameters:

row – Row of interest

Returns:

Pair of const_iterator

std::vector<uint64_t>::const_iterator get_range_iter(const uint64_t row = 0UL) const

Returns const_iterator for range.

The const_iterator points to the start in range of the given row.

uint64_t row = 42;
const auto iter = matrix.get_range_iter(row);
uint64_t number_of_columns = *iter - *(iter+1);

std::cout << "Row " << row << " has " << number_of_columns << " columns" << std::endl;

Parameters:

row – Row of interest

Returns:

const_iterator of range

std::vector<std::pair<uint64_t, ScalarType>>::const_iterator get_data_iter(const uint64_t offset = 0UL) const

Returns const_iterator for data.

The const_iterator points to the data with a given offset.

uint64_t row = 42;
const auto iter_range = matrix.get_range_iter(row);
const auto iter_data = matrix.get_data_iter(*iter_range);

std::cout << "First element of row " << row << " is at column " << iter_data->first << " with a value " << iter_data->second << std::endl;

Parameters:

offset – Offset of interest

Returns:

const_iterator of data

int32_t info(const bool show_data = false) const

Prints info.

Prints data like memory usage.

Parameters:

show_data – Shows data if true

Returns:

error_code

int32_t print(const bool print_endl = true, const bool print_info = true) const

Prints the dense matrix.

If print_endl is true it adds a line break after each row. If print_info is false it only prints the matrix without further text.

Parameters:

• print_endl – Boolean to control output

• print_info – Boolean to control output

Returns:

error_code

uint64_t max_number_of_cols_per_row(void) const

Returns the maximal number columns in a single row.

Returns:

maximum

int32_t set_diag_to_zero(void)

Sets the diagonal to zero.

.. math::

M_{i,i} = 0 \, ,\,\forall i

Returns:

error_code

int32_t set_to_identity(const uint64_t new_dim = static_cast<uint64_t>(-1))

Sets the matrix to the identity.

.. math::

M_{i,i} = 1 \, ,\,\forall i

M_{i,j} = 0 \, ,\,\text{ for } i \neq j

The default value of -1 corresponds to the current dimension.

Parameters:

new_dim – New dimension (Default: -1)

Returns:

error_code

double get_norm(void) const

Returns the Frobenius norm of the matrix.

\[\mathrm{norm} = \sqrt{\sum_{i,j} \vert a_{i,j}\vert^2}\]

Returns:

norm

bool is_zero(void) const

Checks if all matrix elements are zero.

Returns:

true if all elements are zero otherwise false

bool is_hermitian(void) const

Checks if the matrix is hermitian (or symmetric if ScalarType is real).

\[a_{i,j} = \text{conj}\left({a_{j,i}}\right) \, ,\,\forall i,j\]

Returns:

true if matrix is hermitian otherwise false

bool is_diagonal(void) const

Checks if the matrix is diagonal.

\[M_{i,j} = 0 \, ,\,\forall i\neq j\]

Returns:

true if matrix is diagonal otherwise false

uint64_t get_nnz(void) const

Returns number of non-zero elements.

This is simply the size of data.

Returns:

number of non-zero elements

std::vector<std::vector<ScalarType>> get_dense(void) const

Returns the dense matrix using std::vector.

Returns:

Dense matrix

ScalarType get_element(const uint64_t row, const uint64_t col) const

Returns element at a certain position.

If the element does not exists zero is returned.

Parameters:

• row – Row

• col – Column

Returns:

Element

bool is_element(const uint64_t row, const uint64_t col) const

Checks if element at a certain position.

Parameters:

• row – Row

• col – Column

Returns:

true if element exists false if it does not exists

std::vector<ScalarType> get_diag(void) const

Returns full diagonal of matrix.

Returns:

Diagonal of size dim

uint64_t get_index(uint64_t row, uint64_t col) const

Returns position of an element in data.

Returns the index of an element in data. It is set -1 if the element is not present.

Parameters:

• row – Row

• col – Column

Returns:

index

Private Members

std::vector<uint64_t> range

Specifies the range to access data.

The range vector is of size dim+1 and defines the range of elements in data for each row:

uint64_t row = 42;
for(uint64_t i = range[row]; i < range[row+1UL]; i++){
    std::cout << "Row " << row << " has an entry in column " << data[i].first << " with value " << data[i].second << std::endl;
}

std::vector<std::pair<uint64_t, ScalarType>> data

Stores the columns and respective values of the matrix.

The values assigned to a certain row can be accessed using range:

uint64_t row = 42;
for(uint64_t i = range[row]; i < range[row+1UL]; i++){
    std::cout << "Row " << row << " has an entry in column " << data[i].first << " with value " << data[i].second << std::endl;
}

uint64_t dim

Dimension of the matrix.