MatrixArray class inherits ValArray class and provides additional interfaces to ValArray which enable page-wise linear algebra operations for arrays of matrices. More...

#include "matrix-array.h"

Inheritance diagram for ns3::MatrixArray< T >:

Collaboration diagram for ns3::MatrixArray< T >:

Public Member Functions
	MatrixArray ()=default

	MatrixArray (const std::valarray< T > &values)
	Constructor creates a single array of values.size () elements and 1 column, and uses std::valarray<T> values to initialize the elements.

	MatrixArray (const std::vector< T > &values)
	Constructor creates a single array of values.size () elements and 1 column, and uses std::vector<T> values to initialize the elements.

	MatrixArray (size_t numRows, size_t numCols, const std::valarray< T > &values)
	Constructor creates a single matrix of numRows and numCols, and uses std::valarray<T> values to initialize the elements.

	MatrixArray (size_t numRows, size_t numCols, size_t numPages, const std::valarray< T > &values)
	Constructor creates the array of numPages matrices of numRows x numCols dimensions, and uses std::valarray<T> values to initialize all the elements.

	MatrixArray (size_t numRows, size_t numCols, size_t numPages, std::valarray< T > &&values)
	Constructor creates the array of numPages matrices of numRows x numCols dimensions, and moves std::valarray<T> values to initialize all the elements.

	MatrixArray (size_t numRows, size_t numCols, std::valarray< T > &&values)
	Constructor creates a single matrix of numRows and numCols, and moves std::valarray<T> values to initialize the elements.

	MatrixArray (size_t numRows, size_t numCols=1, size_t numPages=1)
	Constructor "pages" number of matrices that are of size "numRows"x"numCols", and are initialized with all-zero elements.

	MatrixArray (std::valarray< T > &&values)
	Constructor creates a single array of values.size () elements and 1 column, and moves std::valarray<T> values to initialize the elements.

template<bool EnableBool = true, typename = std::enable_if_t<(std::is_same_v<T, std::complex<double>> && EnableBool)>>
MatrixArray< T >	HermitianTranspose () const
	Function that performs the Hermitian transpose of this MatrixArray and returns a new matrix that is the result of the operation.

MatrixArray	MultiplyByLeftAndRightMatrix (const MatrixArray< T > &lMatrix, const MatrixArray< T > &rMatrix) const
	Multiply each matrix in the array by the left and the right matrix.

MatrixArray	operator* (const MatrixArray< T > &rhs) const
	Page-wise matrix multiplication.

MatrixArray	operator* (const T &rhs) const
	Element-wise multiplication with a scalar value.

MatrixArray	operator+ (const MatrixArray< T > &rhs) const
	operator+ definition for MatrixArray<T>.

MatrixArray	operator- () const
	unary operator- definition for MatrixArray<T>.

MatrixArray	operator- (const MatrixArray< T > &rhs) const
	binary operator- definition for MatrixArray<T>.

MatrixArray	Transpose () const
	This operator interprets the 3D array as an array of matrices, and performs a linear algebra operation on each of the matrices (pages), i.e., transposes the matrix or array of matrices definition for MatrixArray<T>.

Public Member Functions inherited from ns3::ValArray< T >
	ValArray ()=default

	ValArray (const std::valarray< T > &values)
	Constructor creates a single 1D array of values.size () elements and 1 column, and uses std::valarray<T> values to initialize the elements.

	ValArray (const std::vector< T > &values)
	Constructor creates a single 1D array of values.size () elements and 1 column, and uses values std::vector<T> to initialize the elements.

	ValArray (const ValArray< T > &)=default
	instruct the compiler to generate the implicitly declared copy constructor

	ValArray (size_t numRows, size_t numCols, const std::valarray< T > &values)
	Constructor creates a single 2D array of numRows and numCols, and uses std::valarray<T> values to initialize the elements.

	ValArray (size_t numRows, size_t numCols, size_t numPages, const std::valarray< T > &values)
	Constructor creates the 3D array of numRows x numCols x numPages dimensions, and uses std::valarray<T> values to initialize all the 2D arrays, where first numRows*numCols elements will belong to the first 2D array.

	ValArray (size_t numRows, size_t numCols, size_t numPages, std::valarray< T > &&values)
	Constructor creates the 3D array of numRows x numCols x numPages dimensions, and moves std::valarray<T> values to initialize all the 2D arrays, where first numRows*numCols elements will belong to the first 2D array.

	ValArray (size_t numRows, size_t numCols, std::valarray< T > &&values)
	Constructor creates a single 2D array of numRows and numCols, and moves std::valarray<T> values to initialize the elements.

	ValArray (size_t numRows, size_t numCols=1, size_t numPages=1)
	Constructor that creates "numPages" number of 2D arrays that are of dimensions "numRows"x"numCols", and are initialized with all-zero elements.

	ValArray (std::valarray< T > &&values)
	Constructor creates a single 1D array of values.size () elements and 1 column, and moves std::valarray<T> values to initialize the elements.

	ValArray (ValArray< T > &&)=default
	instruct the compiler to generate the implicitly declared move constructor

