The Matrix class is used to represent \( M \times N \) matrices. It provides common matrix operations and allows accessing matrix elements in a more natural way, using row and column indices, regardless of the underlying flat array storage layout. More...

#include </home/docs/checkouts/readthedocs.org/user_builds/axom/checkouts/v0.5.0/src/axom/core/numerics/Matrix.hpp>

Public Member Functions
	Matrix (int rows, int cols, T val=static_cast< T >(0))
	Constructor, creates a Matrix with the given rows and columns. More...

AXOM_HOST_DEVICE	Matrix (int rows, int cols, T *data, bool useExternal=false)
	Array constructor, creates a Matrix with the given rows and columns and initializes its entries with the data from the supplied array. More...

	Matrix (const Matrix< T > &m)
	Copy constructor. More...

AXOM_HOST_DEVICE	~Matrix ()
	Destructor. More...

bool	isSquare () const
	Check to see if the matrix is square. More...

bool	empty () const
	Checks if the matrix is empty. More...

bool	usesExternalBuffer () const
	Checks to see if the matrix has an external buffer. More...

int	getNumRows () const
	Returns the number of rows in the matrix.. More...

AXOM_HOST_DEVICE int	getNumColumns () const
	Returns the number of columns in the matrix. More...

int	getDiagonalSize () const
	Returns the size of the diagonal. More...

void	getDiagonal (T *diagonal) const
	Returns the diagonal entries of this Matrix instance. More...

void	fillDiagonal (const T &val)
	Assigns val to all entries in the diagonal. More...

void	fillRow (IndexType i, const T &val)
	Assigns val to all elements in the given matrix row. More...

void	fillColumn (IndexType j, const T &val)
	Assigns val to all elements in the given matrix column. More...

void	fill (const T &val)
	Assigns val to all elements of the matrix. More...

void	swapRows (IndexType i, IndexType j)
	Swaps the rows of this matrix instance. More...

void	swapColumns (IndexType i, IndexType j)
	Swaps the columns of this matrix instance. More...

Random Access Operators
AXOM_HOST_DEVICE const T &	operator() (IndexType i, IndexType j) const
	Given an \( M \times N \) matrix, \( \mathcal{A} \), return a const reference to matrix element \( \alpha_{ij} \). More...

AXOM_HOST_DEVICE T &	operator() (IndexType i, IndexType j)
	Given an \( M \times N \) matrix, \( \mathcal{A} \), return a reference to matrix element \( \alpha_{ij} \). More...

AXOM_HOST_DEVICE const T *	getColumn (IndexType j) const
	Returns a const pointer to the \( jth \) column of an \( M \times N \) matrix, \( \mathcal{A} \). More...

AXOM_HOST_DEVICE T *	getColumn (IndexType j)
	Returns pointer to the \( jth \) column of an \( M \times N \) matrix, \( \mathcal{A} \). More...

const T *	getDiagonal (IndexType &p, IndexType &N) const
	Returns a const pointer for strided access along the main diagonal. More...

T *	getDiagonal (IndexType &p, IndexType &N)
	Returns a pointer for strided access along the main diagonal. More...

const T *	getRow (IndexType i, IndexType &p, IndexType &N) const
	Returns a const pointer to the \( ith \) row of an \( M \times N \) matrix, \( \mathcal{A} \). More...

T *	getRow (IndexType i, IndexType &p, IndexType &N)
	Returns a pointer to the \( ith \) row of an \( M \times N \) matrix, \( \mathcal{A} \). More...

const T *	data () const
	Returns a const pointer to the raw data. More...

T *	data ()
	Returns pointer to the raw data. More...

Overloaded Operators
Matrix< T > &	operator= (const Matrix< T > &rhs)
	Overloaded assignment operator. More...

Static Public Member Functions
Static Methods
static Matrix< T >	identity (int n)
	Returns an identity matrix \( \mathcal{I}_n \). More...

static Matrix< T >	zeros (int nrows, int ncols)
	Returns a zero matrix, \( \mathcal{A} \). More...

static Matrix< T >	ones (int nrows, int ncols)
	Returns a unity matrix, \( \mathcal{A} \). More...

