LAPACK++  2022.05.00
LAPACK C++ API
Computational routines

Functions

int64_t lapack::hetrd (lapack::Uplo uplo, int64_t n, std::complex< double > *A, int64_t lda, double *D, double *E, std::complex< double > *tau)
 Reduces a Hermitian matrix A to real symmetric tridiagonal form T by a unitary similarity transformation: \(Q^H A Q = T\). More...
 
int64_t lapack::hetrd (lapack::Uplo uplo, int64_t n, std::complex< float > *A, int64_t lda, float *D, float *E, std::complex< float > *tau)
 
int64_t lapack::hetrd_2stage (lapack::Job jobz, lapack::Uplo uplo, int64_t n, std::complex< double > *A, int64_t lda, double *D, double *E, std::complex< double > *tau, std::complex< double > *hous2, int64_t lhous2)
 Reduces a Hermitian matrix A to real symmetric tridiagonal form T by a unitary similarity transformation: \(Q1^H Q2^H A Q2 Q1 = T\). More...
 
int64_t lapack::hetrd_2stage (lapack::Job jobz, lapack::Uplo uplo, int64_t n, std::complex< float > *A, int64_t lda, float *D, float *E, std::complex< float > *tau, std::complex< float > *hous2, int64_t lhous2)
 
int64_t lapack::orgtr (lapack::Uplo uplo, int64_t n, double *A, int64_t lda, double const *tau)
 
int64_t lapack::orgtr (lapack::Uplo uplo, int64_t n, float *A, int64_t lda, float const *tau)
 
int64_t lapack::ormtr (lapack::Side side, lapack::Uplo uplo, lapack::Op trans, int64_t m, int64_t n, double const *A, int64_t lda, double const *tau, double *C, int64_t ldc)
 
int64_t lapack::ormtr (lapack::Side side, lapack::Uplo uplo, lapack::Op trans, int64_t m, int64_t n, float const *A, int64_t lda, float const *tau, float *C, int64_t ldc)
 
template<typename scalar_t >
int64_t lapack::sturm (int64_t n, scalar_t const *diag, scalar_t const *offd, scalar_t u)
 
int64_t lapack::sytrd (lapack::Uplo uplo, int64_t n, double *A, int64_t lda, double *D, double *E, double *tau)
 
int64_t lapack::sytrd (lapack::Uplo uplo, int64_t n, float *A, int64_t lda, float *D, float *E, float *tau)
 
int64_t lapack::sytrd_2stage (lapack::Job jobz, lapack::Uplo uplo, int64_t n, double *A, int64_t lda, double *D, double *E, double *tau, double *hous2, int64_t lhous2)
 
int64_t lapack::sytrd_2stage (lapack::Job jobz, lapack::Uplo uplo, int64_t n, float *A, int64_t lda, float *D, float *E, float *tau, float *hous2, int64_t lhous2)
 
int64_t lapack::ungtr (lapack::Uplo uplo, int64_t n, std::complex< double > *A, int64_t lda, std::complex< double > const *tau)
 Generates an n-by-n unitary matrix Q which is defined as the product of n-1 elementary reflectors of order n, as returned by lapack::hetrd: More...
 
int64_t lapack::ungtr (lapack::Uplo uplo, int64_t n, std::complex< float > *A, int64_t lda, std::complex< float > const *tau)
 
int64_t lapack::unmtr (lapack::Side side, lapack::Uplo uplo, lapack::Op trans, int64_t m, int64_t n, std::complex< double > const *A, int64_t lda, std::complex< double > const *tau, std::complex< double > *C, int64_t ldc)
 Multiplies the general m-by-n matrix C by Q from lapack::hetrd as follows: More...
 
int64_t lapack::unmtr (lapack::Side side, lapack::Uplo uplo, lapack::Op trans, int64_t m, int64_t n, std::complex< float > const *A, int64_t lda, std::complex< float > const *tau, std::complex< float > *C, int64_t ldc)
 
int64_t lapack::upmtr (lapack::Side side, lapack::Uplo uplo, lapack::Op trans, int64_t m, int64_t n, std::complex< double > const *AP, std::complex< double > const *tau, std::complex< double > *C, int64_t ldc)
 Multiplies the general m-by-n matrix C by Q from lapack::hptrd as follows: More...
 
