Matrix

template<Number ElemType, DataLocation Location, template<typename, typename> typename Storage>
class Matrix : public HighFM::MatrixBase<Matrix<ElemType, Location, Storage>>, public Storage<ElemType, Location>

A dense matrix following a column major (Fortran-style) layout. Depending on the Storage parameter, this object will be referred to either as MatrixMap (when Storage is set to DataMap) or as just Matrix (when Storage is set to Array).

Creating a new object:

using namespace HighFM;
Matrix<int> mat1;                                    // Creates a empty integer matrix
Matrix<int> mat2(5, 5);                              // Creates a 5x5 integer matrix filled with zeroes
Matrix<float> mat3(3, 3, 2.2);                       // Creates a 3x3 floating-point matrix filled with 2.2
Matrix<float> mat4 = mat3;                           // Creates a copy of the mat3
MatrixMap<float> mat_map1(mat4.mat_data());          // Creates a data map to mat4
MatrixMap<float> mat_map2({.buffer = mat4.data(),    // Creates a data map to mat4 (is equivalent to the above)
                           .nrows = mat4.rows(),
                           .ncols = mat4.cols(),
                           .lead_dim = mat4.lead_dim()});

Accessing the elements:

Matrix<double> mat(10, 10);
mat(1, 4) = 10;                         // Access element at position (1, 4)
// mat[1] = 2                           // Do NOT do this as may have a gap between columns
mat(all, 1) = 3;                        // Creates a slice from the column 1 of the matrix
mat({1, 6}, 1) = 4;                     // Creates a slice from the column 1 of the matrix containing the rows 1 --> 6
mat(all, {1, 3}) = 5;                   // Creates a slice from the column 1 --> 3 of the matrix
mat({1, 6}, {1, 3}) = 6;                // Creates a sub matrix from the columns 1 --> 3 and rows 1 --> 6 of the matrix

Note

If lead_dim() != rows(), there is a gap between the last element in one column and the first element in the next column.

Template Parameters:
  • ElemType – Data types of the entries. Must be either a double or float.

  • Location – Location of the data

  • Storage – Container used for storing the data.

Constructor

Matrix()

Creates an empty Matrix.

template<ResizableContainer S = storage>
Matrix(index_t rows, index_t cols, ElemType val = ElemType(0))

Creates a Matrix and fills with val.

Warning

This constructor is only available when using Array as Storage.

Parameters:
  • cols[in] number of columns.

  • rows[in] number of rows.

  • val[in] value to initialize the Matrix with.

Throws:

LengthError – if `nrows/ncols < 1`

Matrix(MatrixData<ElemType> data)

Maps the Matrix to an external container when using DataMap as Storage. Otherwise, creates a new Matrix and then copies the data from the external container.

Warning

The container must store the data in the column major format.

Parameters:

data[in] struct containing the information about the container

template<DataLocation OtherLoc, template<typename, typename> typename OtherStorage>
Matrix(const Matrix<ElemType, OtherLoc, OtherStorage> &other)

Creates a Matrix from an other Matrix. When using DataMap as Storage, this will just duplicate the map without copying the data.

Parameters:

other[in] another Matrix to use as the data source.

Matrix(const Matrix &other)

Creates a Matrix from an other Matrix. When using DataMap as Storage, this will just duplicate the map without copying the data.

Parameters:

other[in] another Matrix to use as the data source.

template<ResizableContainer S = storage>
Matrix(Matrix &&other) noexcept

Creates a new Matrix and then moves the content from an other Matrix.

Warning

This constructor is only available when using Array as Storage.

Parameters:

other[in] another Matrix to use as the data source.

Destructor

virtual ~Matrix() = default

Default destructor.

Assignment

template<Number T>
inline Matrix &operator=(T scalar)

Sets all elements in the container to scalar.

Parameters:

scalar[in] scalar to use as the data source

Returns:

*this.

template<DataLocation OtherLoc, template<typename, typename> typename OtherStorage>
Matrix &operator=(const Matrix<ElemType, OtherLoc, OtherStorage> &other)

Copies the content from other to this container.

Parameters:

other[in] another Matrix to use as the data source

Returns:

*this.

Matrix &operator=(const Matrix &other)

Copies the content from other to this container.

Parameters:

other[in] another Matrix to use as the data source.

Returns:

*this.

template<template<typename, typename> typename OtherStorage>
Matrix &operator=(const CSRMatrix<ElemType, Location, OtherStorage> &csr)

Copies the content from csr to this container.

Parameters:

csr[in] A CSRMatrix to use as the data source.

Returns:

*this.

template<MatrixTriangularType UpLo, DataLocation OtherLoc>
Matrix &operator=(const TriangularMap<ElemType, UpLo, OtherLoc> &triangular)

Copies the content from an upper or lower triangular matrix to this container.

Parameters:

triangular[in] A TriangularMap to use as the data source.

