LAPACK++  2022.07.00
LAPACK C++ API
Hermitian indefinite

Functions

int64_t lapack::hesv (lapack::Uplo uplo, int64_t n, int64_t nrhs, std::complex< double > *A, int64_t lda, int64_t *ipiv, std::complex< double > *B, int64_t ldb)
 Computes the solution to a system of linear equations \(A X = B\), where A is an n-by-n Hermitian matrix and X and B are n-by-nrhs matrices. More...
 
int64_t lapack::hesv (lapack::Uplo uplo, int64_t n, int64_t nrhs, std::complex< float > *A, int64_t lda, int64_t *ipiv, std::complex< float > *B, int64_t ldb)
 
int64_t lapack::hesv_aa (lapack::Uplo uplo, int64_t n, int64_t nrhs, std::complex< double > *A, int64_t lda, int64_t *ipiv, std::complex< double > *B, int64_t ldb)
 Computes the solution to a system of linear equations \(A X = B\), where A is an n-by-n Hermitian matrix and X and B are n-by-nrhs matrices. More...
 
int64_t lapack::hesv_aa (lapack::Uplo uplo, int64_t n, int64_t nrhs, std::complex< float > *A, int64_t lda, int64_t *ipiv, std::complex< float > *B, int64_t ldb)
 
int64_t lapack::hesv_rk (lapack::Uplo uplo, int64_t n, int64_t nrhs, std::complex< double > *A, int64_t lda, std::complex< double > *E, int64_t *ipiv, std::complex< double > *B, int64_t ldb)
 Computes the solution to a system of linear equations. More...
 
int64_t lapack::hesv_rk (lapack::Uplo uplo, int64_t n, int64_t nrhs, std::complex< float > *A, int64_t lda, std::complex< float > *E, int64_t *ipiv, std::complex< float > *B, int64_t ldb)
 
int64_t lapack::hesv_rook (lapack::Uplo uplo, int64_t n, int64_t nrhs, std::complex< double > *A, int64_t lda, int64_t *ipiv, std::complex< double > *B, int64_t ldb)
 
int64_t lapack::hesv_rook (lapack::Uplo uplo, int64_t n, int64_t nrhs, std::complex< float > *A, int64_t lda, int64_t *ipiv, std::complex< float > *B, int64_t ldb)
 
int64_t lapack::hesvx (lapack::Factored fact, lapack::Uplo uplo, int64_t n, int64_t nrhs, std::complex< double > const *A, int64_t lda, std::complex< double > *AF, int64_t ldaf, int64_t *ipiv, std::complex< double > const *B, int64_t ldb, std::complex< double > *X, int64_t ldx, double *rcond, double *ferr, double *berr)
 Uses the diagonal pivoting factorization to compute the solution to a system of linear equations \(A X = B\), where A is an n-by-n Hermitian matrix and X and B are n-by-nrhs matrices. More...
 
int64_t lapack::hesvx (lapack::Factored fact, lapack::Uplo uplo, int64_t n, int64_t nrhs, std::complex< float > const *A, int64_t lda, std::complex< float > *AF, int64_t ldaf, int64_t *ipiv, std::complex< float > const *B, int64_t ldb, std::complex< float > *X, int64_t ldx, float *rcond, float *ferr, float *berr)
 

Detailed Description

Function Documentation

◆ hesv()

int64_t lapack::hesv ( lapack::Uplo  uplo,
int64_t  n,
int64_t  nrhs,
std::complex< double > *  A,
int64_t  lda,
int64_t *  ipiv,
std::complex< double > *  B,
int64_t  ldb 
)

Computes the solution to a system of linear equations \(A X = B\), where A is an n-by-n Hermitian matrix and X and B are n-by-nrhs matrices.

The diagonal pivoting method is used to factor A as \(A = U D U^H\) if uplo = Upper, or \(A = L D L^H\) if uplo = Lower, where U (or L) is a product of permutation and unit upper (lower) triangular matrices, and D is Hermitian and block diagonal with 1-by-1 and 2-by-2 diagonal blocks. The factored form of A is then used to solve the system of equations \(A X = B\).

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

Parameters
[in]uplo
  • lapack::Uplo::Upper: Upper triangle of A is stored;
  • lapack::Uplo::Lower: Lower triangle of A is stored.
