naginterfaces.library.lapacklin.dppsvx

naginterfaces.library.lapacklin.dppsvx(fact, uplo, n, nrhs, ap, afp, equed, s, b)[source]

dppsvx uses the Cholesky factorization

to compute the solution to a real system of linear equations

where is an symmetric positive definite matrix stored in packed format 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 f07gb

https://www.nag.com/numeric/nl/nagdoc_27.3/flhtml/f07/f07gbf.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 .

nrhsint

, the number of right-hand sides, i.e., the number of columns of the matrix .

apfloat, array-like, shape

If and , must contain the equilibrated matrix ; otherwise, must contain the symmetric matrix , packed by columns.

afpfloat, array-like, shape

If , contains the triangular factor or from the Cholesky factorization or , 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.

bfloat, array-like, shape

The right-hand side matrix .

Returns
apfloat, ndarray, shape

If or , or if and , is not modified.

If and , is overwritten by .

afpfloat, ndarray, shape

If or if and , returns the triangular factor or from the Cholesky factorization or of the original matrix .

If and , 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.

bfloat, ndarray, shape

If , is not modified.

If , is overwritten by .

xfloat, 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: 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

dppsvx performs the following steps:

  1. 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 .

  2. 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.

  3. 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.

  4. The system of equations is solved for using the factored form of .

  5. Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for it.

  6. 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