LAPACK++  2022.05.00
LAPACK C++ API
Standard, A = U Sigma V^H

Functions

int64_t lapack::gesdd (lapack::Job jobz, int64_t m, int64_t n, double *A, int64_t lda, double *S, double *U, int64_t ldu, double *VT, int64_t ldvt)
 
int64_t lapack::gesdd (lapack::Job jobz, int64_t m, int64_t n, float *A, int64_t lda, float *S, float *U, int64_t ldu, float *VT, int64_t ldvt)
 
int64_t lapack::gesdd (lapack::Job jobz, int64_t m, int64_t n, std::complex< double > *A, int64_t lda, double *S, std::complex< double > *U, int64_t ldu, std::complex< double > *VT, int64_t ldvt)
 Computes the singular value decomposition (SVD) of a m-by-n matrix A, optionally computing the left and/or right singular vectors, by using divide-and-conquer method. More...
 
int64_t lapack::gesdd (lapack::Job jobz, int64_t m, int64_t n, std::complex< float > *A, int64_t lda, float *S, std::complex< float > *U, int64_t ldu, std::complex< float > *VT, int64_t ldvt)
 
int64_t lapack::gesvd (lapack::Job jobu, lapack::Job jobvt, int64_t m, int64_t n, double *A, int64_t lda, double *S, double *U, int64_t ldu, double *VT, int64_t ldvt)
 
int64_t lapack::gesvd (lapack::Job jobu, lapack::Job jobvt, int64_t m, int64_t n, float *A, int64_t lda, float *S, float *U, int64_t ldu, float *VT, int64_t ldvt)
 
int64_t lapack::gesvd (lapack::Job jobu, lapack::Job jobvt, int64_t m, int64_t n, std::complex< double > *A, int64_t lda, double *S, std::complex< double > *U, int64_t ldu, std::complex< double > *VT, int64_t ldvt)
 Computes the singular value decomposition (SVD) of a m-by-n matrix A, optionally computing the left and/or right singular vectors. More...
 
int64_t lapack::gesvd (lapack::Job jobu, lapack::Job jobvt, int64_t m, int64_t n, std::complex< float > *A, int64_t lda, float *S, std::complex< float > *U, int64_t ldu, std::complex< float > *VT, int64_t ldvt)
 
int64_t lapack::gesvdx (lapack::Job jobu, lapack::Job jobvt, lapack::Range range, int64_t m, int64_t n, double *A, int64_t lda, double vl, double vu, int64_t il, int64_t iu, int64_t *ns, double *S, double *U, int64_t ldu, double *VT, int64_t ldvt)
 
int64_t lapack::gesvdx (lapack::Job jobu, lapack::Job jobvt, lapack::Range range, int64_t m, int64_t n, float *A, int64_t lda, float vl, float vu, int64_t il, int64_t iu, int64_t *ns, float *S, float *U, int64_t ldu, float *VT, int64_t ldvt)
 
int64_t lapack::gesvdx (lapack::Job jobu, lapack::Job jobvt, lapack::Range range, int64_t m, int64_t n, std::complex< double > *A, int64_t lda, double vl, double vu, int64_t il, int64_t iu, int64_t *nfound, double *S, std::complex< double > *U, int64_t ldu, std::complex< double > *VT, int64_t ldvt)
 Computes the singular value decomposition (SVD) of a m-by-n matrix A, optionally computing the left and/or right singular vectors. More...
 
int64_t lapack::gesvdx (lapack::Job jobu, lapack::Job jobvt, lapack::Range range, int64_t m, int64_t n, std::complex< float > *A, int64_t lda, float vl, float vu, int64_t il, int64_t iu, int64_t *ns, float *S, std::complex< float > *U, int64_t ldu, std::complex< float > *VT, int64_t ldvt)
 

Detailed Description

Function Documentation

◆ gesdd()

int64_t lapack::gesdd ( lapack::Job  jobz,
int64_t  m,
int64_t  n,
std::complex< double > *  A,
int64_t  lda,
double *  S,
std::complex< double > *  U,
int64_t  ldu,
std::complex< double > *  VT,
int64_t  ldvt 
)

Computes the singular value decomposition (SVD) of a m-by-n matrix A, optionally computing the left and/or right singular vectors, by using divide-and-conquer method.

