naginterfaces.library.matop.real_​gen_​sparse_​lu_​reuse

naginterfaces.library.matop.real_gen_sparse_lu_reuse(warnlev, a, ivect, jvect, comm, grow, eta=0.0001, abort=True, io_manager=None)[source]

real_gen_sparse_lu_reuse factorizes a real sparse matrix using the pivotal sequence previously obtained by real_gen_sparse_lu() when a matrix of the same sparsity pattern was factorized.

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

https://www.nag.com/numeric/nl/nagdoc_28.4/flhtml/f01/f01bsf.html

Parameters
warnlevint

Setting disables output of warning messages during the process of the computation. Setting enables these messages.

afloat, array-like, shape

, for , must contain the nonzero elements of the sparse matrix . They can be in any order since real_gen_sparse_lu_reuse will reorder them.

ivectint, array-like, shape

and , for , must contain the row index and the column index respectively of the nonzero element stored in .

jvectint, array-like, shape

and , for , must contain the row index and the column index respectively of the nonzero element stored in .

commdict, communication object

Communication structure.

This argument must have been initialized by a prior call to real_gen_sparse_lu().

growbool

If , then on exit contains an estimate (an upper bound) of the increase in size of elements encountered during the factorization. If the matrix is well-scaled (see Further Comments), then a high value for indicates that the factorization may be inaccurate and you should be wary of the results and perhaps increase the argument for subsequent runs (see Accuracy).

etafloat, optional

The relative pivot threshold below which an error diagnostic is provoked and is set to = 7. If is greater than , then no check on pivot size is made.

abortbool, optional

If , real_gen_sparse_lu_reuse exits immediately (with = 8) if it finds duplicate elements in the input matrix.

If , real_gen_sparse_lu_reuse proceeds using a value equal to the sum of the duplicate elements.

In either case details of each duplicate element are output on the file object associated with the advisory I/O unit (see FileObjManager), unless suppressed by the value of on entry.

io_managerFileObjManager, optional

Manager for I/O in this routine.

Returns
afloat, ndarray, shape

The nonzero elements in the factorization. The array must not be changed by you between a call of real_gen_sparse_lu_reuse and a call of linsys.real_sparse_fac_solve.

wfloat, ndarray, shape

If , contains an estimate (an upper bound) of the increase in size of elements encountered during the factorization (see ); the rest of the array is used as workspace.

If , the array is not used.

rpminfloat

If is less than , then gives the smallest ratio of the pivot to the largest element in the row of the corresponding upper triangular factor thus monitoring the stability of the factorization. If is very small it may be advisable to perform a new factorization using real_gen_sparse_lu().

Raises
NagValueError
(errno )

On entry, .

Constraint: .

(errno )

On entry, .

Constraint: .

(errno )

On entry, and .

Constraint: .

(errno )

On entry, in real_gen_sparse_lu() or is out of range: , in real_gen_sparse_lu(), .

(errno )

Nonzero element (, ) was not in L/U pattern.

(errno )

Nonzero element (, ) in zero off-diagonal block.

(errno )

Numerical singularity in row - decomposition aborted.

(errno )

On entry, duplicate elements found – see advisory messages.

(errno )

On entry, .

Constraint: or .

Warns
NagAlgorithmicWarning
(errno )

Subthreshold pivot in row - decomposition completed.

Notes

No equivalent traditional C interface for this routine exists in the NAG Library.

real_gen_sparse_lu_reuse accepts as input a real sparse matrix of the same sparsity pattern as a matrix previously factorized by a call of real_gen_sparse_lu(). It first applies to the matrix the same permutations as were used by real_gen_sparse_lu(), both for permutation to block triangular form and for pivoting, and then performs Gaussian elimination to obtain the factorization of the diagonal blocks.

Extensive data checks are made; duplicated nonzeros can be accumulated.

The factorization is intended to be used by linsys.real_sparse_fac_solve to solve sparse systems of linear equations or .

real_gen_sparse_lu_reuse is much faster than real_gen_sparse_lu() and in some applications it is expected that there will be many calls of real_gen_sparse_lu_reuse for each call of real_gen_sparse_lu().

The method is fully described in Duff (1977).

A more recent algorithm for the same calculation is provided by sparse.direct_real_gen_lu.

References

Duff, I S, 1977, MA28 – a set of Fortran subroutines for sparse unsymmetric linear equations, AERE Report R8730, HMSO