Template Class Matrix

• Defined in File matrix.h

Nested Relationships

Nested Types

• Struct Matrix::sliceIterator

Class Documentation

template<typename Real>
class Matrix

The Matrix class is designed to serve as a convenient wrapper to simplify 2D matrix operations. It assumes dense matrices with contiguious data and the fast running index being the right (column) index. The underlying memory may have already been allocated elsewhere by C, Fortran or Python, and is directly manipulated in place, saving an expensive copy operation. To provide read-only access to such memory address, use a const template type.

Public Types

enum class SortOrder

Values:

enumerator Ascending

enumerator Descending

Public Functions

inline const Real &operator()(int row, int col) const

inline const Real &operator()(const std::pair<int, int> &indices) const

inline Real &operator()(int row, int col)

inline Real &operator()(const std::pair<int, int> &indices)

inline const Real *operator[](int row) const

inline Real *operator[](int row)

inline Real *begin() const

inline Real *end() const

inline const Real *cbegin() const

inline const Real *cend() const

inline sliceIterator row(size_t r) const

row returns a read-only iterator over a given row.

Parameters:

r – the row to return.

Returns:

the slice in memory corresponding to the rth row.

inline sliceIterator col(size_t c) const

col returns a read-only iterator over a given column.

Parameters:

c – the column to return.

Returns:

the slice in memory corresponding to the cth column.

inline size_t nRows() const

Returns:

the number of rows in this matrix.

inline size_t nCols() const

Returns:

the number of columns in this matrix.

inline Matrix()

Matrix Constructs an empty matrix.

inline Matrix(size_t nRows, size_t nCols)

Matrix Constructs a new matrix, allocating memory.

Parameters:

• nRows – the number of rows in the matrix.

• nCols – the number of columns in the matrix.

inline Matrix(const std::string &filename)

Matrix Constructs a new matrix, allocating memory.

Parameters:

filename – the ASCII file from which to read this matrix

inline Matrix(std::initializer_list<std::initializer_list<Real>> data)

Matrix Constructs a new matrix, allocating memory and initializing values using the braced initializer.

Parameters:

data – a braced initializer list of braced initializer lists containing the values to be stored in the matrix.

inline Matrix(std::initializer_list<Real> data)

Matrix Constructs a new column vector, allocating memory and initializing values using the braced initializer.

Parameters:

data – a braced initializer list of braced initializer lists containing the values to be stored in the matrix.

inline Matrix(Real *ptr, size_t nRows, size_t nCols)

Matrix Constructs a new matrix using already allocated memory.

Parameters:

• ptr – the already-allocated memory underlying this matrix.

• nRows – the number of rows in the matrix.

• nCols – the number of columns in the matrix.

template<typename NewReal>
inline Matrix<NewReal> cast() const

cast make a copy of this matrix, with its elements cast as a different type.

Template Parameters:

NewReal – the type to cast each element to.

Returns:

the copy of the matrix with the new type.

inline void setConstant(Real value)

setConstant sets all elements of this matrix to a specified value.

Parameters:

value – the value to set each element to.

inline void setZero()

setZero sets each element of this matrix to zero.

inline bool isNearZero(Real threshold = 1e-10f) const

isNearZero checks that each element in this matrix has an absolute value below some threshold.

Parameters:

threshold – the value below which an element is considered zero.

Returns:

whether all values are near zero or not.

inline Matrix inverse() const

inverse inverts this matrix, leaving the original matrix untouched.

Returns:

the inverse of this matrix.

inline void assertSymmetric(const Real &threshold = 1e-10f) const

assertSymmetric checks that this matrix is symmetric within some threshold.

Parameters:

threshold – the value below which an pair’s difference is considered zero.

inline void applyOperationToEachElement(const std::function<void(Real&)> &fxn)

applyOperationToEachElement modifies every element in the matrix by applying an operation.

Parameters:

function – a unary operator describing the operation to perform.

inline Matrix applyOperation(const std::function<void(Real&)> &function) const

applyOperation applies an operation to this matrix using the spectral decomposition, leaving the original untouched. Only for symmetric matrices, as coded.

Parameters:

function – a undary operator describing the operation to perform.

Returns:

the matrix transformed by the operator.

inline void assertSameSize(const Matrix &other) const

assertSameSize make sure that this Matrix has the same dimensions as another Matrix.

Parameters:

other – the matrix to compare to.

inline void assertSquare() const

assertSquare make sure that this Matrix is square.

inline Matrix multiply(const Matrix &other) const

multiply this matrix with another, returning a new matrix containing the product.

Parameters:

other – the right hand side of the matrix product.

Returns:

the product of this matrix with the matrix other.

inline Matrix operator*(const Matrix &other) const

