# Level 3¶

The prototypes for the following routines can be found at include/elemental/blas-like/decl.hpp, while the implementations are in include/elemental/blas-like/level3/.

## Gemm¶

General matrix-matrix multiplication: updates $$C := \alpha A^\# B^\sharp + \beta C$$, where $$M^\#$$ and $$M^\sharp$$ are individually defined to be one of $$\{M,M^T,M^H\}$$.

void Gemm(Orientation orientationOfA, Orientation orientationOfB, T alpha, const Matrix<T> &A, const Matrix<T> &B, T beta, Matrix<T> &C)
void Gemm(Orientation orientationOfA, Orientation orientationOfB, T alpha, const DistMatrix<T> &A, const DistMatrix<T> &B, T beta, DistMatrix<T> &C)

## Hemm¶

Hermitian matrix-matrix multiplication: updates $$C := \alpha A B + \beta C$$, or $$C := \alpha B A + \beta C$$, depending upon whether side is set to LEFT or RIGHT, respectively. In both of these types of updates, $$A$$ is implicitly Hermitian and only the triangle specified by uplo is accessed.

void Hemm(LeftOrRight side, UpperOrLower uplo, T alpha, const Matrix<T> &A, const Matrix<T> &B, T beta, Matrix<T> &C)
void Hemm(LeftOrRight side, UpperOrLower uplo, T alpha, const DistMatrix<T> &A, const DistMatrix<T> &B, T beta, DistMatrix<T> &C)

## Her2k¶

Hermitian rank-2K update: updates $$C := \alpha (A B^H + B A^H) + \beta C$$, or $$C := \alpha (A^H B + B^H A) + \beta C$$, depending upon whether orientation is set to NORMAL or ADJOINT, respectively. Only the triangle of $$C$$ specified by the uplo parameter is modified.

void Her2k(UpperOrLower uplo, Orientation orientation, T alpha, const Matrix<T> &A, const Matrix<T> &B, T beta, Matrix<T> &C)
void Her2k(UpperOrLower uplo, Orientation orientation, T alpha, const DistMatrix<T> &A, const DistMatrix<T> &B, T beta, DistMatrix<T> &C)

Please see SetLocalTrr2kBlocksize<T>() and LocalTrr2kBlocksize<T>() in the Tuning parameters section for information on tuning the distributed Her2k().

## Herk¶

Hermitian rank-K update: updates $$C := \alpha A A^H + \beta C$$, or $$C := \alpha A^H A + \beta C$$, depending upon whether orientation is set to NORMAL or ADJOINT, respectively. Only the triangle of $$C$$ specified by the uplo parameter is modified.

void Herk(UpperOrLower uplo, Orientation orientation, T alpha, const Matrix<T> &A, T beta, Matrix<T> &C)
void Herk(UpperOrLower uplo, Orientation orientation, T alpha, const DistMatrix<T> &A, T beta, DistMatrix<T> &C)

Please see SetLocalTrrkBlocksize<T>() and LocalTrrkBlocksize<T>() in the Tuning parameters section for information on tuning the distributed Herk().

## Multi-shift QuasiTrsm¶

Solve for $$X$$ in the linear system

$T^\# X - X D^\# = Y$

or

$X T^\# - D^\# X = Y$

where $$T$$ is quasi-triangular, $$D$$ is diagonal, and $$A^\#$$ is defined to be one of $$\{A,A^T,A^H\}$$. The data movement requires almost no modification from that of QuasiTrsm().

Note that the term quasi-triangular is in the context of real Schur decompositions, which produce triangular matrices with mixes of $$1 \times 1$$ and $$2 \times 2$$ diagonal blocks.

Note

There is no corresponding BLAS routine, but it is a natural extension of Trsm.

void MultiShiftQuasiTrsm(LeftOrRight side, UpperOrLower uplo, Orientation orientation, F alpha, const Matrix<F> &T, const Matrix<F> &shifts, Matrix<F> &X)
void MultiShiftQuasiTrsm(LeftOrRight side, UpperOrLower uplo, Orientation orientation, F alpha, const DistMatrix<F> &T, const DistMatrix<F, VR, STAR> &shifts, DistMatrix<F> &X)

