Sequential matrices¶
The Matrix<T>
class is the building of the library:
its purpose is to provide convenient mechanisms for performing basic matrix
manipulations, such as setting and querying individual matrix entries,
without giving up compatibility with interfaces such as BLAS and LAPACK,
which assume columnmajor storage.
An example of generating an \(m \times n\) matrix of real doubleprecision numbers where the \((i,j)\) entry is equal to \(ij\) 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(ij) );
whereas the complex doubleprecision equivalent could use Complex<double>
, which is currently a typedef for std::complex<double>
.
The underlying data storage for Matrix<T>
is simply a contiguous
buffer that stores entries in a columnmajor fashion with a leading
dimension which is only required to be at least as large as the height of the
matrix (so that entry \((i,j)\) is located at position i+j*ldim
).
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(ij);
For immutable 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 bottomright \(6 \times 7\) submatrix using
#include "elemental.hpp" ... auto ABR = View( A, 1, 2, 3, 4 );
since the bottomright \(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 );
.
 template<>

class
Matrix
<T>¶ The goal is for the Matrix class to support any datatype T which supports both addition and multiplication and has the associated identities (that is, when the datatype T is a ring). While there are several barriers to reaching this goal, it is important to keep in mind that, in addition to T being allowed to be a real or complex (single or doubleprecision) floatingpoint type, signed integers are also supported.
Constructors and destructors
Note
Many of the following constructors have the default parameter
bool fixed=false
, which can be changed totrue
in order to produce a Matrix whose entries can be modified, but the matrix’s dimensions cannot. This is useful for theDistMatrix<T>
class, which contains a localMatrix<T>
whose entries can be locally modified in cases where it would not make sense to change the local matrix size (which should instead result from changing the size of the full distributed matrix).
Matrix
(bool fixed = false)¶ 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, bool fixed = false)¶ A height \(\times\) width matrix is created with an unspecified leading dimension (though it is currently implemented as \(\max(height,1)\)).

Matrix
(int height, int width, int ldim, bool fixed = false)¶ A height \(\times\) width matrix is created with a leading dimension equal to ldim (which must be greater than or equal \(\max(height,1)\)).

Matrix
(int height, int width, const T *buffer, int ldim, bool fixed = false)¶

Matrix
(int height, int width, T *buffer, int ldim, bool fixed = false)¶ A matrix is built around a columnmajor (immutable) buffer with the specified dimensions. The memory pointed to by buffer should not be freed until after the
Matrix<T>
object is destructed.

Matrix
(Matrix<T> &&A) noexcept¶ A C++11 move constructor which creates a new matrix by moving the metadata from the specified matrix over to the new matrix, which cheaply gives the new matrix control over the resources originally assigned to the input matrix.

~Matrix
()¶ Frees all resources owned by the matrix upon destruction.
Assignment and reconfiguration

Matrix<T> &
operator=
(Matrix<T> &&A)¶ A C++11 move assignment which swaps the metadata of two matrices so that the resources owned by the two objects will have been cheaply switched.

void
Empty
()¶ Sets the matrix to \(0 \times 0\) and frees any owned resources.

void
Resize
(int height, int width)¶ Reconfigures the matrix to be height \(\times\) width.

void
Resize
(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 \(\max(height,1)\)).

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

void
LockedAttach
(int height, int width, const T *buffer, int ldim)¶ Reconfigure the matrix around the specified (unmodifiable) buffer.

void
Control
(int height, int width, T *buffer, int ldim)¶ Reconfigure the matrix around a specified buffer and give ownership of the resource to the matrix.
Basic queries

int
Height
() const¶

int
Width
() const¶ Return the height/width of the matrix.

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.

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.

T *
Buffer
()¶

const T *
LockedBuffer
() const¶ Return a pointer to the (immutable) underlying buffer.

T *
Buffer
(int i, int j)¶

const T *
LockedBuffer
(int i, int j) const¶ Return a pointer to the (immutable) portion of the buffer that holds entry \((i,j)\).

bool
Viewing
() const¶ Returns true if the underlying buffer is merely a pointer into an externallyowned buffer.

bool
FixedSize
() const¶ Returns true if the dimensions of the matrix cannot be changed.

bool
Locked
() const¶ Returns true if the entries of the matrix cannot be changed.
Singleentry manipulation

T
Get
(int i, int j) const¶

Base<T>
GetRealPart
(int i, int j) const¶

Base<T>
GetImagPart
(int i, int j) const¶ Return entry \((i,j)\) (or its real or imaginary part).

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

void
SetRealPart
(int i, int j, Base<T> alpha)¶