virtual	~ValArray ()=default
	instruct the compiler to generate the implicitly declared destructor

void	AssertEqualDims (const ValArray< T > &rhs) const
	Function that asserts if the dimensions of lhs and rhs ValArray are not equal and prints a message with the matrices dimensions.

T &	Elem (size_t row, size_t col, size_t page)
	Alternative access operator to access a specific element.

const T &	Elem (size_t row, size_t col, size_t page) const
	Alternative const access operator to access a specific element.

bool	EqualDims (const ValArray< T > &rhs) const
	Checks whether rhs and lhs ValArray objects have the same dimensions.

size_t	GetNumCols () const

size_t	GetNumPages () const

size_t	GetNumRows () const

T *	GetPagePtr (size_t pageIndex)
	Get a data pointer to a specific 2D array for use in linear algebra libraries.

const T *	GetPagePtr (size_t pageIndex) const
	Get a data pointer to a specific 2D array for use in linear algebra libraries.

size_t	GetSize () const

const std::valarray< T > &	GetValues () const
	Returns underlying values.

bool	IsAlmostEqual (const ValArray< T > &rhs, T tol) const
	Compare Valarray up to a given absolute tolerance.

bool	operator!= (const ValArray< T > &rhs) const
	operator!= definition for ValArray<T>.

T &	operator() (size_t index)
	Single-element access operator() for 1D ValArrays.

const T &	operator() (size_t index) const
	Single-element access operator() for 1D ValArrays.

T &	operator() (size_t rowIndex, size_t colIndex)
	Access operator for 2D ValArrays.

const T &	operator() (size_t rowIndex, size_t colIndex) const
	Const access operator for 2D ValArrays.

T &	operator() (size_t rowIndex, size_t colIndex, size_t pageIndex)
	Access operator, with bound-checking in debug profile.

const T &	operator() (size_t rowIndex, size_t colIndex, size_t pageIndex) const
	Const access operator, with bound-checking in debug profile.

ValArray	operator* (const T &rhs) const
	Element-wise multiplication with a scalar value.

ValArray	operator+ (const ValArray< T > &rhs) const
	operator+ definition for ValArray<T>.

ValArray< T > &	operator+= (const ValArray< T > &rhs)
	operator+= definition for ValArray<T>.

ValArray	operator- () const
	unary operator- definition for ValArray<T>.

ValArray	operator- (const ValArray< T > &rhs) const
	binary operator- definition for ValArray<T>.

ValArray< T > &	operator-= (const ValArray< T > &rhs)
	operator-= definition for ValArray<T>.

ValArray &	operator= (const ValArray< T > &)=default
	Copy assignment operator.

ValArray< T > &	operator= (ValArray< T > &&)=default
	Move assignment operator.

bool	operator== (const ValArray< T > &rhs) const
	operator== definition for ValArray<T>.

T &	operator[] (size_t index)
	Single-element access operator[] that can be used to access a specific element of 1D ValArray.

const T &	operator[] (size_t index) const
	Const access operator that can be used to access a specific element of 1D ValArray.

Public Member Functions inherited from ns3::SimpleRefCount< ValArray< T > >
	SimpleRefCount ()
	Default constructor.

	SimpleRefCount (const SimpleRefCount &o)
	Copy constructor.

