LAPACK++
LAPACK C++ API
General matrix: LU: banded

Functions

int64_t lapack::gbsv (int64_t n, int64_t kl, int64_t ku, int64_t nrhs, double *AB, int64_t ldab, int64_t *ipiv, double *B, int64_t ldb)
 
int64_t lapack::gbsv (int64_t n, int64_t kl, int64_t ku, int64_t nrhs, float *AB, int64_t ldab, int64_t *ipiv, float *B, int64_t ldb)
 
int64_t lapack::gbsv (int64_t n, int64_t kl, int64_t ku, int64_t nrhs, std::complex< double > *AB, int64_t ldab, 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 a band matrix of order n with kl subdiagonals and ku superdiagonals, and X and B are n-by-nrhs matrices. More...
 
int64_t lapack::gbsv (int64_t n, int64_t kl, int64_t ku, int64_t nrhs, std::complex< float > *AB, int64_t ldab, int64_t *ipiv, std::complex< float > *B, int64_t ldb)
 
int64_t lapack::gbsvx (lapack::Factored fact, lapack::Op trans, int64_t n, int64_t kl, int64_t ku, int64_t nrhs, double *AB, int64_t ldab, double *AFB, int64_t ldafb, int64_t *ipiv, lapack::Equed *equed, double *R, double *C, double *B, int64_t ldb, double *X, int64_t ldx, double *rcond, double *ferr, double *berr)
 
int64_t lapack::gbsvx (lapack::Factored fact, lapack::Op trans, int64_t n, int64_t kl, int64_t ku, int64_t nrhs, float *AB, int64_t ldab, float *AFB, int64_t ldafb, int64_t *ipiv, lapack::Equed *equed, float *R, float *C, float *B, int64_t ldb, float *X, int64_t ldx, float *rcond, float *ferr, float *berr)
 
int64_t lapack::gbsvx (lapack::Factored fact, lapack::Op trans, int64_t n, int64_t kl, int64_t ku, int64_t nrhs, std::complex< double > *AB, int64_t ldab, std::complex< double > *AFB, int64_t ldafb, int64_t *ipiv, lapack::Equed *equed, double *R, double *C, std::complex< double > *B, int64_t ldb, std::complex< double > *X, int64_t ldx, double *rcond, double *ferr, double *berr)
 Uses the LU factorization to compute the solution to a system of linear equations. More...
 
int64_t lapack::gbsvx (lapack::Factored fact, lapack::Op trans, int64_t n, int64_t kl, int64_t ku, int64_t nrhs, std::complex< float > *AB, int64_t ldab, std::complex< float > *AFB, int64_t ldafb, int64_t *ipiv, lapack::Equed *equed, float *R, float *C, std::complex< float > *B, int64_t ldb, std::complex< float > *X, int64_t ldx, float *rcond, float *ferr, float *berr)
 

Detailed Description

Function Documentation

◆ gbsv()

int64_t lapack::gbsv ( int64_t  n,
int64_t  kl,
int64_t  ku,
int64_t  nrhs,
std::complex< double > *  AB,
int64_t  ldab,
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 a band matrix of order n with kl subdiagonals and ku superdiagonals, and X and B are n-by-nrhs matrices.

The LU decomposition with partial pivoting and row interchanges is used to factor A as \(A = L U\), where L is a product of permutation and unit lower triangular matrices with kl subdiagonals, and U is upper triangular with kl+ku superdiagonals. 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]nThe number of linear equations, i.e., the order of the matrix A. n >= 0.
[in]klThe number of subdiagonals within the band of A. kl >= 0.
[in]kuThe number of superdiagonals within the band of A. ku >= 0.
[in]nrhsThe number of right hand sides, i.e., the number of columns of the matrix B. nrhs >= 0.
[in,out]ABThe n-by-n band matrix AB, stored in an ldab-by-n array. On entry, the matrix A in band storage, in rows kl+1 to 2*kl+ku+1; rows 1 to kl of the array need not be set. The j-th column of A is stored in the j-th column of the array AB as follows:
AB(kl+ku+1+i-j,j) = A(i,j) for max(1,j-ku) <= i <= min(n,j+kl)
On exit, details of the factorization: U is stored as an upper triangular band matrix with kl+ku superdiagonals in rows 1 to kl+ku+1, and the multipliers used during the factorization are stored in rows kl+ku+2 to 2*kl+ku+1. See below for further details.
[in]ldabThe leading dimension of the array AB. ldab >= 2*kl+ku+1.
[out]ipivThe vector ipiv of length n. The pivot indices that define the permutation matrix P; row i of the matrix was interchanged with row ipiv(i).
[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, U(i,i) is exactly zero. The factorization has been completed, but the factor U is exactly singular, and the solution has not been computed.
Further Details

The band storage scheme is illustrated by the following example, when n = 6, kl = 2, ku = 1:

On entry:                        On exit:

 *    *    *    +    +    +       *    *    *   u14  u25  u36
 *    *    +    +    +    +       *    *   u13  u24  u35  u46
 *   a12  a23  a34  a45  a56      *   u12  u23  u34  u45  u56
a11  a22  a33  a44  a55  a66     u11  u22  u33  u44  u55  u66
a21  a32  a43  a54  a65   *      m21  m32  m43  m54  m65   *
a31  a42  a53  a64   *    *      m31  m42  m53  m64   *    *

Array elements marked * are not used by the routine; elements marked

  • need not be set on entry, but are required by the routine to store elements of U because of fill-in resulting from the row interchanges.

◆ gbsvx()

int64_t lapack::gbsvx ( lapack::Factored  fact,
lapack::Op  trans,
int64_t  n,
int64_t  kl,
int64_t  ku,
int64_t  nrhs,
std::complex< double > *  AB,
int64_t  ldab,
std::complex< double > *  AFB,
int64_t  ldafb,
int64_t *  ipiv,
lapack::Equed *  equed,
double *  R,
double *  C,
std::complex< double > *  B,
int64_t  ldb,
std::complex< double > *  X,
int64_t  ldx,
double *  rcond,
double *  ferr,
double *  berr 
)

Uses the LU factorization to compute the solution to a system of linear equations.

\[ A X = B, \]

\[ A^T X = B, \]

or

\[ A^H X = B, \]

where A is a band matrix of order n with kl subdiagonals and ku superdiagonals, 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>.

Parameters
[in]factWhether or not the factored form of the matrix A is supplied on entry, and if not, whether the matrix A should be equilibrated before it is factored.
  • lapack::Factored::Factored: On entry, AFB and ipiv contain the factored form of A. If equed != None, the matrix A has been equilibrated with scaling factors given by R and C. AB, AFB, and ipiv are not modified.
  • lapack::Factored::NotFactored: The matrix A will be copied to AFB and factored.
  • lapack::Factored::Equilibrate: The matrix A will be equilibrated if necessary, then copied to AFB and factored.
[in]transThe form of the system of equations:
  • lapack::Op::NoTrans: \(A X = B\) (No transpose)
  • lapack::Op::Trans: \(A^T X = B\) (Transpose)
  • lapack::Op::ConjTrans: \(A^H X = B\) (Conjugate transpose)
[in]nThe number of linear equations, i.e., the order of the matrix A. n >= 0.
[in]klThe number of subdiagonals within the band of A. kl >= 0.
[in]kuThe number of superdiagonals within the band of A. ku >= 0.
[in]nrhsThe number of right hand sides, i.e., the number of columns of the matrices B and X. nrhs >= 0.
[in,out]ABThe kl+ku+1-by-n matrix AB, stored in an ldab-by-n array. On entry, the matrix A in band storage, in rows 1 to kl+ku+1. The j-th column of A is stored in the j-th column of the array AB as follows:
AB(ku+1+i-j,j) = A(i,j) for max(1,j-ku) <= i <= min(n,j+kl)
  • If fact = Factored and equed != None, then A must have been equilibrated by the scaling factors in R and/or C.
  • AB is not modified if fact = Factored or NotFactored, or if fact = Equilibrate and equed = None on exit.
  • On exit, if equed != None, A is scaled as follows:
    • equed = Row: \(A := \text{diag}(R) \; A\)
    • equed = Col: \(A := A \; \text{diag}(C)\)
    • equed = Both: \(A := \text{diag}(R) \; A \; \text{diag}(C).\)
[in]ldabThe leading dimension of the array AB. ldab >= kl+ku+1.
[in,out]AFBThe 2*kl+ku+1-by-n matrix AFB, stored in an ldafb-by-n array.
  • If fact = Factored, then AFB is an input argument and on entry contains details of the LU factorization of the band matrix A, as computed by lapack::gbtrf. U is stored as an upper triangular band matrix with kl+ku superdiagonals in rows 1 to kl+ku+1, and the multipliers used during the factorization are stored in rows kl+ku+2 to 2*kl+ku+1.
  • If equed != None, then AFB is the factored form of the equilibrated matrix A.
  • If fact = NotFactored, then AFB is an output argument and on exit returns details of the LU factorization of A.
  • If fact = Equilibrate, then AFB is an output argument and on exit returns details of the LU factorization of the equilibrated matrix A (see the description of AB for the form of the equilibrated matrix).
[in]ldafbThe leading dimension of the array AFB. ldafb >= 2*kl+ku+1.
[in,out]ipivThe vector ipiv of length n.
  • If fact = Factored, then ipiv is an input argument and on entry contains the pivot indices from the factorization \(A = P L U\) as computed by lapack::gbtrf; row i of the matrix was interchanged with row ipiv(i).
  • If fact = NotFactored, then ipiv is an output argument and on exit contains the pivot indices from the factorization \(A = P L U\) of the original matrix A.
  • If fact = Equilibrate, then ipiv is an output argument and on exit contains the pivot indices from the factorization \(A = P L U\) of the equilibrated matrix A.
[in,out]equedThe form of equilibration that was done:
  • lapack::Equed::None: No equilibration (always true if fact = NotFactored).
  • lapack::Equed::Row: Row equilibration, i.e., A has been premultiplied by diag(R).
  • lapack::Equed::Col: Column equilibration, i.e., A has been postmultiplied by diag(C).
  • lapack::Equed::Both: Both row and column equilibration, i.e., A has been replaced by \(\text{diag}(R) \; A \; \text{diag}(C).\)
    equed is an input argument if fact = Factored; otherwise, it is an output argument.
[in,out]RThe vector R of length n. The row scale factors for A.
  • If equed = Row or Both, A is multiplied on the left by diag(R);
  • if equed = None or Col, R is not accessed.
  • If fact = Factored, R is an input argument;
  • otherwise, R is an output argument.
  • If fact = Factored and equed = Row or Both, each element of R must be positive.
[in,out]CThe vector C of length n. The column scale factors for A.
  • If equed = Col or Both, A is multiplied on the right by diag(C);
  • if equed = None or Row, C is not accessed.
  • If fact = Factored, C is an input argument;
  • otherwise, C is an output argument.
  • If fact = Factored and equed = Col or Both, each element of C must be positive.
[in,out]BThe n-by-nrhs matrix B, stored in an ldb-by-nrhs array. On entry, the right hand side matrix B. On exit,
  • if equed = None, B is not modified;
  • if trans = NoTrans and equed = Row or Both, B is overwritten by \(\text{diag}(R) \; B;\)
  • if trans = Trans or ConjTrans and equed = Col or Both, B is overwritten by \(\text{diag}(C) \; 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 to the original system of equations. Note that A and B are modified on exit if equed != None, and the solution to the equilibrated system is \(\text{diag}(C)^{-1} X\) if trans = NoTrans and equed = Col or Both, or \(\text{diag}(R)^{-1} X\) if trans = Trans or ConjTrans and equed = Row or Both.
[in]ldxThe leading dimension of the array X. ldx >= max(1,n).
[out]rcondThe estimate of the reciprocal condition number of the matrix A after equilibration (if done). 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 code of 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, then U(i,i) is exactly zero. The factorization has been completed, but the factor U is exactly singular, so the solution and error bounds could not be computed. rcond = 0 is returned.
= n+1: U 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.