Returns:

*this.

template<ResizableContainer S = storage>
Matrix &operator=(Matrix &&other) noexcept

Moves the content from an other Matrix to this container.

Warning

This constructor is only available when using Array as Storage.

Parameters:

other[in] another Matrix to use as the data source.

Returns:

*this.

Element Access

ElemType &operator()(index_t row, index_t col)
Parameters:
  • row[in] index of the row.

  • col[in] index of the column.

Returns:

The element at (row, col).

ElemType operator()(index_t row, index_t col) const
Parameters:
  • row[in] index of the row.

  • col[in] index of the row.

Returns:

The element at (row, col).

VectorMap<ElemType, Location> operator()(All, index_t col) const
Parameters:

col[in] index of the column.

Returns:

A slice from the column ‘col’ of the Matrix.

VectorMap<ElemType, Location> operator()(Range row_range, index_t col) const
Parameters:
  • row_range[in] the range of rows

  • col[in] index of the column.

Returns:

A slice from the column ‘col’ of the Matrix containing the rows specified by the range.

MatrixMap<ElemType, Location> operator()(Range row_range, All) const
Parameters:

row_range[in] the range of rows

Returns:

A subset of rows from the Matrix as specified by the row_range.

MatrixMap<ElemType, Location> operator()(All, Range col_range) const
Parameters:

col_range[in] the range of columns

Returns:

A subset of columns from the Matrix as specified by the col_range.

MatrixMap<ElemType, Location> operator()(Range row_range, Range col_range) const
Parameters:
  • row_range[in] the range of rows

  • col_range[in] the range of columns

Returns:

A sub matrix from the Matrix as specified by the row_range and col_range.

Capacity

index_t rows() const noexcept
Returns:

The number of rows in the Matrix.

index_t cols() const noexcept
Returns:

The number of columns in the Matrix.

index_t size() const noexcept
Returns:

The number of elements in the Matrix.

index_t lead_dim() const noexcept
Returns:

The leading dimension of the Matrix.

Modifiers

template<ResizableContainer S = storage>
void resize(index_t nrows, index_t ncols)

Resizes the Matrix. This routine will clear the previous content from the Matrix.

Note

This routine is only available when using Array as Storage.

Parameters:
  • nrows[in] new number of rows.

  • ncols[in] new number of columns.

Throws:

LengthError – if `nrows/ncols < 1`.

void swap(Matrix &other) noexcept

Swaps the Matrix content with the other Matrix, including any memory allocation (if applicable).

Parameters:

other[in] another Matrix to exchange content with.

template<RemappableContainer S = storage>
void map_to(MatrixData<ElemType> data)

Replaces the managed container.

Note

This routine is only available when using DataMap as Storage.

Parameters:

data[in] struct containing the information about the container

template<template<typename, typename> typename OtherStorage, RemappableContainer S = storage>
void map_to(const Matrix<ElemType, Location, OtherStorage> &other)

Replaces the managed container.

Note

This routine is only available when using DataMap as Storage.

Parameters:

other[in] a Matrix to use as the data source

internal::ConjugateTransposeOp<Matrix, internal::kTranspose> T() const

Warning

If you want to replace the matrix by its transpose, do not use:

mat = mat.T(); 
Instead, do
mat.transpose_inplace() 
to correctly transpose the matrix.

Returns:

An abstract expression representing the transpose of the Matrix.

internal::ConjugateTransposeOp<Matrix, internal::kAdjoint> H() const

Warning

If you want to replace the matrix by its transpose, do not use:

mat = mat.H(); 
Instead, do
mat.adjoint_inplace() 
to correctly transpose the matrix.

Returns:

An abstract expression representing the adjoint (conjugate transpose) of the Matrix. This is equivalent to T() if the matrix is real.

internal::ConjugateOp<Matrix> conj() const
Returns:

An abstract expression representing the conjugate of the Matrix. If the matrix is real, this is a noop.

void transpose_inplace()

Calculates the transpose of the Matrix in-place. Use this routine to avoid aliasing.

void adjoint_inplace()

Calculates the transpose of the Matrix in-place. Use this routine to avoid aliasing.

TriangularMap<ElemType, kLower, Location> lower_triangular()
Returns:

An object representing the lower triangular part of the matrix.

TriangularMap<ElemType, kUpper, Location> upper_triangular()
Returns:

An object representing the upper triangular part of the matrix.

MatrixData<ElemType> mat_data() const
Returns:

A simple struct with a pointer to the container and its dimensions.

template<typename T>
struct MatrixData

A simple struct storing the data of a dense matrix in the column-major format.

Public Members

T *buffer

A contiguous array with elements of the matrix.

index_t nrows

Number of rows in the matrix.

index_t ncols

Number of columns in the matrix.

index_t lead_dim

Leading dimension of the matrix (i.e., the distance between the first element in each column)