[in]nThe number of linear equations, i.e., the order of the matrix A. n >= 0.
[in]nrhsThe number of right hand sides, i.e., the number of columns of the matrix B. nrhs >= 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 successful exit, the block diagonal matrix D and the multipliers used to obtain the factor U or L from the factorization \(A = U D U^H\) or \(A = L D L^H\) as computed by lapack::hetrf.
[in]ldaThe leading dimension of the array A. lda >= max(1,n).
[out]ipivThe vector ipiv of length n. Details of the interchanges and the block structure of D, as determined by lapack::hetrf. If ipiv(k) > 0, then rows and columns k and ipiv(k) were interchanged, and D(k,k) is a 1-by-1 diagonal block.
  • If uplo = Upper and ipiv(k) = ipiv(k-1) < 0, then rows and columns k-1 and -ipiv(k) were interchanged and D(k-1:k,k-1:k) is a 2-by-2 diagonal block.
  • If uplo = Lower and ipiv(k) = ipiv(k+1) < 0, then rows and columns k+1 and -ipiv(k) were interchanged and D(k:k+1,k:k+1) is a 2-by-2 diagonal block.
[in,out]BThe n-by-nrhs matrix B, stored in an ldb-by-nrhs array. On entry, the n-by-nrhs right hand side matrix B. On successful exit, the n-by-nrhs solution matrix X.
[in]ldbThe leading dimension of the array B. ldb >= max(1,n).
Returns
= 0: successful exit
> 0: if return value = i, D(i,i) is exactly zero. The factorization has been completed, but the block diagonal matrix D is exactly singular, so the solution could not be computed.

◆ hesv_aa()

int64_t lapack::hesv_aa ( lapack::Uplo  uplo,
int64_t  n,
int64_t  nrhs,
std::complex< double > *  A,
int64_t  lda,
int64_t *  ipiv,
std::complex< double > *  B,
int64_t  ldb 
)

Computes the solution to a system of linear equations \(A X = B\), where A is an n-by-n Hermitian matrix and X and B are n-by-nrhs matrices.

Aasen's algorithm is used to factor A as \(A = U T U^H\) if uplo = Upper, or \(A = L T L^H\) if uplo = Lower, where U (or L) is a product of permutation and unit upper (lower) triangular matrices, and T is Hermitian tridiagonal. The factored form of A is then used to solve the system of equations \(A X = B\).

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

Parameters
[in]uplo
  • lapack::Uplo::Upper: Upper triangle of A is stored;
  • lapack::Uplo::Lower: Lower triangle of A is stored.
[in]nThe number of linear equations, i.e., the order of the matrix A. n >= 0.
[in]nrhsThe number of right hand sides, i.e., the number of columns of the matrix B. nrhs >= 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 successful exit, the tridiagonal matrix T and the multipliers used to obtain the factor U or L from the factorization \(A = U T U^H\) or \(A = L T L^H\) as computed by lapack::hetrf_aa.
[in]ldaThe leading dimension of the array A. lda >= max(1,n).
[out]ipivThe vector ipiv of length n. On exit, it contains the details of the interchanges, i.e., the row and column k of A were interchanged with the row and column ipiv(k).
[in,out]BThe n-by-nrhs matrix B, stored in an ldb-by-nrhs array. On entry, the n-by-nrhs right hand side matrix B. On successful exit, the n-by-nrhs solution matrix X.
[in]ldbThe leading dimension of the array B. ldb >= max(1,n).
Returns
= 0: successful exit
> 0: if return value = i, D(i,i) is exactly zero. The factorization has been completed, but the block diagonal matrix D is exactly singular, so the solution could not be computed.

◆ hesv_rk()

int64_t lapack::hesv_rk ( lapack::Uplo  uplo,
int64_t  n,
int64_t  nrhs,
std::complex< double > *  A,
int64_t  lda,
std::complex< double > *  E,
int64_t *  ipiv,
std::complex< double > *  B,
int64_t  ldb 
)

Computes the solution to a system of linear equations.

\[ A X = B, \]

where A is an n-by-n Hermitian matrix and X and B are n-by-nrhs matrices.