uint32_t	GetReferenceCount () const
	Get the reference count of the object.

SimpleRefCount &	operator= (const SimpleRefCount &o)
	Assignment operator.

void	Ref () const
	Increment the reference count.

void	Unref () const
	Decrement the reference count.

Additional Inherited Members
Protected Attributes inherited from ns3::ValArray< T >
size_t	m_numCols
	The size of the second dimension, i.e., the number of columns of each 2D array.

size_t	m_numPages = 0
	The size of the third dimension, i.e., the number of 2D arrays.

size_t	m_numRows
	The size of the first dimension, i.e., the number of rows of each 2D array.

std::valarray< T >	m_values
	The data values.

Detailed Description

template<class T>
class ns3::MatrixArray< T >

MatrixArray class inherits ValArray class and provides additional interfaces to ValArray which enable page-wise linear algebra operations for arrays of matrices.

While ValArray class is focused on efficient storage, access and basic algebra element-wise operations on 3D numerical arrays, MatrixArray is focused on the efficient algebra operations on arrays of matrices.

Each page (2-dimensional array) within a 3D array is considered to be a matrix, and operations are performed separately for each page/matrix. For example, a multiplication of two MatrixArrays means that a matrix multiplication is performed between each page in the first MatrixArray with the corresponding page in the second MatrixArray. Some of the operations can use the Eigen3 matrix library for speedup. In addition, this class can be extended to provide interfaces to the Eigen3 matrix library and enable additional linear algebra operations. The objective of this class is to two-fold:

First, it provides simple interfaces to perform matrix operations in parallel on all pages without the need to write an outer loop over all the pages.
Second, it can improve the performance of such parallel matrix operations, as this class uses a single memory allocation and one common set of size variables (rows, cols) for all pages, which can be an advantage compared to having separate memory allocations and size variables for each page/matrix, especially when those matrices are very small.

Important characteristics:

Matrices are in column-major order.
Matrices can be 1-dimensional, in the sense that either the number of rows or columns is equal to 1.
The array of matrices can contain just one matrix or more matrices.
For binary operators, both MatrixArrays must have an equal number of pages, as well compatible row and column dimensions between the matrices.
Binary operators are performed among matrices with the same index from lhs and rhs matrix.
MatrixArray improves computationally complex matrix operations by using Eigen library when it is available at compile time. MatrixArray class makes use of Eigen Map class, which allows re-using already existing portion of memory as an Eigen type, e.g. ValArray can return a pointer to a memory where are placed elements of a specific matrix, and this can be passed to Eigen Map class which does not do a copy of the elements, but is using these elements directly in linear algebra operations.

Definition at line 82 of file matrix-array.h.

Constructor & Destructor Documentation

◆ MatrixArray() [1/9]

template<class T >

ns3::MatrixArray< T >::MatrixArray ( )

default

◆ MatrixArray() [2/9]

template<class T >

ns3::MatrixArray< T >::MatrixArray	(	size_t	numRows,
		size_t	numCols = `1`,
		size_t	numPages = `1`
	)

Constructor "pages" number of matrices that are of size "numRows"x"numCols", and are initialized with all-zero elements.

If only 1 parameter, numRows, is provided then a single 1D array is being created.

Parameters

numRows	the number of rows
numCols	the number of columns
numPages	the number of pages

Definition at line 37 of file matrix-array.cc.

◆ MatrixArray() [3/9]

template<class T >

ns3::MatrixArray< T >::MatrixArray ( const std::valarray< T > & values )

explicit

Constructor creates a single array of values.size () elements and 1 column, and uses std::valarray<T> values to initialize the elements.

Parameters

values std::valarray<T> that will be used to initialize elements of 1D array

Definition at line 43 of file matrix-array.cc.

◆ MatrixArray() [4/9]

template<class T >

ns3::MatrixArray< T >::MatrixArray ( std::valarray< T > && values )

Constructor creates a single array of values.size () elements and 1 column, and moves std::valarray<T> values to initialize the elements.

Parameters

values std::valarray<T> that will be moved to initialize elements of 1D array