int64_t lapack::upmtr (lapack::Side side, lapack::Uplo uplo, lapack::Op trans, int64_t m, int64_t n, std::complex< float > const *AP, std::complex< float > const *tau, std::complex< float > *C, int64_t ldc)
 

Detailed Description

Function Documentation

◆ hetrd()

int64_t lapack::hetrd ( lapack::Uplo  uplo,
int64_t  n,
std::complex< double > *  A,
int64_t  lda,
double *  D,
double *  E,
std::complex< double > *  tau 
)

Reduces a Hermitian matrix A to real symmetric tridiagonal form T by a unitary similarity transformation: \(Q^H A Q = T\).

Overloaded versions are available for float, double, std::complex<float>, and std::complex<double>. For real matrices, this is an alias for lapack::sytrd.

Parameters
[in]uplo
  • lapack::Uplo::Upper: Upper triangle of A is stored;
  • lapack::Uplo::Lower: Lower triangle of A is stored.
[in]nThe order of the matrix A. n >= 0.
[in,out]AThe n-by-n matrix A, stored in an lda-by-n array. On entry, the Hermitian matrix A.
  • If uplo = Upper, the leading n-by-n upper triangular part of A contains the upper triangular part of the matrix A, and the strictly lower triangular part of A is not referenced.
  • If uplo = Lower, the leading n-by-n lower triangular part of A contains the lower triangular part of the matrix A, and the strictly upper triangular part of A is not referenced.
  • On exit, if uplo = Upper, the diagonal and first superdiagonal of A are overwritten by the corresponding elements of the tridiagonal matrix T, and the elements above the first superdiagonal, with the array tau, represent the unitary matrix Q as a product of elementary reflectors;
  • On exit, if uplo = Lower, the diagonal and first subdiagonal of A are overwritten by the corresponding elements of the tridiagonal matrix T, and the elements below the first subdiagonal, with the array tau, represent the unitary matrix Q as a product of elementary reflectors. See Further Details.
[in]ldaThe leading dimension of the array A. lda >= max(1,n).
[out]DThe vector D of length n. The diagonal elements of the tridiagonal matrix T: D(i) = A(i,i).
[out]EThe vector E of length n-1. The off-diagonal elements of the tridiagonal matrix T: E(i) = A(i,i+1) if uplo = Upper, E(i) = A(i+1,i) if uplo = Lower.
[out]tauThe vector tau of length n-1. The scalar factors of the elementary reflectors (see Further Details).
Returns
= 0: successful exit
Further Details

If uplo = Upper, the matrix Q is represented as a product of elementary reflectors

\[ Q = H(n-1) . . . H(2) H(1). \]

Each H(i) has the form

\[ H(i) = I - \tau v v^H \]

where \(\tau\) is a scalar, and v is a vector with v(i+1:n) = 0 and v(i) = 1; v(1:i-1) is stored on exit in A(1:i-1,i+1), and \(\tau\) in tau(i).

If uplo = Lower, the matrix Q is represented as a product of elementary reflectors

\[ Q = H(1) H(2) . . . H(n-1). \]

Each H(i) has the form

\[ H(i) = I - \tau v v^H \]

where \(\tau\) is a scalar, and v is a vector with v(1:i) = 0 and v(i+1) = 1; v(i+2:n) is stored on exit in A(i+2:n,i), and \(\tau\) in tau(i).

The contents of A on exit are illustrated by the following examples with n = 5:

if uplo = Upper:                       if uplo = Lower:

(  d   e   v2  v3  v4 )              (  d                  )
(      d   e   v3  v4 )              (  e   d              )
(          d   e   v4 )              (  v1  e   d          )
(              d   e  )              (  v1  v2  e   d      )
(                  d  )              (  v1  v2  v3  e   d  )

where d and e denote diagonal and off-diagonal elements of T, and vi denotes an element of the vector defining H(i).

◆ hetrd_2stage()

int64_t lapack::hetrd_2stage ( lapack::Job  jobz,
lapack::Uplo  uplo,
int64_t  n,
std::complex< double > *  A,
int64_t  lda,
double *  D,
double *  E,
std::complex< double > *  tau,
std::complex< double > *  hous2,
int64_t  lhous2 
)