Detailed Description

template<typename T>
class axom::numerics::Matrix< T >

The Matrix class is used to represent \( M \times N \) matrices. It provides common matrix operations and allows accessing matrix elements in a more natural way, using row and column indices, regardless of the underlying flat array storage layout.

Note: The underlying storage layout is column-major.

Basic usage example:

int main( int argc, char**argv )
{
  // Allocate a 5,5 matrix
  Matrix< double > A(5,5);
  const int nrows = A.getNumRows(); // nrows=5
  const int ncols = A.getNumColumnds(); // ncols=5
  // loop over the elements of the matrix, row by row
  for ( IndexType i=0; i < nrows; ++i ) {
     for ( IndexType j=0; j < ncols; ++j ) {
       A( i,j ) = getValue( );
     } // END for all columns
  } // END for all rows
  return 0;
}

Template Parameters

T	the underlying matrix data type, e.g., float, double, etc.

Constructor & Destructor Documentation

◆ Matrix() [1/3]

template<typename T >

axom::numerics::Matrix< T >::Matrix	(	int	rows,
		int	cols,
		T	val = `static_cast<T>(0)`
	)

Constructor, creates a Matrix with the given rows and columns.

Parameters

[in]	rows	the number of rows in the matrix.
[in]	cols	the number of columns in the matrix.
[in]	val	optional argument to initialize the entries of the matrix. If not supplied, the default is zero.

Precondition: rows >= 1; cols >= 1

References axom::numerics::Matrix< T >::fill().

◆ Matrix() [2/3]

template<typename T >

AXOM_HOST_DEVICE axom::numerics::Matrix< T >::Matrix	(	int	rows,
		int	cols,
		T *	data,
		bool	useExternal = `false`
	)

Array constructor, creates a Matrix with the given rows and columns and initializes its entries with the data from the supplied array.

Parameters

[in]	rows	the number of rows in the matrix
[in]	cols	the number of columns in the matrix
[in]	data	pointer to user-supplied buffer to initialize the matrix.
[in]	useExternal	optional flag that indicates that this matrix instance should not make a deep copy of the data. Default is false.

Precondition: rows >= 1; cols >= 1; data != nullptr

References axom::numerics::Matrix< T >::data().

◆ Matrix() [3/3]

template<typename T >

axom::numerics::Matrix< T >::Matrix ( const Matrix< T > & m )

Copy constructor.

Parameters

[in] m the matrix instance that is being passed.

◆ ~Matrix()

template<typename T >

AXOM_HOST_DEVICE axom::numerics::Matrix< T >::~Matrix ( )

Destructor.

Member Function Documentation

◆ isSquare()

template<typename T>

bool axom::numerics::Matrix< T >::isSquare ( ) const

inline

Check to see if the matrix is square.

Returns: status true iff this instance is a square matrix, else, false.

Referenced by axom::numerics::determinant(), axom::numerics::eigen_solve(), axom::numerics::jacobi_eigensolve(), axom::numerics::linear_solve(), axom::numerics::lower_triangular(), axom::numerics::lu_decompose(), axom::numerics::lu_solve(), and axom::numerics::upper_triangular().

◆ empty()

template<typename T>

bool axom::numerics::Matrix< T >::empty ( ) const

inline

Checks if the matrix is empty.

Returns: status true iff the matrix is empty, else, false.

Referenced by axom::numerics::determinant().

◆ usesExternalBuffer()

template<typename T>

bool axom::numerics::Matrix< T >::usesExternalBuffer ( ) const

inline

Checks to see if the matrix has an external buffer.

Returns: status true iff the matrix has an external buffer, else, false.

◆ getNumRows()

template<typename T>

int axom::numerics::Matrix< T >::getNumRows ( ) const

inline

Returns the number of rows in the matrix..

Returns: numRows the number of rows in the matrix.