Definition at line 49 of file matrix-array.cc.

◆ MatrixArray() [5/9]

template<class T >

ns3::MatrixArray< T >::MatrixArray ( const std::vector< T > & values )

explicit

Constructor creates a single array of values.size () elements and 1 column, and uses std::vector<T> values to initialize the elements.

Parameters

values std::vector<T> that will be used to initialize elements of 1D array

Definition at line 55 of file matrix-array.cc.

◆ MatrixArray() [6/9]

template<class T >

ns3::MatrixArray< T >::MatrixArray	(	size_t	numRows,
		size_t	numCols,
		const std::valarray< T > &	values
	)

Constructor creates a single matrix of numRows and numCols, and uses std::valarray<T> values to initialize the elements.

Parameters

numRows	the number of rows
numCols	the number of columns
values	std::valarray<T> that will be used to initialize elements of 3D array

Definition at line 61 of file matrix-array.cc.

◆ MatrixArray() [7/9]

template<class T >

ns3::MatrixArray< T >::MatrixArray	(	size_t	numRows,
		size_t	numCols,
		std::valarray< T > &&	values
	)

Constructor creates a single matrix of numRows and numCols, and moves std::valarray<T> values to initialize the elements.

Parameters

numRows	the number of rows
numCols	the number of columns
values	std::valarray<T> that will be moved to initialize elements of 3D array

Definition at line 67 of file matrix-array.cc.

◆ MatrixArray() [8/9]

template<class T >

ns3::MatrixArray< T >::MatrixArray	(	size_t	numRows,
		size_t	numCols,
		size_t	numPages,
		const std::valarray< T > &	values
	)

Constructor creates the array of numPages matrices of numRows x numCols dimensions, and uses std::valarray<T> values to initialize all the elements.

Parameters

numRows	the number of rows
numCols	the number of columns
numPages	the number of pages
values	std::valarray<T> that will be used to initialize elements of 3D array

Definition at line 73 of file matrix-array.cc.

◆ MatrixArray() [9/9]

template<class T >

ns3::MatrixArray< T >::MatrixArray	(	size_t	numRows,
		size_t	numCols,
		size_t	numPages,
		std::valarray< T > &&	values
	)

Constructor creates the array of numPages matrices of numRows x numCols dimensions, and moves std::valarray<T> values to initialize all the elements.

Parameters

numRows	the number of rows
numCols	the number of columns
numPages	the number of pages
values	std::valarray<T> that will be used to initialize elements of 3D array

Definition at line 82 of file matrix-array.cc.

Member Function Documentation

◆ HermitianTranspose()

template<class T >

template<bool EnableBool, typename >

template MatrixArray< std::complex< double > > ns3::MatrixArray< T >::HermitianTranspose ( ) const

Function that performs the Hermitian transpose of this MatrixArray and returns a new matrix that is the result of the operation.

This function assumes that the matrix contains complex numbers, because of that it is only available for the <std::complex<double>> specialization of MatrixArray.

Returns: Returns a new matrix that is the result of the Hermitian transpose

Definition at line 221 of file matrix-array.cc.

References ns3::GetSize(), and ns3::ValArray< T >::m_values.

Referenced by ns3::ThreeGppSpectrumPropagationLossModel::CalcBeamformingGain().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ MultiplyByLeftAndRightMatrix()

template<class T >

MatrixArray< T > ns3::MatrixArray< T >::MultiplyByLeftAndRightMatrix	(	const MatrixArray< T > &	lMatrix,
		const MatrixArray< T > &	rMatrix
	)		const

Multiply each matrix in the array by the left and the right matrix.

For each page of this MatrixArray the operation performed is lMatrix * matrix(pageIndex) * rMatrix, and the resulting MatrixArray<T> contains the array of the results per page. If "this" has dimensions M x N x P, lMatrix must have dimensions M number of columns, and a single page, and rMatrix must have N number of rows, and also a single page.

The result of this function will have the dimensions J x K x P. Where J is the number of rows of the lMatrix, and K is the number of columns of rMatrix. Dimensions are:

lMatrix(JxMx1) * this (MxNxP) * rMatrix(NxKx1) -> result(JxKxP)