The bounded Bunch-Kaufman (rook) diagonal pivoting method is used to factor A as \(A = P U D U^H P^T,\) if uplo = Upper, or \(A = P L D L^H P^T,\) if uplo = Lower, where U (or L) is unit upper (or lower) triangular matrix, \(U^H\) (or \(L^H\)) is the conjugate of U (or L), P is a permutation matrix, \(P^T\) is the transpose of P, and D is Hermitian and block diagonal with 1-by-1 and 2-by-2 diagonal blocks.

lapack::hetrf_rk is called to compute the factorization of a Hermitian matrix. The factored form of A is then used to solve the system of equations \(A X = B\) by calling lapack::hetrs_rk.

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

Parameters
[in]uploWhether the upper or lower triangular part of the Hermitian matrix A is stored:
  • lapack::Uplo::Upper: Upper triangle of A is stored;
  • lapack::Uplo::Lower: Lower triangle of A is stored.
[in]nThe number of linear equations, i.e., the order of the matrix A. n >= 0.
[in]nrhsThe number of right hand sides, i.e., the number of columns of the matrix B. nrhs >= 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 successful exit, diagonal of the block diagonal matrix D and factors U or L as computed by lapack::hetrf_rk:
    • ONLY diagonal elements of the Hermitian block diagonal matrix D on the diagonal of A, i.e. D(k,k) = A(k,k); (superdiagonal (or subdiagonal) elements of D are stored on exit in array E), and
    • If uplo = Upper: factor U in the superdiagonal part of A.
    • If uplo = Lower: factor L in the subdiagonal part of A.
  • For more info see the description of lapack::hetrf_rk.
[in]ldaThe leading dimension of the array A. lda >= max(1,n).
[out]EThe vector E of length n. On exit, contains the output computed by the factorization routine lapack::hetrf_rk, i.e. the superdiagonal (or subdiagonal) elements of the Hermitian block diagonal matrix D with 1-by-1 or 2-by-2 diagonal blocks, where
  • If uplo = Upper: E(i) = D(i-1,i), i=2:n, E(1) is set to 0;
  • If uplo = Lower: E(i) = D(i+1,i), i=1:n-1, E(n) is set to 0.
  • Note: For 1-by-1 diagonal block D(k), where 1 <= k <= n, the element E(k) is set to 0 in both uplo = Upper or uplo = Lower cases.
  • For more info see the description of lapack::hetrf_rk.
[out]ipivThe vector ipiv of length n. Details of the interchanges and the block structure of D, as determined by lapack::hetrf_rk. For more info see the description of lapack::hetrf_rk.
[in,out]BThe n-by-nrhs matrix B, stored in an ldb-by-nrhs array. On entry, the n-by-nrhs right hand side matrix B. On successful exit, the n-by-nrhs solution matrix X.
[in]ldbThe leading dimension of the array B. ldb >= max(1,n).
Returns
= 0: successful exit
> 0: If return value = k, the matrix A is singular, because: If uplo = Upper: column k in the upper triangular part of A contains all zeros. If uplo = Lower: column k in the lower triangular part of A contains all zeros.

Therefore D(k,k) is exactly zero, and superdiagonal elements of column k of U (or subdiagonal elements of column k of L ) are all zeros. The factorization has been completed, but the block diagonal matrix D is exactly singular, and division by zero will occur if it is used to solve a system of equations.

NOTE: info only stores the first occurrence of a singularity, any subsequent occurrence of singularity is not stored in info even though the factorization always completes.

◆ hesv_rook()

int64_t lapack::hesv_rook ( lapack::Uplo  uplo,
int64_t  n,
int64_t  nrhs,
std::complex< double > *  A,
int64_t  lda,
int64_t *  ipiv,
std::complex< double > *  B,
int64_t  ldb 
)
See also
lapack::hesv_rk.
Since
LAPACK 3.5.0.

◆ hesvx()

int64_t lapack::hesvx ( lapack::Factored  fact,
lapack::Uplo  uplo,
int64_t  n,
int64_t  nrhs,
std::complex< double > const *  A,
int64_t  lda,
std::complex< double > *  AF,
int64_t  ldaf,
int64_t *  ipiv,
std::complex< double > const *  B,
int64_t  ldb,
std::complex< double > *  X,
int64_t  ldx,
double *  rcond,
double *  ferr,
double *  berr 
)