Referenced by axom::numerics::eigen_solve(), axom::numerics::eigen_sort(), axom::numerics::jacobi_eigensolve(), axom::numerics::lower_triangular(), axom::numerics::lu_decompose(), axom::numerics::lu_solve(), axom::numerics::matrix_add(), axom::numerics::matrix_multiply(), axom::numerics::matrix_norm(), axom::numerics::matrix_scalar_multiply(), axom::numerics::matrix_subtract(), axom::numerics::matrix_transpose(), axom::numerics::matrix_vector_multiply(), axom::numerics::operator<<(), and axom::numerics::upper_triangular().

◆ getNumColumns()

template<typename T>

AXOM_HOST_DEVICE int axom::numerics::Matrix< T >::getNumColumns ( ) const

inline

Returns the number of columns in the matrix.

Returns: numCols the number of columns in the matrix.

Referenced by axom::numerics::determinant(), axom::numerics::eigen_solve(), axom::numerics::eigen_sort(), axom::numerics::linear_solve(), axom::numerics::matrix_add(), axom::numerics::matrix_multiply(), axom::numerics::matrix_norm(), axom::numerics::matrix_scalar_multiply(), axom::numerics::matrix_subtract(), axom::numerics::matrix_transpose(), and axom::numerics::matrix_vector_multiply().

◆ getDiagonalSize()

template<typename T>

int axom::numerics::Matrix< T >::getDiagonalSize ( ) const

inline

Returns the size of the diagonal.

Returns: N the size of the diagonal.

Note: For non-square matrices, \( N=min(num\_rows, num\_cols) \)

Referenced by axom::numerics::Matrix< T >::fillDiagonal(), and axom::numerics::Matrix< T >::getDiagonal().

◆ getDiagonal() [1/3]

template<typename T >

void axom::numerics::Matrix< T >::getDiagonal ( T * diagonal ) const

Returns the diagonal entries of this Matrix instance.

Parameters

[in] diagonal user-supplied buffer to store the diagonal entries.

Precondition: diagonal != nullptr; diagonal must have sufficient storage for all the diagonal entries.

Note: For non-square matrices, this method will retrieve all the entries along the main diagonal, \( \alpha_{ii} \in \mathcal{A} \), where, \( i \in [0,N] \), \( N=min(num\_rows, num\_cols) \)

References axom::numerics::Matrix< T >::getDiagonalSize().

Referenced by axom::numerics::Matrix< T >::getDiagonalSize().

◆ fillDiagonal()

template<typename T >

void axom::numerics::Matrix< T >::fillDiagonal ( const T & val )

Assigns val to all entries in the diagonal.

Parameters

[in] val value to assign to all diagonal entries.

Note: For non-square matrices, this method will fill all the entries along the main diagonal, \( \alpha_{ii} \in \mathcal{A} \), where, \( i \in [0,N] \), \( N=min(num\_rows, num\_cols) \)

References axom::numerics::Matrix< T >::getDiagonalSize().

Referenced by axom::numerics::Matrix< T >::getDiagonalSize().

◆ fillRow()

template<typename T >

void axom::numerics::Matrix< T >::fillRow	(	IndexType	i,
		const T &	val
	)

Assigns val to all elements in the given matrix row.

Parameters

[in]	i	the row index.
[in]	val	value to assign to all elements in the given row.

Precondition: i >= 0 && i < m_rows

Referenced by axom::numerics::Matrix< T >::getDiagonalSize().

◆ fillColumn()

template<typename T >

void axom::numerics::Matrix< T >::fillColumn	(	IndexType	j,
		const T &	val
	)

Assigns val to all elements in the given matrix column.

Parameters

[in]	j	the column index.
[in]	val	value to assign to all elements in the given column.

Precondition: j >= 0 && j < m_cols

Referenced by axom::numerics::Matrix< T >::getDiagonalSize().

◆ fill()

template<typename T >

void axom::numerics::Matrix< T >::fill ( const T & val )

Assigns val to all elements of the matrix.

Parameters

[in] val value to assign to all elements of the matrix.

Referenced by axom::numerics::Matrix< T >::getDiagonalSize(), axom::numerics::Matrix< T >::Matrix(), axom::numerics::Matrix< T >::ones(), and axom::numerics::Matrix< T >::zeros().

◆ swapRows()

template<typename T >

