Elemental 0.80 documentation

The Matrix class

«  Environment   ::   Contents   ::   The Grid class  »

The Matrix class

This is the basic building block of the library: its purpose it to provide convenient mechanisms for performing basic matrix manipulation operations, such as setting and querying individual matrix entries, without giving up compatibility with interfaces such as BLAS and LAPACK, which assume column-major storage.

An example of generating an \(m \times n\) matrix of real double-precision numbers where the \((i,j)\) entry is equal to \(i-j\) would be:

#include "elemental.hpp"
using namespace elem;
...
Matrix<double> A( m, n );
for( int j=0; j<n; ++j )
    for( int i=0; i<m; ++i )
        A.Set( i, j, double(i-j) );

The underlying data storage is simply a contiguous buffer that stores entries in a column-major fashion with an arbitrary leading dimension. For modifiable instances of the Matrix<T> class, the routine Matrix<T>::Buffer returns a pointer to the underlying buffer, while Matrix<T>::LDim returns the leading dimension; these two routines could be used to directly perform the equivalent of the first code sample as follows:

#include "elemental.hpp"
using namespace elem;
...
Matrix<double> A( m, n );
double* buffer = A.Buffer();
const int ldim = A.LDim();
for( int j=0; j<n; ++j )
    for( int i=0; i<m; ++i )
        buffer[i+j*ldim] = double(i-j);

For constant instances of the Matrix<T> class, a const pointer to the underlying data can similarly be returned with a call to Matrix<T>::LockedBuffer(). In addition, a (const) pointer to the place in the (const) buffer where entry \((i,j)\) resides can be easily retrieved with a call to Matrix<T>::Buffer() or Matrix<T>::LockedBuffer().

It is also important to be able to create matrices which are simply views of existing (sub)matrices. For example, if A is a \(10 \times 10\) matrix of complex doubles, then a matrix \(A_{BR}\) can easily be created to view the bottom-right \(6 \times 7\) submatrix using

#include "elemental.hpp"
...
Matrix<Complex<double> > ABR;
View( ABR, A, 1, 2, 3, 4 );

since the bottom-right \(3 \times 4\) submatrix beings at index \((1,2)\). In general, to view the \(M \times N\) submatrix starting at entry \((i,j)\), one would call View( ABR, A, i, j, M, N );.

type class Matrix<T>

The most general case, where the underlying datatype T is only assumed to be a ring; that is, it supports multiplication and addition and has the appropriate identities.

Constructors

Matrix()

This simply creates a default \(0 \times 0\) matrix with a leading dimension of one (BLAS and LAPACK require positive leading dimensions).

Matrix(int height, int width)

A height \(\times\) width matrix is created with an unspecified leading dimension (though it is currently implemented as std::max(height,1)).

Matrix(int height, int width, int ldim)

A height \(\times\) width matrix is created with a leading dimension equal to ldim (which must be greater than or equal std::min(height,1)).

Matrix(int height, int width, const T* buffer, int ldim)

A matrix is built around column-major constant buffer const T* buffer with the specified dimensions. The memory pointed to by buffer should not be freed until after the Matrix<T> object is destructed.

Matrix(int height, int width, T* buffer, int ldim)

A matrix is built around the column-major modifiable buffer T* buffer with the specified dimensions. The memory pointed to by buffer should not be freed until after the Matrix<T> object is destructed.

Matrix(const Matrix<T>& A)

A copy (not a view) of the matrix \(A\) is built.

Basic information

int Height() const

Return the height of the matrix.

int Width() const

Return the width of the matrix.

int DiagonalLength(int offset=0 ) const

Return the length of the specified diagonal of the matrix: an offset of \(0\) refers to the main diagonal, an offset of \(1\) refers to the superdiagonal, an offset of \(-1\) refers to the subdiagonal, etc.

int LDim() const

Return the leading dimension of the underlying buffer.

int MemorySize() const

Return the number of entries of type T that this Matrix<T> instance has allocated space for.

T* Buffer()

Return a pointer to the underlying buffer.

const T* LockedBuffer() const

Return a pointer to the underlying buffer that does not allow for modifying the data.

T* Buffer(int i, int j)

Return a pointer to the portion of the buffer that holds entry \((i,j)\).

const T* LockedBuffer(int i, int j) const

Return a pointer to the portion of the buffer that holds entry \((i,j)\) that does not allow for modifying the data.

I/O

void Print(const std::string msg="") const

