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/develop/src/axom/core/numerics/Matrix.hpp>

Inheritance diagram for axom::numerics::Matrix< T >:

[legend]

Public Member Functions
	Matrix ()
	Default constructor. More...

	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...

bool	isIdentity () const
	Determines whether matrix is identity matrix. 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.getNumColumns(); // 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/4]

template<typename T >

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

inline

Default constructor.

◆ Matrix() [2/4]

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() [3/4]

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() [4/4]

template<typename T >

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

Copy constructor.

Parameters

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

References axom::copy().

◆ ~Matrix()

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) \)

◆ 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) \)

◆ 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) \)

◆ 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

◆ 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

◆ 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.

◆ 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 axom::utilities::swap().

◆ 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

◆ 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

◆ 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 ] << " ";

}

...

◆ 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 ];

}

...

◆ 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;

}

...

◆ 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 ]

}

...

◆ 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

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

◆ 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.

References axom::copy().

◆ isIdentity()

template<typename T >

bool axom::numerics::Matrix< T >::isIdentity

Determines whether matrix is identity matrix.

Returns: True if matrix is identity, false otherwise.

◆ 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

◆ 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().

◆ 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::numerics::Matrix< T >::fill().

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

/home/docs/checkouts/readthedocs.org/user_builds/axom/checkouts/develop/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/4]

◆ Matrix() [2/4]

◆ Matrix() [3/4]

◆ Matrix() [4/4]

◆ ~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=()

◆ isIdentity()

◆ identity()

◆ zeros()

◆ ones()

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