void axom::numerics::Matrix< T >::swapRows	(	IndexType	i,
		IndexType	j
	)

Swaps the rows of this matrix instance.

Parameters

[in]	i	index of the first row to swap
[in]	j	index of the second row to swap

Precondition: i >= 0 && i < m_rows; j >= 0 && j < m_rows

References A, and axom::utilities::swap().

Referenced by axom::numerics::Matrix< T >::getDiagonalSize(), and axom::numerics::lu_decompose().

◆ swapColumns()

template<typename T >

void axom::numerics::Matrix< T >::swapColumns	(	IndexType	i,
		IndexType	j
	)

Swaps the columns of this matrix instance.

Parameters

[in]	i	index of the first column to swap
[in]	j	index of the second column to swap

Precondition: i >= 0 && i < m_cols; j >= 0 && j < m_cols

References axom::numerics::Matrix< T >::getColumn().

Referenced by axom::numerics::eigen_sort(), and axom::numerics::Matrix< T >::getDiagonalSize().

◆ operator()() [1/2]

template<typename T >

AXOM_HOST_DEVICE const T & axom::numerics::Matrix< T >::operator()	(	IndexType	i,
		IndexType	j
	)		const

Given an \( M \times N \) matrix, \( \mathcal{A} \), return a const reference to matrix element \( \alpha_{ij} \).

Parameters

[in]	i	the row index of the matrix element,
[in]	j	the column index of the matrix element.

Returns: \( \alpha_{ij} \) const reference to matrix element

Precondition: i >= 0 && i < m_rows; j >= 0 && j < m_cols

Referenced by axom::numerics::Matrix< T >::getDiagonalSize().

◆ operator()() [2/2]

template<typename T >

AXOM_HOST_DEVICE T & axom::numerics::Matrix< T >::operator()	(	IndexType	i,
		IndexType	j
	)

Given an \( M \times N \) matrix, \( \mathcal{A} \), return a reference to matrix element \( \alpha_{ij} \).

Parameters

[in]	i	the row index of the matrix element.
[in]	j	the column index of the matrix element.

Returns: \( \alpha_{ij} \) const reference to matrix element

Precondition: i >= 0 && i < m_rows; j >= 0 && j < m_cols

◆ getColumn() [1/2]

template<typename T >

AXOM_HOST_DEVICE const T * axom::numerics::Matrix< T >::getColumn ( IndexType j ) const

Returns a const pointer to the \( jth \) column of an \( M \times N \) matrix, \( \mathcal{A} \).

Parameters

[in] j the jth column of the matrix.

Returns: \( \mathcal{A}_{*j} \) pointer to the \( jth \) column.

Precondition: j >= 0 && j < m_cols

Note: Example Usage:
...
Matrix < double > A( MROWS,NCOLS );
const double* column = A.getColumn( j );
for ( IndexType i=0; i < MROWS; ++i ) {
std::cout << column[ i ] << " ";
}
...

Referenced by axom::numerics::Matrix< T >::getDiagonalSize(), axom::quest::getMeshTriangle(), and axom::numerics::Matrix< T >::swapColumns().

◆ getColumn() [2/2]

template<typename T >

AXOM_HOST_DEVICE T * axom::numerics::Matrix< T >::getColumn ( IndexType j )

Returns pointer to the \( jth \) column of an \( M \times N \) matrix, \( \mathcal{A} \).

Parameters

[in] j the jth column of the matrix.

Returns: \( \mathcal{A}_{*j} \) pointer to the \( jth \) column.

Precondition: j >= 0 && j < m_cols

Note: Example Usage:
...
Matrix < double > A( MROWS,NCOLS );
double* column = A.getColumn( j );
for ( IndexType i=0; i < MROWS; ++i ) {
column[ i ] = newval;
}
...

◆ getDiagonal() [2/3]

template<typename T >

const T * axom::numerics::Matrix< T >::getDiagonal	(	IndexType &	p,
		IndexType &	N
	)		const

Returns a const pointer for strided access along the main diagonal.

Parameters

[out]	p	stride used to access elements along the main diagonal.
[out]	N	upper-bound used to loop over the main diagonal entries.