Uses the diagonal pivoting factorization to compute the solution to a system of linear equations \(A X = B\), where A is an n-by-n Hermitian matrix and X and B are n-by-nrhs matrices.

Error bounds on the solution and a condition estimate are also provided.

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

Parameters
[in]factWhether or not the factored form of A has been supplied on entry.
  • lapack::Factored::Factored: On entry, AF and ipiv contain the factored form of A. A, AF and ipiv will not be modified.
  • lapack::Factored::NotFactored: The matrix A will be copied to AF and factored.
[in]uplo
  • lapack::Uplo::Upper: Upper triangle of A is stored;
  • lapack::Uplo::Lower: Lower triangle of A is stored.
[in]nThe number of linear equations, i.e., the order of the matrix A. n >= 0.
[in]nrhsThe number of right hand sides, i.e., the number of columns of the matrices B and X. nrhs >= 0.
[in]AThe n-by-n matrix A, stored in an lda-by-n array. 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.
[in]ldaThe leading dimension of the array A. lda >= max(1,n).
[in,out]AFThe n-by-n matrix AF, stored in an ldaf-by-n array.
  • If fact = Factored, then AF is an input argument and on entry contains the block diagonal matrix D and the multipliers used to obtain the factor U or L from the factorization \(A = U D U^H\) or \(A = L D L^H\) as computed by lapack::hetrf.
  • If fact = NotFactored, then AF is an output argument and on exit returns the block diagonal matrix D and the multipliers used to obtain the factor U or L from the factorization \(A = U D U^H\) or \(A = L D L^H\).
[in]ldafThe leading dimension of the array AF. ldaf >= max(1,n).
[in,out]ipivThe vector ipiv of length n.
  • If fact = Factored, then ipiv is an input argument and on entry contains details of the interchanges and the block structure of D, as determined by lapack::hetrf. If ipiv(k) > 0, then rows and columns k and ipiv(k) were interchanged and D(k,k) is a 1-by-1 diagonal block.
  • If uplo = Upper and ipiv(k) = ipiv(k-1) < 0, then rows and columns k-1 and -ipiv(k) were interchanged and D(k-1:k,k-1:k) is a 2-by-2 diagonal block.
  • If uplo = Lower and ipiv(k) = ipiv(k+1) < 0, then rows and columns k+1 and -ipiv(k) were interchanged and D(k:k+1,k:k+1) is a 2-by-2 diagonal block.
  • If fact = NotFactored, then ipiv is an output argument and on exit contains details of the interchanges and the block structure of D, as determined by lapack::hetrf.
[in]BThe n-by-nrhs matrix B, stored in an ldb-by-nrhs array. The n-by-nrhs right hand side matrix B.
[in]ldbThe leading dimension of the array B. ldb >= max(1,n).
[out]XThe n-by-nrhs matrix X, stored in an ldx-by-nrhs array. If successful or return value = n+1, the n-by-nrhs solution matrix X.
[in]ldxThe leading dimension of the array X. ldx >= max(1,n).
[out]rcondThe estimate of the reciprocal condition number of the matrix A. If rcond is less than the machine precision (in particular, if rcond = 0), the matrix is singular to working precision. This condition is indicated by a return value > 0.
[out]ferrThe vector ferr of length nrhs. The estimated forward error bound for each solution vector X(j) (the j-th column of the solution matrix X). If XTRUE is the true solution corresponding to X(j), ferr(j) is an estimated upper bound for the magnitude of the largest element in (X(j) - XTRUE) divided by the magnitude of the largest element in X(j). The estimate is as reliable as the estimate for rcond, and is almost always a slight overestimate of the true error.
[out]berrThe vector berr of length nrhs. The componentwise relative backward error of each solution vector X(j) (i.e., the smallest relative change in any element of A or B that makes X(j) an exact solution).
Returns
= 0: successful exit
> 0 and <= n: if return value = i, D(i,i) is exactly zero. The factorization has been completed but the factor D is exactly singular, so the solution and error bounds could not be computed. rcond = 0 is returned.
= n+1: D is nonsingular, but rcond is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of rcond would suggest.