Reduces a Hermitian matrix A to real symmetric tridiagonal form T by a unitary similarity transformation: \(Q1^H Q2^H A Q2 Q1 = T\).

Overloaded versions are available for float, double, std::complex<float>, and std::complex<double>. For real matrices, this is an alias for lapack::sytrd_2stage.

Parameters
[in]jobz
  • lapack::Job::NoVec: No need for the Housholder representation, in particular for the second stage (band to tridiagonal).
  • lapack::Job::Vec: the Householder representation is needed to either generate \(Q1 Q2\) or to apply \(Q1 Q2\). Not yet available (as of LAPACK 3.8.0).
[in]uplo
  • lapack::Uplo::Upper: Upper triangle of A is stored;
  • lapack::Uplo::Lower: Lower triangle of A is stored.
[in]nThe order of the matrix A. n >= 0.
[in,out]AThe n-by-n matrix A, stored in an lda-by-n array. On entry, the Hermitian matrix A.
  • If uplo = Upper, the leading n-by-n upper triangular part of A contains the upper triangular part of the matrix A, and the strictly lower triangular part of A is not referenced.
  • If uplo = Lower, the leading n-by-n lower triangular part of A contains the lower triangular part of the matrix A, and the strictly upper triangular part of A is not referenced.
  • On exit, if uplo = Upper, the diagonal and upper band of A are overwritten by the corresponding elements of the internal band-diagonal matrix AB, and the elements above the KD superdiagonal, with the array tau, represent the unitary matrix Q1 as a product of elementary reflectors.
  • On exit, if uplo = Lower, the diagonal and lower band of A are overwritten by the corresponding elements of the internal band-diagonal matrix AB, and the elements below the KD subdiagonal, with the array tau, represent the unitary matrix Q1 as a product of elementary reflectors. See Further Details.
[in]ldaThe leading dimension of the array A. lda >= max(1,n).
[out]DThe vector D of length n. The diagonal elements of the tridiagonal matrix T.
[out]EThe vector E of length n-1. The off-diagonal elements of the tridiagonal matrix T.
[out]tauThe vector tau of length n-kd. The scalar factors of the elementary reflectors of the first stage (see Further Details).
[out]hous2The vector hous2 of length lhous2. Stores the Householder representation of the stage2 band to tridiagonal.
[in]lhous2The dimension of the array hous2.
  • If lhous2 = -1, then a query is assumed; the routine only calculates the optimal size of the hous2 array, returns this value as the first entry of the hous2 array, and no error message related to lhous2 is issued.
  • If jobz=NoVec, lhous2 = max(1, 4*n);
  • if jobz=Vec, option not yet available.
Returns
= 0: successful exit
Further Details

Implemented by Azzam Haidar.

All details are available on technical report, SC11, SC13 papers.