operator * a convenient wrapper for the multiply function.

Parameters:

other – the right hand side of the matrix product.

Returns:

the product of this matrix with the matrix other.

inline Matrix operator*(Real scaleFac) const

operator * scale a copy of this matrix by a constant, leaving the orignal untouched.

Parameters:

scaleFac – the scale factor to apply.

Returns:

the scaled version of this matrix.

inline Matrix incrementWith(const Matrix &other)

increment this matrix with another, returning a new matrix containing the sum.

Parameters:

other – the right hand side of the matrix sum.

Returns:

the sum of this matrix and the matrix other.

inline Matrix operator+=(const Matrix &other)

a wrapper around the incrementWith() function.

Parameters:

other – the right hand side of the matrix sum.

Returns:

the sum of this matrix and the matrix other.

inline Matrix incrementWith(const Real &shift)

increment every element of this matrix by a constant another, returning a new matrix containing the sum.

Parameters:

other – the right hand side of the matrix sum.

Returns:

the sum of this matrix and the matrix other.

inline Matrix operator+=(const Real &shift)

a wrapper around the incrementWith() function.

Parameters:

shift – the scalar to increment each value by

Returns:

the sum of this matrix and the matrix other.

template<typename T = Real, typename std::enable_if<std::is_floating_point<T>::value, int>::type = 0>
inline bool almostEquals(const Matrix &other, Real tolerance = 1e-6) const

almostEquals checks that two matrices have all elements the same, within some specificied tolerance.

Parameters:

• other – the matrix against which we’re comparing.

• tol – the amount that each element is allowed to deviate by.

Returns:

whether the two matrices are almost equal.

template<typename T = Real, typename std::enable_if<!std::is_floating_point<T>::value, int>::type = 0>
inline bool almostEquals(const Matrix &other, Real tolerance = 1e-6) const

inline Real dot(const Matrix &other) const

dot computes the inner product of this matrix with another.

Parameters:

other – the other matrix in the inner product, which must have the same dimensions.

Returns:

the inner product.

inline void writeToFile(const std::string &filename, int width = 20, int precision = 14, bool printDimensions = false) const

writeToFile formats the matrix and writes to an ASCII file.

Parameters:

• fileName – the name of the file to save to.

• width – the width of each matrix element’s formatted representation.

• precision – the precision of each matrix element’s formatted representation.

• printDimensions – whether to print the dimensions at the top of the file.

inline std::ostream &write(std::ostream &os) const

write formatted matrix to a stream object.

Parameters:

os – stream object to write to.

Returns:

modified stream object.

inline void transposeInPlace()

transposeInPlace transposes this matrix in place.

inline Matrix clone() const

clone make a new copy of this matrix by deep copying the data.

Returns:

the copy of this matrix.

inline Matrix transpose() const

transpose this matrix, leaving the original untouched.

Returns:

a transposed deep copy of this matrix.

inline std::pair<Matrix<Real>, Matrix<Real>> diagonalize(SortOrder order = SortOrder::Ascending) const

diagonalize diagonalize this matrix, leaving the original untouched. Note that this assumes that this matrix is real and symmetric.

Parameters:

order – how to order the (eigenvalue,eigenvector) pairs, where the sort key is the eigenvalue.

Returns:

a pair of corresponding <eigenvalue , eigenvectors> sorted according to the order variable. The eigenvectors are stored by column.

Protected Attributes

size_t nRows_

The number of rows in the matrix.

size_t nCols_

The number of columns in the matrix.

helpme::vector<Real> allocatedData_

A vector to conveniently allocate data, if we really need to.

Real *data_

Pointer to the raw data, whose allocation may not be controlled by us.

struct sliceIterator

The sliceIterator struct provides a read-only view of a sub-block of a matrix, with arbitrary size.

Public Functions

inline sliceIterator(Real *start, Real *end, size_t stride)

inline sliceIterator begin() const

inline sliceIterator end() const

inline sliceIterator cbegin() const

inline sliceIterator cend() const

inline bool operator!=(const sliceIterator &other)

inline sliceIterator operator*=(Real val)

inline sliceIterator operator/=(Real val)

inline sliceIterator operator-=(Real val)

inline sliceIterator operator+=(Real val)

inline sliceIterator operator++()

inline const Real &operator[](size_t index) const

inline size_t size() const

inline void assertSameSize(const sliceIterator &other) const

inline void assertContiguous(const sliceIterator &iter) const

inline Matrix<Real> operator-(const sliceIterator &other) const

inline sliceIterator operator-=(const sliceIterator &other) const

inline sliceIterator operator+=(const sliceIterator &other) const

inline Real &operator*()

Public Members

Real *begin_

Real *end_

Real *ptr_

size_t stride_