Returns: diag pointer along the main diagonal.

Postcondition: p = m_rows+1; N = this->getDiaonalSize()*m_rows

Note: For non-square matrices, the entries along the main diagonal, are given by \( \alpha_{ii} \in \mathcal{A} \), where, \( i \in [0,N] \), \( N=min(num\_rows, num\_cols) \); Example Usage:
...
Matrix< double > A (MROWS,NCOLS);
IndexType p = 0;
IndexThype N = 0;
const double* diag = A.getDiagonal( p, N );
for ( IndexType i=0; i < N; i+=p ) {
std::cout << diag[ i ];
}
...

References axom::numerics::Matrix< T >::getDiagonalSize().

◆ getDiagonal() [3/3]

template<typename T >

T * axom::numerics::Matrix< T >::getDiagonal	(	IndexType &	p,
		IndexType &	N
	)

Returns a pointer for strided access along the main diagonal.

Parameters

[out]	p	stride used to access elements along the main diagonal.
[out]	N	upper-bound used to loop over the main diagonal entris.

Returns: diag pointer along the main diagonal.

Postcondition: p = m_rows+1; N = this->getDiagonalSize()*m_rows

Note: For non-square matrices, the entries along the main diagonal, are given by \( \alpha_{ii} \in \mathcal{A} \), where, \( i \in [0,N] \), \( N=min(num\_rows, num\_cols) \); Example Usage:
...
Matrix< double > A (MROWS,NCOLS);
IndexType p = 0;
IndexType N = 0;
const double* diag = A.getDiagonal( p,N );
for ( IndexType i=0; i < N; i+=p ) {
diag[ i ] = newval;
}
...

References axom::numerics::Matrix< T >::getDiagonalSize().

◆ getRow() [1/2]

template<typename T >

const T * axom::numerics::Matrix< T >::getRow	(	IndexType	i,
		IndexType &	p,
		IndexType &	N
	)		const

Returns a const pointer to the \( ith \) row of an \( M \times N \) matrix, \( \mathcal{A} \).

Parameters

[in]	i	index to the \( ith \) row of the matrix
[out]	p	stride used to access row elements
[out]	N	upper-bound to loop over

Returns: \( \mathcal{A}_{i*} \) pointer to the \( ith \) row.

Precondition: i >= 0 && i < m_rows

Postcondition: p == m_rows

Note: Example Usage:
...
Matrix< double > A( MROWS,NCOLS );
IndexType p = 0;
IndexType N = 0;
const double* row = A.getRow( irow, p, N );
for ( IndexType j=0; j < N; j+=p ) {
std::cout << row[ j ]
}
...

Referenced by axom::numerics::Matrix< T >::getDiagonalSize().

◆ getRow() [2/2]

template<typename T >

T * axom::numerics::Matrix< T >::getRow	(	IndexType	i,
		IndexType &	p,
		IndexType &	N
	)

Returns a pointer to the \( ith \) row of an \( M \times N \) matrix, \( \mathcal{A} \).

Parameters

[in]	i	index to the \( ith \) row of the matrix
[out]	p	stride used to access row elements
[out]	N	upper-bound to loop over

Returns: \( \mathcal{A}_{i*} \) pointer to the \( ith \) row.

Precondition: i >= 0 && i < m_rows

Postcondition: p == m_rows

Note: Example Usage:
...
Matrix< double > A( MROWS,NCOLS );
IndexType p = 0;
IndexType N = 0;
double* row = A.getRow( irow, p, N );
for ( IndexType j=0; j < N; j+=p ) {
row[ j ] = newval;
}
...

◆ data() [1/2]

template<typename T >

const T * axom::numerics::Matrix< T >::data ( ) const

Returns a const pointer to the raw data.

Returns: ptr pointer to the raw data.

Note: The raw data are stored in column-major layout.

Postcondition: ptr != nullptr

Referenced by axom::numerics::Matrix< T >::getDiagonalSize(), axom::numerics::Matrix< T >::Matrix(), axom::numerics::matrix_add(), axom::numerics::matrix_scalar_multiply(), and axom::numerics::matrix_subtract().