Azzam Haidar, Hatem Ltaief, and Jack Dongarra. Parallel reduction to condensed forms for symmetric eigenvalue problems using aggregated fine-grained and memory-aware kernels. In Proceedings of 2011 International Conference for High Performance Computing, Networking, Storage and Analysis (SC '11), New York, NY, USA, Article 8, 11 pages. http://doi.acm.org/10.1145/2063384.2063394

A. Haidar, J. Kurzak, P. Luszczek, 2013. An improved parallel singular value algorithm and its implementation for multicore hardware, In Proceedings of 2013 International Conference for High Performance Computing, Networking, Storage and Analysis (SC '13). Denver, Colorado, USA, 2013. Article 90, 12 pages. http://doi.acm.org/10.1145/2503210.2503292

A. Haidar, R. Solca, S. Tomov, T. Schulthess and J. Dongarra. A novel hybrid CPU-GPU generalized eigensolver for electronic structure calculations based on fine-grained memory aware tasks. International Journal of High Performance Computing Applications. Volume 28 Issue 2, Pages 196-209, May 2014. http://hpc.sagepub.com/content/28/2/196

◆ orgtr()

int64_t lapack::orgtr ( lapack::Uplo  uplo,
int64_t  n,
double *  A,
int64_t  lda,
double const *  tau 
)
See also
lapack::ungtr

◆ ormtr()

int64_t lapack::ormtr ( lapack::Side  side,
lapack::Uplo  uplo,
lapack::Op  trans,
int64_t  m,
int64_t  n,
double const *  A,
int64_t  lda,
double const *  tau,
double *  C,
int64_t  ldc 
)
See also
lapack::unmtr

◆ sturm()

template<typename scalar_t >
int64_t lapack::sturm ( int64_t const  n,
scalar_t const *  diag,
scalar_t const *  offd,
scalar_t const  u 
)

sturm computes a Scaled Sturm Sequence using a real symmetric tri-diagonal matrix. NOTE this calls no LAPACK routine; the code is here. Only single and double precision code exist.

Parameters: All parameters are read-only by this routine.

Parameters
[in]diaga vector of 'n' diagonal elements.
[in]offda vector of 'n-1' off-diagonal elements.
[in]nThe order of the matrix.
[in]uThe sigma test point.
Return values
Numberof eigenvalues strictly less than u.

◆ sytrd()

int64_t lapack::sytrd ( lapack::Uplo  uplo,
int64_t  n,
double *  A,
int64_t  lda,
double *  D,
double *  E,
double *  tau 
)
See also
lapack::hetrd

◆ sytrd_2stage()

int64_t lapack::sytrd_2stage ( lapack::Job  jobz,
lapack::Uplo  uplo,
int64_t  n,
double *  A,
int64_t  lda,
double *  D,
double *  E,
double *  tau,
double *  hous2,
int64_t  lhous2 
)
See also
lapack::hetrd_2stage

◆ ungtr()

int64_t lapack::ungtr ( lapack::Uplo  uplo,
int64_t  n,
std::complex< double > *  A,
int64_t  lda,
std::complex< double > const *  tau 
)

Generates an n-by-n unitary matrix Q which is defined as the product of n-1 elementary reflectors of order n, as returned by lapack::hetrd:

  • if uplo = Upper, \(Q = H(n-1) \dots H(2) H(1),\)
  • if uplo = Lower, \(Q = H(1) H(2) \dots H(n-1).\)

Overloaded versions are available for float, double, std::complex<float>, and std::complex<double>. For real matrices, this is an alias for lapack::orgtr.

Parameters
[in]uplo
  • lapack::Uplo::Upper: Upper triangle of A contains elementary reflectors from lapack::hetrd;
  • lapack::Uplo::Lower: Lower triangle of A contains elementary reflectors from lapack::hetrd.
[in]nThe order of the matrix Q. n >= 0.
[in,out]AThe n-by-n matrix A, stored in an lda-by-n array. On entry, the vectors which define the elementary reflectors, as returned by lapack::hetrd. On exit, the n-by-n unitary matrix Q.
[in]ldaThe leading dimension of the array A. lda >= n.
[in]tauThe vector tau of length n-1. tau(i) must contain the scalar factor of the elementary reflector H(i), as returned by lapack::hetrd.
Returns
= 0: successful exit

◆ unmtr()

int64_t lapack::unmtr ( lapack::Side  side,
lapack::Uplo  uplo,
lapack::Op  trans,
int64_t  m,
int64_t  n,
std::complex< double > const *  A,
int64_t  lda,
std::complex< double > const *  tau,
std::complex< double > *  C,
int64_t  ldc 
)

Multiplies the general m-by-n matrix C by Q from lapack::hetrd as follows:

  • side = left, trans = NoTrans: \(Q C\)
  • side = right, trans = NoTrans: \(C Q\)
  • side = left, trans = ConjTrans: \(Q^H C\)
  • side = right, trans = ConjTrans: \(C Q^H\)

where Q is a unitary matrix of order nq, with nq = m if side = Left and nq = n if side = Right. Q is defined as the product of nq-1 elementary reflectors, as returned by lapack::hetrd:

  • if uplo = Upper, \(Q = H(nq-1) \dots H(2) H(1);\)
  • if uplo = Lower, \(Q = H(1) H(2) \dots H(nq-1).\)

Overloaded versions are available for float, double, std::complex<float>, and std::complex<double>. For real matrices, this is an alias for lapack::ormtr.

Parameters
[in]side
  • lapack::Side::Left: apply \(Q\) or \(Q^H\) from the Left;
  • lapack::Side::Right: apply \(Q\) or \(Q^H\) from the Right.
[in]uplo
  • lapack::Uplo::Upper: Upper triangle of A contains elementary reflectors from lapack::hetrd;
  • lapack::Uplo::Lower: Lower triangle of A contains elementary reflectors from lapack::hetrd.
[in]trans
  • lapack::Op::NoTrans: No transpose, apply \(Q\);
  • lapack::Op::ConjTrans: Conjugate transpose, apply \(Q^H\).
[in]mThe number of rows of the matrix C. m >= 0.
[in]nThe number of columns of the matrix C. n >= 0.
[in]AThe vectors which define the elementary reflectors, as returned by lapack::hetrd.
  • If side = Left, the m-by-m matrix A, stored in an lda-by-m array;
  • if side = Right, the n-by-n matrix A, stored in an lda-by-n array.
[in]ldaThe leading dimension of the array A.
  • If side = Left, lda >= max(1,m);
  • If side = Right, lda >= max(1,n).
[in]tautau(i) must contain the scalar factor of the elementary reflector H(i), as returned by lapack::hetrd.
  • If side = Left, the vector tau of length m-1;
  • if side = Right, the vector tau of length n-1.
[in,out]CThe m-by-n matrix C, stored in an ldc-by-n array. On entry, the m-by-n matrix C. On exit, C is overwritten by \(Q C\) or \(Q^H C\) or \(C Q^H\) or \(C Q\).
[in]ldcThe leading dimension of the array C. ldc >= max(1,m).
Returns
= 0: successful exit

◆ upmtr()

int64_t lapack::upmtr ( lapack::Side  side,
lapack::Uplo  uplo,
lapack::Op  trans,
int64_t  m,
int64_t  n,
std::complex< double > const *  AP,
std::complex< double > const *  tau,
std::complex< double > *  C,
int64_t  ldc 
)

Multiplies the general m-by-n matrix C by Q from lapack::hptrd as follows:

  • side = left, trans = NoTrans: \(Q C\)
  • side = right, trans = NoTrans: \(C Q\)
  • side = left, trans = ConjTrans: \(Q^H C\)
  • side = right, trans = ConjTrans: \(C Q^H\)

where Q is a unitary matrix of order nq, with nq = m if side = Left and nq = n if side = Right. Q is defined as the product of nq-1 elementary reflectors, as returned by lapack::hptrd using packed storage:

  • if uplo = Upper, \(Q = H(nq-1) \dots H(2) H(1);\)
  • if uplo = Lower, \(Q = H(1) H(2) \dots H(nq-1).\)

Overloaded versions are available for float, double, std::complex<float>, and std::complex<double>. For real matrices, this is an alias for lapack::opmtr.

Parameters
[in]side
  • lapack::Side::Left: apply \(Q\) or \(Q^H\) from the Left;
  • lapack::Side::Right: apply \(Q\) or \(Q^H\) from the Right.
[in]uplo
  • lapack::Uplo::Upper: Upper triangular packed storage used in previous call to lapack::hptrd;
  • lapack::Uplo::Lower: Lower triangular packed storage used in previous call to lapack::hptrd.
[in]trans
  • lapack::Op::NoTrans: No transpose, apply \(Q\);
  • lapack::Op::ConjTrans: Conjugate transpose, apply \(Q^H\).
[in]mThe number of rows of the matrix C. m >= 0.
[in]nThe number of columns of the matrix C. n >= 0.
[in]APThe vectors which define the elementary reflectors, as returned by lapack::hptrd. AP is modified by the routine but restored on exit.
  • If side = Left, AP is of length m*(m+1)/2;
  • if side = Right, AP is of length n*(n+1)/2.
[in]tautau(i) must contain the scalar factor of the elementary reflector H(i), as returned by lapack::hptrd.
  • If side = Left, the vector tau of length m-1;
  • if side = Right, the vector tau of length n-1.
[in,out]CThe m-by-n matrix C, stored in an ldc-by-n array. On entry, the m-by-n matrix C. On exit, C is overwritten by \(Q C\) or \(Q^H C\) or \(C Q^H\) or \(C Q\).
[in]ldcThe leading dimension of the array C. ldc >= max(1,m).
Returns
= 0: successful exit