The SVD is written

\[ A = U \Sigma V^H \]

where \(\Sigma\) is an m-by-n matrix which is zero except for its min(m,n) diagonal elements, U is an m-by-m unitary matrix, and V is an n-by-n unitary matrix. The diagonal elements of \(\Sigma\) are the singular values of A; they are real and non-negative, and are returned in descending order. The first min(m,n) columns of U and V are the left and right singular vectors of A.

Note that the routine returns VT \(= V^H\), not V.

The divide and conquer algorithm makes very mild assumptions about floating point arithmetic. It will work on machines with a guard digit in add/subtract, or on those binary machines without guard digits which subtract like the Cray X-MP, Cray Y-MP, Cray C-90, or Cray-2. It could conceivably fail on hexadecimal or decimal machines without guard digits, but we know of none.

Overloaded versions are available for float, double, std::complex<float>, and std::complex<double>.

Parameters
[in]jobzSpecifies options for computing all or part of the matrix U:
  • lapack::Job::AllVec: all m columns of U and all n rows of \(V^H\) are returned in the arrays U and VT;
  • lapack::Job::SomeVec: the first min(m,n) columns of U and the first min(m,n) rows of \(V^H\) are returned in the arrays U and VT;
  • lapack::Job::OverwriteVec:
    • If m >= n, the first n columns of U are overwritten in the array A and all rows of \(V^H\) are returned in the array VT;
    • otherwise, all columns of U are returned in the array U and the first m rows of \(V^H\) are overwritten in the array A;
  • lapack::Job::NoVec: no columns of U or rows of \(V^H\) are computed.
[in]mThe number of rows of the input matrix A. m >= 0.
[in]nThe number of columns of the input matrix A. n >= 0.
[in,out]AThe m-by-n matrix A, stored in an lda-by-n array. On entry, the m-by-n matrix A. On exit:
  • If jobz = OverwriteVec,
    • if m >= n, A is overwritten with the first n columns of U (the left singular vectors, stored columnwise);
    • if m < n, A is overwritten with the first m rows of \(V^H\) (the right singular vectors, stored rowwise).
  • Otherwise, the contents of A are destroyed.
[in]ldaThe leading dimension of the array A. lda >= max(1,m).
[out]SThe vector S of length min(m,n). The singular values of A, sorted so that S(i) >= S(i+1).
[out]UThe m-by-ucol matrix U, stored in an ldu-by-ucol array.
  • If jobz = AllVec or (jobz = OverwriteVec and m < n), ucol = m and U contains the m-by-m unitary matrix U;
  • if jobz = SomeVec, ucol = min(m,n) and U contains the first min(m,n) columns of U (the left singular vectors, stored columnwise);
  • if (jobz = OverwriteVec and m >= n), or jobz = NoVec, U is not referenced.
[in]lduThe leading dimension of the array U. ldu >= 1; if jobz = SomeVec or AllVec or (jobz = OverwriteVec and m < n), ldu >= m.
[out]VTThe vrow-by-n matrix VT, stored in an ldvt-by-n array.
  • If jobz = AllVec or (jobz = OverwriteVec and m >= n), vrow = n and VT contains the n-by-n unitary matrix \(V^H\);
  • if jobz = SomeVec, vrow = min(m,n) and VT contains the first min(m,n) rows of \(V^H\) (the right singular vectors, stored rowwise);
  • if (jobz = OverwriteVec and m < n), or jobz = NoVec, VT is not referenced.
[in]ldvtThe leading dimension of the array VT. ldvt >= 1;
  • if jobz = AllVec or (jobz = OverwriteVec and m >= n), ldvt >= n;
  • if jobz = SomeVec, ldvt >= min(m,n).
Returns
= 0: successful exit.
> 0: The updating process of lapack::bdsdc did not converge.

◆ gesvd()

int64_t lapack::gesvd ( lapack::Job  jobu,
lapack::Job  jobvt,
int64_t  m,
int64_t  n,
std::complex< double > *  A,
int64_t  lda,
double *  S,
std::complex< double > *  U,
int64_t  ldu,
std::complex< double > *  VT,
int64_t  ldvt 
)