Overwrite the columns of X with the solutions to the shifted linear systems.

void MultiShiftQuasiTrsm(LeftOrRight side, UpperOrLower uplo, Orientation orientation, Complex<Real> alpha, const Matrix<Real> &T, const Matrix<Complex<Real>> &shifts, Matrix<Real> &XReal, Matrix<Real> &XImag)
void MultiShiftQuasiTrsm(LeftOrRight side, UpperOrLower uplo, Orientation orientation, Complex<Real> alpha, const DistMatrix<Real> &T, const DistMatrix<Complex<Real>, VR, STAR> &shifts, DistMatrix<Real> &XReal, DistMatrix<Real> &XImag)

Overwrite the columns of the real and imaginary parts of X with the solutions to the shifted linear systems.

## Multi-shift Trsm¶

Solve for $$X$$ in the linear system

$T^\# X - X D^\# = Y$

or

$X T^\# - D^\# X = Y$

where $$T$$ is triangular, $$D$$ is diagonal, and $$A^\#$$ is defined to be one of $$\{A,A^T,A^H\}$$. The data movement requires almost no modification from that of Trsm().

Note

There is no corresponding BLAS routine, but it is a natural modification of Trsm.

void MultiShiftTrsm(LeftOrRight side, UpperOrLower uplo, Orientation orientation, F alpha, const Matrix<F> &T, const Matrix<F> &shifts, Matrix<F> &X)
void MultiShiftTrsm(LeftOrRight side, UpperOrLower uplo, Orientation orientation, F alpha, const DistMatrix<F> &T, const DistMatrix<F, VR, STAR> &shifts, DistMatrix<F> &X)

Overwrite the columns of X with the solutions to the shifted linear systems.

void MultiShiftTrsm(LeftOrRight side, UpperOrLower uplo, Orientation orientation, Complex<Real> alpha, const Matrix<Real> &T, const Matrix<Complex<Real>> &shifts, Matrix<Real> &XReal, Matrix<Real> &XImag)
void MultiShiftTrsm(LeftOrRight side, UpperOrLower uplo, Orientation orientation, Complex<Real> alpha, const DistMatrix<Real> &T, const DistMatrix<Complex<Real>, VR, STAR> &shifts, DistMatrix<Real> &XReal, DistMatrix<Real> &XImag)

Overwrite the columns of the real and imaginary parts of X with the solutions to the shifted linear systems.

## QuasiTrsm¶

Solve for $$X$$ in the linear system

$T^\# X = Y$

or

$X T^\# = Y$

where $$T$$ is quasi-triangular and $$A^\#$$ is defined to be one of $$\{A,A^T,A^H\}$$. The algorithm is very similar to that of Trsm().

Note that the term quasi-triangular is in the context of real Schur decompositions, which produce triangular matrices with mixes of $$1 \times 1$$ and $$2 \times 2$$ diagonal blocks.

Note

There is no corresponding BLAS routine, but it is a natural extension of Trsm.

void QuasiTrsm(LeftOrRight side, UpperOrLower uplo, Orientation orientation, F alpha, const Matrix<F> &T, const Matrix<F> &shifts, Matrix<F> &X, bool checkIfSingular = false)
void QuasiTrsm(LeftOrRight side, UpperOrLower uplo, Orientation orientation, F alpha, const DistMatrix<F> &T, const DistMatrix<F, VR, STAR> &shifts, DistMatrix<F> &X, bool checkIfSingular = false)

Overwrite the columns of X with the solutions to the shifted linear systems.

## Symm¶

Symmetric matrix-matrix multiplication: updates $$C := \alpha A B + \beta C$$, or $$C := \alpha B A + \beta C$$, depending upon whether side is set to LEFT or RIGHT, respectively. In both of these types of updates, $$A$$ is implicitly symmetric and only the triangle specified by uplo is accessed.

void Symm(LeftOrRight side, UpperOrLower uplo, T alpha, const Matrix<T> &A, const Matrix<T> &B, T beta, Matrix<T> &C, bool conjugate = false)
void Symm(LeftOrRight side, UpperOrLower uplo, T alpha, const DistMatrix<T> &A, const DistMatrix<T> &B, T beta, DistMatrix<T> &C, bool conjugate = false)