◆ data() [2/2]

template<typename T >

T * axom::numerics::Matrix< T >::data ( )

Returns pointer to the raw data.

Returns: ptr pointer to the raw data.

Note: The raw data are stored in column-major layout.

Postcondition: ptr != nullptr

◆ operator=()

template<typename T >

Matrix< T > & axom::numerics::Matrix< T >::operator= ( const Matrix< T > & rhs )

Overloaded assignment operator.

Parameters

[in] rhs matrix instance on the right-hand side.

Returns: M a copy of the matrix instance in rhs.

Referenced by axom::numerics::Matrix< T >::getDiagonalSize().

◆ identity()

template<typename T >

Matrix< T > axom::numerics::Matrix< T >::identity ( int n )

static

Returns an identity matrix \( \mathcal{I}_n \).

Parameters

[in] n the size of the identity matrix.

Returns: M the identity matrix of size \( \mathcal{I}_n \)

Precondition: n >= 1

Postcondition: M.isSquare()==true; M.getNumRows() == M.getNumCols() == n

Referenced by axom::numerics::Matrix< T >::getDiagonalSize().

◆ zeros()

template<typename T >

Matrix< T > axom::numerics::Matrix< T >::zeros	(	int	nrows,
		int	ncols
	)

static

Returns a zero matrix, \( \mathcal{A} \).

Parameters

[in]	nrows	the number of rows in the matrix.
[in]	ncols	the number of columns in the matrix.

Returns: \( \mathcal{A} \) a zero matrix.

Precondition: nrows >= 1; ncols >= 1

Postcondition: \( \alpha_{ij}=0 \forall \alpha_{ij} \in \mathcal{A} \)

References axom::numerics::Matrix< T >::fill().

Referenced by axom::numerics::Matrix< T >::getDiagonalSize(), axom::numerics::lower_triangular(), axom::numerics::matrix_add(), axom::numerics::matrix_multiply(), axom::numerics::matrix_subtract(), axom::numerics::matrix_transpose(), and axom::numerics::upper_triangular().

◆ ones()

template<typename T >

Matrix< T > axom::numerics::Matrix< T >::ones	(	int	nrows,
		int	ncols
	)

static

Returns a unity matrix, \( \mathcal{A} \).

Parameters

[in]	nrows	the number of rows in the matrix.
[in]	ncols	the number of columns in the matrix.

Returns: \( \mathcal{A} \) a zero matrix.

Precondition: nrows >= 1; ncols >= 1

Postcondition: \( \alpha_{ij}=1 \forall \alpha_{ij} \in \mathcal{A} \)

References AXOM_HOST_DEVICE, axom::deallocate(), and axom::numerics::Matrix< T >::fill().

Referenced by axom::numerics::Matrix< T >::getDiagonalSize().

The documentation for this class was generated from the following file:

/home/docs/checkouts/readthedocs.org/user_builds/axom/checkouts/v0.5.0/src/axom/core/numerics/Matrix.hpp

Public Member Functions

Static Public Member Functions

Detailed Description

template<typename T> class axom::numerics::Matrix< T >

Constructor & Destructor Documentation

◆ Matrix() [1/3]

◆ Matrix() [2/3]

◆ Matrix() [3/3]

◆ ~Matrix()

Member Function Documentation

◆ isSquare()

◆ empty()

◆ usesExternalBuffer()

◆ getNumRows()

◆ getNumColumns()

◆ getDiagonalSize()

◆ getDiagonal() [1/3]

◆ fillDiagonal()

◆ fillRow()

◆ fillColumn()

◆ fill()

◆ swapRows()

◆ swapColumns()

◆ operator()() [1/2]

◆ operator()() [2/2]

◆ getColumn() [1/2]

◆ getColumn() [2/2]

◆ getDiagonal() [2/3]

◆ getDiagonal() [3/3]

◆ getRow() [1/2]

◆ getRow() [2/2]

◆ data() [1/2]

◆ data() [2/2]

◆ operator=()

◆ identity()

◆ zeros()

◆ ones()

template<typename T>
class axom::numerics::Matrix< T >