Computes the singular value decomposition (SVD) of a m-by-n matrix A, optionally computing the left and/or right singular vectors.

The SVD is written

\[ A = U \Sigma V^H \]

where \(\Sigma\) is an m-by-n matrix which is zero except for its min(m,n) diagonal elements, U is an m-by-m unitary matrix, and V is an n-by-n unitary matrix. The diagonal elements of \(\Sigma\) are the singular values of A; they are real and non-negative, and are returned in descending order. The first min(m,n) columns of U and V are the left and right singular vectors of A.

Note that the routine returns VT \(= V^H\), not V.

Overloaded versions are available for float, double, std::complex<float>, and std::complex<double>.

Parameters
[in]jobuSpecifies options for computing all or part of the matrix U:
  • lapack::Job::AllVec: all m columns of U are returned in array U:
  • lapack::Job::SomeVec: the first min(m,n) columns of U (the left singular vectors) are returned in the array U;
  • lapack::Job::OverwriteVec: the first min(m,n) columns of U (the left singular vectors) are overwritten on the array A;
  • lapack::Job::NoVec: no columns of U (no left singular vectors) are computed.
[in]jobvtSpecifies options for computing all or part of the matrix \(V^H\):
  • lapack::Job::AllVec: all n rows of \(V^H\) are returned in the array VT;
  • lapack::Job::SomeVec: the first min(m,n) rows of \(V^H\) (the right singular vectors) are returned in the array VT;
  • lapack::Job::OverwriteVec: the first min(m,n) rows of \(V^H\) (the right singular vectors) are overwritten on the array A;
  • lapack::Job::NoVec: no rows of \(V^H\) (no right singular vectors) are computed.
    jobvt and jobu cannot both be OverwriteVec.
[in]mThe number of rows of the input matrix A. m >= 0.
[in]nThe number of columns of the input matrix A. n >= 0.
[in,out]AThe m-by-n matrix A, stored in an lda-by-n array. On entry, the m-by-n matrix A. On exit:
  • If jobu = OverwriteVec, A is overwritten with the first min(m,n) columns of U (the left singular vectors, stored columnwise);
  • if jobvt = OverwriteVec, A is overwritten with the first min(m,n) rows of \(V^H\) (the right singular vectors, stored rowwise);
  • if jobu != OverwriteVec and jobvt != OverwriteVec, the contents of A are destroyed.
[in]ldaThe leading dimension of the array A. lda >= max(1,m).
[out]SThe vector S of length min(m,n). The singular values of A, sorted so that S(i) >= S(i+1).
[out]UThe m-by-ucol matrix U, stored in an ldu-by-ucol array.
  • If jobu = AllVec, ucol = m and U contains the m-by-m unitary matrix U;
  • if jobu = SomeVec, ucol = min(m,n) and U contains the first min(m,n) columns of U (the left singular vectors, stored columnwise);
  • if jobu = NoVec or OverwriteVec, U is not referenced.
[in]lduThe leading dimension of the array U. ldu >= 1; if jobu = SomeVec or AllVec, ldu >= m.
[out]VTThe vrow-by-n matrix VT, stored in an ldvt-by-n array.
  • If jobvt = AllVec, vrow = n and VT contains the n-by-n unitary matrix \(V^H\);
  • if jobvt = SomeVec, VT contains the first min(m,n) rows of \(V^H\) (the right singular vectors, stored rowwise);
  • if jobvt = NoVec or OverwriteVec, VT is not referenced.
[in]ldvtThe leading dimension of the array VT. ldvt >= 1;
  • if jobvt = AllVec, ldvt >= n;
  • if jobvt = SomeVec, ldvt >= min(m,n).
Returns
= 0: successful exit.
> 0: lapack::bdsqr did not converge; return value specifies how many superdiagonals of the intermediate bidiagonal form B did not converge to zero.

◆ gesvdx()

int64_t lapack::gesvdx ( lapack::Job  jobu,
lapack::Job  jobvt,
lapack::Range  range,
int64_t  m,
int64_t  n,
std::complex< double > *  A,
int64_t  lda,
double  vl,
double  vu,
int64_t  il,
int64_t  iu,
int64_t *  nfound,
double *  S,
std::complex< double > *  U,
int64_t  ldu,
std::complex< double > *  VT,
int64_t  ldvt 
)

