naginterfaces.library.sparse.direct_real_gen_lu¶

naginterfaces.library.sparse.direct_real_gen_lu(irowix, a, iprm, thresh, nzlmx, nzlumx, nzumx)[source]¶

direct_real_gen_lu computes the $L U$ factorization of a real sparse matrix in compressed column (Harwell–Boeing), column-permuted format.

For full information please refer to the NAG Library document for f11me

https://support.nag.com/numeric/nl/nagdoc_30/flhtml/f11/f11mef.html

Parameters

irowixint, array-like, shape $(:)$

The row index array of sparse matrix $A$ . See the F11 Introduction.

afloat, array-like, shape $(:)$

The array of nonzero values in the sparse matrix $A$ .

iprmint, array-like, shape $(7 \times n)$

Contains the column permutation which defines the permutation $P_{c}$ and associated data structures as computed by function direct_real_gen_setup().

threshfloat

The diagonal pivoting threshold, $t$ . At step $j$ of the Gaussian elimination, if $∣ ∣ A_{j j} ∣ ∣ \geq t ({max}_{i \geq j} ∣ ∣ A_{i j} ∣ ∣)$ , use $A_{j j}$ as a pivot, otherwise use ${max}_{i \geq j} ∣ ∣ A_{i j} ∣ ∣$ . A value of $t = 1$ corresponds to partial pivoting, a value of $t = 0$ corresponds to always choosing the pivot on the diagonal (unless it is zero).

Suggested value: $t h r e s h = 1.0$ . Smaller values may result in a faster factorization, but the benefits are likely to be small in most cases. It might be possible to use $t h r e s h = 0.0$ if you are confident about the stability of the factorization, for example, if $A$ is diagonally dominant.

nzlmxint

Indicates the available size of array $i l$ . The dimension of $i l$ should be at least $7 \times n + n z l m x + 4$ . A good range for $n z l m x$ that works for many problems is $nnz$ to $8 \times nnz$ , where $nnz$ is the number of nonzeros in the sparse matrix $A$ . If, on exit, $e r r n o$ = 2, the given $n z l m x$ was too small and you should attempt to provide more storage and call the function again.

nzlumxint

Indicates the available size of array $l v a l$ . The dimension of $l v a l$ should be at least $n z l u m x$ .

nzumxint

Indicates the available sizes of arrays $i u$ and $u v a l$ . The dimension of $i u$ should be at least $2 \times n + n z u m x + 1$ and the dimension of $u v a l$ should be at least $n z u m x$ . A good range for $n z u m x$ that works for many problems is $nnz$ to $8 \times nnz$ , where $nnz$ is the number of nonzeros in the sparse matrix $A$ . If, on exit, $e r r n o$ = 3, the given $n z u m x$ was too small and you should attempt to provide more storage and call the function again.

Returns

iprmint, ndarray, shape $(7 \times n)$: Part of the array is modified to record the row permutation $P_{r}$ determined by pivoting.
nzlumxint: If $e r r n o$ = 4, the given $n z l u m x$ was too small and is reset to a value that will be sufficient. You should then provide the indicated storage and call the function again.
ilint, ndarray, shape $(7 \times n + n z l m x + 4)$: Encapsulates the sparsity pattern of matrix $L$ .
lvalfloat, ndarray, shape $(n z l u m x)$: Records the nonzero values of matrix $L$ and some of the nonzero values of matrix $U$ .
iuint, ndarray, shape $(2 \times n + n z u m x + 1)$: Encapsulates the sparsity pattern of matrix $U$ .
uvalfloat, ndarray, shape $(n z u m x)$: Records some of the nonzero values of matrix $U$ .
nnzlint: The number of nonzero values in the matrix $L$ .
nnzuint: The number of nonzero values in the matrix $U$ .
flopfloat: The number of floating-point operations performed.

Raises

NagValueError

(errno $1$ )

On entry, $n z u m x = ⟨ v a l u e ⟩$ .

Constraint: $n z u m x \geq 1$ .

(errno $1$ )

On entry, $n z l u m x = ⟨ v a l u e ⟩$ .

Constraint: $n z l u m x \geq 1$ .

(errno $1$ )

On entry, $n z l m x = ⟨ v a l u e ⟩$ .

Constraint: $n z l m x \geq 1$ .

(errno $1$ )

On entry, $t h r e s h = ⟨ v a l u e ⟩$ .

Constraint: $0.0 \leq t h r e s h \leq 1.0$ .

(errno $1$ )

On entry, $n = ⟨ v a l u e ⟩$ .

Constraint: $n \geq 0$ .

(errno $2$ )

Insufficient $n z l m x$ .

(errno $3$ )

Insufficient $n z u m x$ .

(errno $4$ )

Insufficient $n z l u m x$ .

(errno $5$ )

The matrix is singular – no factorization possible.

Notes

Given a real sparse matrix $A$ , direct_real_gen_lu computes an $L U$ factorization of $A$ with partial pivoting, $P_{r} A P_{c} = L U$ , where $P_{r}$ is a row permutation matrix (computed by direct_real_gen_lu), $P_{c}$ is a (supplied) column permutation matrix, $L$ is unit lower triangular and $U$ is upper triangular. The column permutation matrix, $P_{c}$ , must be computed by a prior call to direct_real_gen_setup(). The matrix $A$ must be presented in the column permuted, compressed column (Harwell–Boeing) format.

The $L U$ factorization is output in the form of four one-dimensional arrays: integer arrays $i l$ and $i u$ and real-valued arrays $l v a l$ and $u v a l$ . These describe the sparsity pattern and numerical values in the $L$ and $U$ matrices. The minimum required dimensions of these arrays cannot be given as a simple function of the size arguments (order and number of nonzero values) of the matrix $A$ . This is due to unpredictable fill-in created by partial pivoting. direct_real_gen_lu will, on return, indicate which dimensions of these arrays were not adequate for the computation or (in the case of one of them) give a firm bound. You should then allocate more storage and try again.

References

Demmel, J W, Eisenstat, S C, Gilbert, J R, Li, X S and Li, J W H, 1999, A supernodal approach to sparse partial pivoting, SIAM J. Matrix Anal. Appl. (20), 720–755

Demmel, J W, Gilbert, J R and Li, X S, 1999, An asynchronous parallel supernodal algorithm for sparse gaussian elimination, SIAM J. Matrix Anal. Appl. (20), 915–952

NAG and Python

Return to Front

naginterfaces.library.sparse.direct_real_gen_lu¶

naginterfaces.library.sparse.direct_​real_​gen_​lu¶

naginterfaces.library.sparse.direct_real_gen_lu¶