This operation is not possible when using the multiplication operator because the number of pages does not match.

Parameters

lMatrix	the left matrix in the multiplication
rMatrix	the right matrix in the multiplication

Returns: Returns the result of the multiplication which is a 3D MatrixArray with dimensions J x K x P as explained previously.

Definition at line 161 of file matrix-array.cc.

References ns3::ValArray< T >::GetPagePtr(), ns3::ValArray< T >::m_numCols, ns3::ValArray< T >::m_numPages, ns3::ValArray< T >::m_numRows, and NS_ASSERT_MSG.

Referenced by ns3::tests::MatrixArrayTestCase< T >::DoRun().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ operator*() [1/2]

template<class T >

MatrixArray< T > ns3::MatrixArray< T >::operator* ( const MatrixArray< T > & rhs ) const

Page-wise matrix multiplication.

This operator interprets the 3D array as an array of matrices, and performs a linear algebra operation on each of the matrices (pages), i.e., matrices from this MatrixArray and rhs with the same page indices are multiplied. The number of columns of this MatrixArray must be equal to the number of rows in rhs, and rhs must have the same number of pages as this MatrixArray.

Parameters

rhs	is another MatrixArray instance

Returns: The array of results of matrix multiplications.

Definition at line 92 of file matrix-array.cc.

References ns3::ValArray< T >::m_numPages, and NS_ASSERT_MSG.

◆ operator*() [2/2]

template<class T >

MatrixArray< T > ns3::MatrixArray< T >::operator* ( const T & rhs ) const

inline

Element-wise multiplication with a scalar value.

Parameters

rhs	is a scalar value of type T

Returns: The matrix in which each element has been multiplied by the given scalar value.

Definition at line 254 of file matrix-array.h.

◆ operator+()

template<class T >

MatrixArray< T > ns3::MatrixArray< T >::operator+ ( const MatrixArray< T > & rhs ) const

inline

operator+ definition for MatrixArray<T>.

Parameters

rhs	The rhs MatrixArray object

Returns: The result of operator+ of this MatrixArray and rhs MatrixArray

Definition at line 264 of file matrix-array.h.

References ns3::ValArray< T >::m_values.

◆ operator-() [1/2]

template<class T >

MatrixArray< T > ns3::MatrixArray< T >::operator-

inline

unary operator- definition for MatrixArray<T>.

Returns: the result of the operator-

Definition at line 280 of file matrix-array.h.

◆ operator-() [2/2]

template<class T >

MatrixArray< T > ns3::MatrixArray< T >::operator- ( const MatrixArray< T > & rhs ) const

inline

binary operator- definition for MatrixArray<T>.

Parameters

rhs	The rhs MatrixArray object

Returns: The result of operator- of this MatrixArray and rhs MatrixArray

Definition at line 272 of file matrix-array.h.

References ns3::ValArray< T >::m_values.

◆ Transpose()

template<class T >

MatrixArray< T > ns3::MatrixArray< T >::Transpose

This operator interprets the 3D array as an array of matrices, and performs a linear algebra operation on each of the matrices (pages), i.e., transposes the matrix or array of matrices definition for MatrixArray<T>.

Returns: The resulting MatrixArray composed of the array of transposed matrices.

Definition at line 131 of file matrix-array.cc.

Referenced by ns3::tests::MatrixArrayTestCase< T >::DoRun().

Here is the caller graph for this function:

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

src/core/model/matrix-array.h
src/core/model/matrix-array.cc

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ MatrixArray() [1/9]

◆ MatrixArray() [2/9]

◆ MatrixArray() [3/9]

◆ MatrixArray() [4/9]

◆ MatrixArray() [5/9]

◆ MatrixArray() [6/9]

◆ MatrixArray() [7/9]

◆ MatrixArray() [8/9]

◆ MatrixArray() [9/9]

Member Function Documentation

◆ HermitianTranspose()

◆ MultiplyByLeftAndRightMatrix()

◆ operator*() [1/2]

◆ operator*() [2/2]

◆ operator+()

◆ operator-() [1/2]

◆ operator-() [2/2]

◆ Transpose()