naginterfaces.library.lapacklin.zpbsvx¶
- naginterfaces.library.lapacklin.zpbsvx(fact, uplo, n, kd, nrhs, ab, afb, equed, s, b)[source]¶
zpbsvx
uses the Cholesky factorizationto compute the solution to a complex system of linear equations
where is an Hermitian positive definite band matrix of bandwidth and and are matrices. Error bounds on the solution and a condition estimate are also provided.
For full information please refer to the NAG Library document for f07hp
https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07hpf.html
- Parameters
- factstr, length 1
Specifies whether or not the factorized form of the matrix is supplied on entry, and if not, whether the matrix should be equilibrated before it is factorized.
contains the factorized form of . If , the matrix has been equilibrated with scaling factors given by . and will not be modified.
The matrix will be copied to and factorized.
The matrix will be equilibrated if necessary, then copied to and factorized.
- uplostr, length 1
If , the upper triangle of is stored.
If , the lower triangle of is stored.
- nint
, the number of linear equations, i.e., the order of the matrix .
- kdint
, the number of superdiagonals of the matrix if , or the number of subdiagonals if .
- nrhsint
, the number of right-hand sides, i.e., the number of columns of the matrix .
- abcomplex, array-like, shape
The upper or lower triangle of the Hermitian band matrix , except if and , in which case must contain the equilibrated matrix .
- afbcomplex, array-like, shape
If , contains the triangular factor or from the Cholesky factorization or of the band matrix , in the same storage format as . If , is the factorized form of the equilibrated matrix .
- equedstr, length 1
If or , need not be set.
If , must specify the form of the equilibration that was performed as follows:
if , no equilibration;
if , equilibration was performed, i.e., has been replaced by .
- sfloat, array-like, shape
If or , need not be set.
If and , must contain the scale factors, , for ; each element of must be positive.
- bcomplex, array-like, shape
The right-hand side matrix .
- Returns
- abcomplex, ndarray, shape
If and , is overwritten by .
- afbcomplex, ndarray, shape
If , returns the triangular factor or from the Cholesky factorization or .
If , returns the triangular factor or from the Cholesky factorization or of the equilibrated matrix (see the description of for the form of the equilibrated matrix).
- equedstr, length 1
If , is unchanged from entry.
Otherwise, if no constraints are violated, specifies the form of the equilibration that was performed as specified above.
- sfloat, ndarray, shape
If , is unchanged from entry.
Otherwise, if no constraints are violated and , contains the scale factors, , for ; each element of is positive.
- bcomplex, ndarray, shape
If , is not modified.
If , is overwritten by .
- xcomplex, ndarray, shape
If the function exits successfully or = + 1, the solution matrix to the original system of equations. Note that the arrays and are modified on exit if , and the solution to the equilibrated system is .
- rcondfloat
If no constraints are violated, an estimate of the reciprocal condition number of the matrix (after equilibration if that is performed), computed as .
- ferrfloat, ndarray, shape
If the function exits successfully or = + 1, an estimate of the forward error bound for each computed solution vector, such that where is the th column of the computed solution returned in the array and is the corresponding column of the exact solution . The estimate is as reliable as the estimate for , and is almost always a slight overestimate of the true error.
- berrfloat, ndarray, shape
If the function exits successfully or = + 1, an estimate of the component-wise relative backward error of each computed solution vector (i.e., the smallest relative change in any element of or that makes an exact solution).
- Raises
- NagValueError
- (errno )
On entry, error in parameter .
Constraint: , or .
- (errno )
On entry, error in parameter .
Constraint: or .
- (errno )
On entry, error in parameter .
Constraint: .
- (errno )
On entry, error in parameter .
Constraint: .
- (errno )
On entry, error in parameter .
Constraint: .
- (errno )
On entry, error in parameter .
Constraint: or .
- (errno )
On entry, error in parameter .
- (errno )
The leading minor of order of is not positive definite, so the factorization could not be completed, and the solution has not been computed. is returned.
- Warns
- NagAlgorithmicWarning
- (errno )
(or ) is nonsingular, but 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 would suggest.
- Notes
zpbsvx
performs the following steps:If , real diagonal scaling factors, , are computed to equilibrate the system:
Whether or not the system will be equilibrated depends on the scaling of the matrix , but if equilibration is used, is overwritten by and .
If or , the Cholesky decomposition is used to factor the matrix (after equilibration if ) as if or if , where is an upper triangular matrix and is a lower triangular matrix.
If the leading principal minor of is not positive definite, then the function returns with . Otherwise, the factored form of is used to estimate the condition number of the matrix . If the reciprocal of the condition number is less than machine precision, = + 1 is returned as a warning, but the function still goes on to solve for and compute error bounds as described below.
The system of equations is solved for using the factored form of .
Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for it.
If equilibration was used, the matrix is premultiplied by so that it solves the original system before equilibration.
- References
Anderson, E, Bai, Z, Bischof, C, Blackford, S, Demmel, J, Dongarra, J J, Du Croz, J J, Greenbaum, A, Hammarling, S, McKenney, A and Sorensen, D, 1999, LAPACK Users’ Guide, (3rd Edition), SIAM, Philadelphia, https://www.netlib.org/lapack/lug
Golub, G H and Van Loan, C F, 1996, Matrix Computations, (3rd Edition), Johns Hopkins University Press, Baltimore
Higham, N J, 2002, Accuracy and Stability of Numerical Algorithms, (2nd Edition), SIAM, Philadelphia