void
SetImagPart
(int i, int j, Base<T> alpha)¶ Set entry \((i,j)\) (or its real or imaginary part) to \(\alpha\).

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

void
UpdateRealPart
(int i, int j, Base<T> alpha)¶

void
UpdateImagPart
(int i, int j, Base<T> alpha)¶ Add \(\alpha\) to entry \((i,j)\) (or its real or imaginary part).

void
MakeReal
(int i, int j)¶ Force the \((i,j)\) entry to be real.

void
Conjugate
(int i, int j)¶ Conjugate the \((i,j)\) entry of the matrix.
Diagonal manipulation

void
GetImagPartOfDiagonal
(Matrix<Base<T>> &d, int offset = 0) const¶ Modify \(d\) into a columnvector containing the entries (or their real or imaginary parts) 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\)).

Matrix<Base<T>>
GetImagPartOfDiagonal
(int offset = 0) const¶ Efficiently construct and return the particular diagonal (or its real or imaginary part) via C++11 move semantics.

void
SetImagPartOfDiagonal
(const Matrix<Base<T>> &d, int offset = 0)¶ Set the entries (or their real or imaginary parts) in the offset diagonal entries from the contents of the columnvector \(d\).

void
UpdateImagPartOfDiagonal
(const Matrix<Base<T>> &d, int offset = 0)¶ Add the contents of \(d\) onto the entries (or the real or imaginary parts) in the offset diagonal.

void
MakeDiagonalReal
(int offset = 0)¶ Force the specified diagonal of the matrix to be real.

void
ConjugateDiagonal
(int offset = 0)¶ Conjugate the specified diagonal of the matrix.
Arbitrarysubmatrix manipulation

void
GetSubmatrix
(const std::vector<int> &rowInd, const std::vector<int> &colInd, Matrix<T> &ASub) const¶

void
GetRealPartOfSubmatrix
(const std::vector<int> &rowInd, const std::vector<int> &colInd, Matrix<Base<T>> &ASub) const¶

void
GetImagPartOfSubmatrix
(const std::vector<int> &rowInd, const std::vector<int> &colInd, Matrix<Base<T>> &ASub) const¶ Return the submatrix (or its real or imaginary part) with the specified row and column indices via ASub.

Matrix<Base<T>>
GetRealPartOfSubmatrix
(const std::vector<int> &rowInd, const std::vector<int> &colInd) const¶

Matrix<Base<T>>
GetImagPartOfSubmatrix
(const std::vector<int> &rowInd, const std::vector<int> &colInd) const¶ Return the submatrix (or its real or imaginary part) with the specified row and column indices via C++11 move semantics.

void
SetSubmatrix
(const std::vector<int> &rowInd, const std::vector<int> &colInd, const Matrix<T> &ASub)¶

void
SetRealPartOfSubmatrix
(const std::vector<int> &rowInd, const std::vector<int> &colInd, const Matrix<Base<T>> &ASub)¶

void
SetImagPartOfSubmatrix
(const std::vector<int> &rowInd, const std::vector<int> &colInd, const Matrix<Base<T>> &ASub)¶ Set the submatrix (or its real or imaginary part) with the specified row and column indices equal to the matrix ASub.

void
UpdateSubmatrix
(const std::vector<int> &rowInd, const std::vector<int> &colInd, T alpha, const Matrix<T> &ASub)¶

void
UpdateRealPartOfSubmatrix
(const std::vector<int> &rowInd, const std::vector<int> &colInd, Base<T> alpha, const Matrix<Base<T>> &ASub)¶

void
UpdateImagPartOfSubmatrix
(const std::vector<int> &rowInd, const std::vector<int> &colInd, Base<T> alpha, const Matrix<Base<T>> &ASub)¶ Update the submatrix (or its real or imaginary part) with the specified row and column indices with alpha times ASub.

void
MakeSubmatrixReal
(const std::vector<int> &rowInd, const std::vector<int> &colInd)¶ Force the submatrix with the specified row and column indices to be real.

void
ConjugateSubmatrix
(const std::vector<int> &rowInd, const std::vector<int> &colInd)¶ Conjugate the entries in the submatrix with the specified row and column indices.

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

class
Matrix
<Real>¶ Used to denote that the underlying datatype Real is real.
 template<>

class
Matrix
<Complex<Real>>¶ Used to denote that the underlying datatype
Complex<Real>
is complex with base type Real.
 template<>

class
Matrix
<F>¶ Used to denote that the underlying datatype F is a field.
 template<>

class
Matrix
<int>¶ When the underlying datatype is a signed integer.