## Syr2k¶

Symmetric rank-2K update: updates $$C := \alpha (A B^T + B A^T) + \beta C$$, or $$C := \alpha (A^T B + B^T A) + \beta C$$, depending upon whether orientation is set to NORMAL or TRANSPOSE, respectively. Only the triangle of $$C$$ specified by the uplo parameter is modified.

void Syr2k(UpperOrLower uplo, Orientation orientation, T alpha, const Matrix<T> &A, const Matrix<T> &B, T beta, Matrix<T> &C)
void Syr2k(UpperOrLower uplo, Orientation orientation, T alpha, const DistMatrix<T> &A, const DistMatrix<T> &B, T beta, DistMatrix<T> &C)

Please see SetLocalTrr2kBlocksize<T>() and LocalTrr2kBlocksize<T>() in the Tuning parameters section for information on tuning the distributed Syr2k().

## Syrk¶

Symmetric rank-K update: updates $$C := \alpha A A^T + \beta C$$, or $$C := \alpha A^T A + \beta C$$, depending upon whether orientation is set to NORMAL or TRANSPOSE, respectively. Only the triangle of $$C$$ specified by the uplo parameter is modified.

void Syrk(UpperOrLower uplo, Orientation orientation, T alpha, const Matrix<T> &A, T beta, Matrix<T> &C)
void Syrk(UpperOrLower uplo, Orientation orientation, T alpha, const DistMatrix<T> &A, T beta, DistMatrix<T> &C)

Please see SetLocalTrrkBlocksize<T>() and LocalTrrkBlocksize<T>() in the Tuning parameters section for information on tuning the distributed Syrk().

## Trmm¶

Triangular matrix-matrix multiplication: performs $$C := \alpha A^\# B$$, or $$C := \alpha B A^\#$$, depending upon whether side was chosen to be LEFT or RIGHT, respectively. Whether $$A$$ is treated as lower or upper triangular is determined by uplo, and $$A^\#$$ is defined to be one of $$\{A,A^T,A^H\}$$ (and diag determines whether $$A$$ is treated as unit-diagonal or not).

void Trmm(LeftOrRight side, UpperOrLower uplo, Orientation orientation, UnitOrNonUnit diag, T alpha, const Matrix<T> &A, Matrix<T> &B)
void Trmm(LeftOrRight side, UpperOrLower uplo, Orientation orientation, UnitOrNonUnit diag, T alpha, const DistMatrix<T> &A, DistMatrix<T> &B)

## Trr2k¶