The matrix is printed to standard output (std::cout) with the preceding message msg (which is empty if unspecified).

void Print(std::ostream& os, const std::string msg="") const

The matrix is printed to the output stream os with the preceding message msg (which is empty if unspecified).

Entry manipulation

T Get(int i, int j) const

Return entry \((i,j)\).

void Set(int i, int j, T alpha)

Set entry \((i,j)\) to \(\alpha\).

void Update(int i, int j, T alpha)

Add \(\alpha\) to entry \((i,j)\).

void GetDiagonal(Matrix<T>& d, int offset=0 ) const

Modify \(d\) into a column-vector containing the entries lying on the offset diagonal of our matrix (for instance, the main diagonal has offset \(0\), the subdiagonal has offset \(-1\), and the superdiagonal has offset \(+1\)).

void SetDiagonal(const Matrix<T>& d, int offset=0 )

Set the entries in the offset diagonal entries from the contents of the column-vector \(d\).

void UpdateDiagonal(const Matrix<T>& d, int offset=0 )

Add the contents of \(d\) onto the entries in the offset diagonal.

Note

Many of the following routines are only valid for complex datatypes.

typename Base<T>::type GetRealPart(int i, int j) const

Return the real part of entry \((i,j)\).

typename Base<T>::type GetImagPart(int i, int j) const

Return the imaginary part of entry \((i,j)\).

void SetRealPart(int i, int j, typename Base<T>::type alpha)

Set the real part of entry \((i,j)\) to \(\alpha\).

void SetImagPart(int i, int j, typename Base<T>::type alpha)

Set the imaginary part of entry \((i,j)\) to \(\alpha\).

void UpdateRealPart(int i, int j, typename Base<T>::type alpha)

Add \(\alpha\) to the real part of entry \((i,j)\).

void UpdateImagPart(int i, int j, typename Base<T>::type alpha)

Add \(\alpha\) to the imaginary part of entry \((i,j)\).

void GetRealPartOfDiagonal(Matrix<typename Base<T>::type>& d, int offset=0 ) const

Modify \(d\) into a column-vector containing the real parts of the entries in the offset diagonal.

void GetImagPartOfDiagonal(Matrix<typename Base<T>::type>& d, int offset=0 ) const

Modify \(d\) into a column-vector containing the imaginary parts of the entries in the offset diagonal.

void SetRealPartOfDiagonal(const Matrix<typename Base<T>::type>& d, int offset=0 )

Set the real parts of the entries in the offset diagonal from the contents of the column-vector \(d\).

void SetImagPartOfDiagonal(const Matrix<typename Base<T>::type>& d, int offset=0 )

Set the imaginary parts of the entries in the offset diagonal from the column-vector \(d\).

void UpdateRealPartOfDiagonal(const Matrix<typename Base<T>::type>& d, int offset=0 )

Add the contents of the column-vector \(d\) onto the real parts of the entries in the offset diagonal.

void UpdateImagPartOfDiagonal(const Matrix<typename Base<T>::type>& d, int offset=0 )

Add the contents of the column-vector \(d\) onto the imaginary parts of the entries in the offset diagonal.

Views

bool Viewing() const

Return whether or not this matrix is currently viewing another matrix.

bool Locked() const

Return whether or not we can modify the data we are viewing.

void Attach(int height, int width, T* buffer, int ldim)

Reconfigure the matrix around the specified buffer.

void LockedAttach(int height, int width, const T* buffer, int ldim)

Reconfigure the matrix around the specified unmodifiable buffer.

Utilities

const Matrix<T>& operator=(const Matrix<T>& A)

Create a copy of matrix \(A\).

void Empty()

Sets the matrix to \(0 \times 0\) and frees the underlying buffer.

void ResizeTo(int height, int width)

Reconfigures the matrix to be height \(\times\) width.

void ResizeTo(int height, int width, int ldim)

Reconfigures the matrix to be height \(\times\) width, but with leading dimension equal to ldim (which must be greater than or equal to std::min(height,1)).

Special cases used in Elemental

This list of special cases is here to help clarify the notation used throughout Elemental’s source (as well as this documentation). These are all special cases of Matrix<T>.

type class Matrix<R>

Used to denote that the underlying datatype R is real.

type class Matrix<Complex<R>>

Used to denote that the underlying datatype Complex<R> is complex with base type R.

type class Matrix<F>

Used to denote that the underlying datatype F is a field.

«  Environment   ::   Contents   ::   The Grid class  »