Computes the singular value decomposition (SVD) of a m-by-n matrix A, optionally computing the left and/or right singular vectors.

The SVD is written

\[ A = U \Sigma V^H, \]

where \(\Sigma\) is an m-by-n matrix which is zero except for its min(m,n) diagonal elements, U is an m-by-m unitary matrix, and V is an n-by-n unitary matrix. The diagonal elements of SIGMA are the singular values of A; they are real and non-negative, and are returned in descending order. The first min(m,n) columns of U and V are the left and right singular vectors of A.

gesvdx uses an eigenvalue problem for obtaining the SVD, which allows for the computation of a subset of singular values and vectors. See lapack::bdsvdx for details.

Note that the routine returns VT = \(V^H\), not V.

Overloaded versions are available for float, double, std::complex<float>, and std::complex<double>.

Parameters
[in]jobuSpecifies options for computing all or part of the matrix U:
  • lapack::Job::Vec: the first min(m,n) columns of U (the left singular vectors) or as specified by range are returned in the array U;
  • lapack::Job::NoVec: no columns of U (no left singular vectors) are computed.
[in]jobvtSpecifies options for computing all or part of the matrix \(V^H\):
  • lapack::Job::Vec: the first min(m,n) rows of \(V^H\) (the right singular vectors) or as specified by range are returned in the array VT;
  • lapack::Job::NoVec: no rows of \(V^H\) (no right singular vectors) are computed.
[in]range
  • lapack::Range::All: all singular values will be found.
  • lapack::Range::Value: all singular values in the half-open interval (vl,vu] will be found.
  • lapack::Range::Index: the il-th through iu-th singular values will be found.
[in]mThe number of rows of the input matrix A. m >= 0.
[in]nThe number of columns of the input matrix A. n >= 0.
[in,out]AThe m-by-n matrix A, stored in an lda-by-n array. On entry, the m-by-n matrix A. On exit, the contents of A are destroyed.
[in]ldaThe leading dimension of the array A. lda >= max(1,m).
[in]vlIf range=Value, the lower bound of the interval to be searched for singular values. vu > vl. Not referenced if range = All or Index.
[in]vuIf range=Value, the upper bound of the interval to be searched for singular values. vu > vl. Not referenced if range = All or Index.
[in]ilIf range=Index, the index of the smallest singular value to be returned. 1 <= il <= iu <= min(m,n), if min(m,n) > 0. Not referenced if range = All or Value.
[in]iuIf range=Index, the index of the largest singular value to be returned. 1 <= il <= iu <= min(m,n), if min(m,n) > 0. Not referenced if range = All or Value.
[out]nfoundThe total number of singular values found, 0 <= nfound <= min(m,n).
  • If range = All, nfound = min(m,n);
  • if range = Index, nfound = iu-il+1.
[out]SThe vector S of length min(m,n). The singular values of A, sorted so that S(i) >= S(i+1).
[out]UThe m-by-nfound matrix U, stored in an ldu-by-ucol array.
  • If jobu = Vec, U contains columns of U (the left singular vectors, stored columnwise) as specified by range;
  • if jobu = NoVec, U is not referenced.
    Note: The user must ensure that ucol >= nfound; if range = Value, the exact value of nfound is not known in advance and an upper bound must be used.
[in]lduThe leading dimension of the array U. ldu >= 1; if jobu = Vec, ldu >= m.
[out]VTThe nfound-by-n matrix VT, stored in an ldvt-by-n array.
  • If jobvt = Vec, VT contains the rows of \(V^H\) (the right singular vectors, stored rowwise) as specified by range;
  • if jobvt = NoVec, VT is not referenced.
    Note: The user must ensure that ldvt >= nfound; if range = Value, the exact value of nfound is not known in advance and an upper bound must be used.
[in]ldvtThe leading dimension of the array VT. ldvt >= 1; if jobvt = Vec, ldvt >= nfound.
Returns
= 0: successful exit
> 0 and <= n: if return value = i, then i eigenvectors failed to converge in lapack::bdsvdx/lapack::stevx.
> n: if return value = 2*n + 1, an internal error occurred in lapack::bdsvdx