Triangular rank-2k update: performs $$E := \alpha ( A^\# B^\sharp + C^\Diamond D^\triangle ) + \beta E$$, where only the triangle of E specified by uplo is modified, and the orientation of each input matrix, e.g., $$A^\# \in \{A,A^T,A^H\}$$, is determined by orientationOfX for each $$X \in \left\{A,B,C,D\right\}$$.

Note

There is no corresponding BLAS routine, but it is a natural generalization of “symmetric” and “Hermitian” updates.

void Trr2k(UpperOrLower uplo, Orientation orientationOfA, Orientation orientationOfB, Orientation orientationOfC, Orientation orientationOfD, T alpha, const Matrix<T> &A, const Matrix<T> &B, const Matrix<T> &C, const Matrix<T> &D, T beta, Matrix<T> &E)
void Trr2k(UpperOrLower uplo, Orientation orientationOfA, Orientation orientationOfB, Orientation orientationOfC, Orientation orientationOfD, T alpha, const DistMatrix<T> &A, const DistMatrix<T> &B, const DistMatrix<T> &C, const DistMatrix<T> &D, T beta, DistMatrix<T> &E)

## Trrk¶

Triangular rank-k update: performs $$C := \alpha A^\# B^\sharp + \beta C$$, where only the triangle of C specified by uplo is modified, and the orientations $$A^\#$$ and $$B^\sharp$$ are determined by orientationOfA and orientationOfB, respectively.

Note

There is no corresponding BLAS routine, but this type of update is frequently encountered, even in serial. For instance, the symmetric rank-k update performed during an LDL factorization is symmetric but one of the two update matrices is scaled by D.

void Trrk(UpperOrLower uplo, Orientation orientationOfA, Orientation orientationOfB, T alpha, const Matrix<T> &A, const Matrix<T> &B, T beta, Matrix<T> &C)
void Trrk(UpperOrLower uplo, Orientation orientationOfA, Orientation orientationOfB, T alpha, const DistMatrix<T> &A, const DistMatrix<T> &B, T beta, DistMatrix<T> &C)

## Trtrmm¶

Note

This routine loosely corresponds with the LAPACK routines ?lauum.

Symmetric/Hermitian triangular matrix-matrix multiply: performs $$L := L^T L$$, $$L := L^H L$$, $$U := U U^T$$, or $$U := U U^H$$, depending upon the choice of the orientation and uplo parameters.

void Trtrmm(Orientation orientation, UpperOrLower uplo, Matrix<T> &A)
void Trtrmm(Orientation orientation, UpperOrLower uplo, DistMatrix<T> &A)

## Trdtrmm¶

Note

This is a modification of Trtrmm for LDL factorizations.

Symmetric/Hermitian triangular matrix-matrix multiply (with diagonal scaling): performs $$L := L^T D^{-1} L$$, $$L := L^H D^{-1} L$$, $$U := U D^{-1} U^T$$, or $$U := U D^{-1} U^H$$, depending upon the choice of the orientation and uplo parameters. Note that $$L$$ and $$U$$ are unit-diagonal and their diagonal is overwritten with $$D$$.

void Trdtrmm(Orientation orientation, UpperOrLower uplo, Matrix<F> &A)
void Trdtrmm(Orientation orientation, UpperOrLower uplo, DistMatrix<F> &A)

## Trsm¶

Triangular solve with multiple right-hand sides: performs $$C := \alpha A^{-\#} B$$, or $$C := \alpha B A^{-\#}$$, depending upon whether side was chosen to be LEFT or RIGHT, respectively. Whether $$A$$ is treated as lower or upper triangular is determined by uplo, and $$A^{-\#}$$ can be $$A^{-1}$$, $$A^{-T}$$, or $$A^{-H}$$ (and diag determines whether $$A$$ is treated as unit-diagonal or not).

void Trsm(LeftOrRight side, UpperOrLower uplo, Orientation orientation, UnitOrNonUnit diag, F alpha, const Matrix<F> &A, Matrix<F> &B)
void Trsm(LeftOrRight side, UpperOrLower uplo, Orientation orientation, UnitOrNonUnit diag, F alpha, const DistMatrix<F> &A, DistMatrix<F> &B)

## Trstrm¶

Performs a triangular solve against a triangular matrix. Only the Left Lower Normal option is currently supported.

void Trstrm(LeftOrRight side, UpperOrLower uplo, Orientation orientation, UnitOrNonUnit diag, F alpha, const Matrix<F> &A, Matrix<F> &X, bool checkIfSingular = true)
void Trstrm(LeftOrRight side, UpperOrLower uplo, Orientation orientation, UnitOrNonUnit diag, F alpha, const DistMatrix<F> &A, DistMatrix<F> &X, bool checkIfSingular = true)

## Two-sided Trmm¶

Performs a two-sided triangular multiplication with multiple right-hand sides which preserves the symmetry of the input matrix, either $$A := L^H A L$$ or $$A := U A U^H$$.

void TwoSidedTrmm(UpperOrLower uplo, UnitOrNonUnit diag, Matrix<T> &A, const Matrix<T> &B)
void TwoSidedTrmm(UpperOrLower uplo, UnitOrNonUnit diag, DistMatrix<T> &A, const DistMatrix<T> &B)

## Two-sided Trsm¶

Performs a two-sided triangular solves with multiple right-hand sides which preserves the symmetry of the input matrix, either $$A := L^{-1} A L^{-H}$$ or $$A := U^{-H} A U^{-1}$$.

void TwoSidedTrsm(UpperOrLower uplo, UnitOrNonUnit diag, Matrix<F> &A, const Matrix<F> &B)
void TwoSidedTrsm(UpperOrLower uplo, UnitOrNonUnit diag, DistMatrix<F> &A, const DistMatrix<F> &B)