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)

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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/f01/f01bsf.html

Parameters

warnlevint

Setting $warnlev=0$ disables output of warning messages during the process of the computation. Setting $warnlev=1$ enables these messages.

afloat, array-like, shape $\left(\text{licn}\right)$

$a[\text{i}-1]$, for $\text{i}=1,2,\dots ,\text{nz}$, must contain the nonzero elements of the sparse matrix $A$. They can be in any order since real_gen_sparse_lu_reuse will reorder them.

ivectint, array-like, shape $\left(\text{nz}\right)$

$ivect[\text{i}-1]$ and $jvect[\text{i}-1]$, for $\text{i}=1,2,\dots ,\text{nz}$, must contain the row index and the column index respectively of the nonzero element stored in $a[i-1]$.

jvectint, array-like, shape $\left(\text{nz}\right)$

$ivect[\text{i}-1]$ and $jvect[\text{i}-1]$, for $\text{i}=1,2,\dots ,\text{nz}$, must contain the row index and the column index respectively of the nonzero element stored in $a[i-1]$.

commdict, communication object

Communication structure.

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

growbool

If $grow=True$, then on exit $w\left[0\right]$ 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 $w\left[0\right]$ indicates that the $LU$ factorization may be inaccurate and you should be wary of the results and perhaps increase the argument $\text{pivot}$ for subsequent runs (see Accuracy).

etafloat, optional

The relative pivot threshold below which an error diagnostic is provoked and $\text{errno}$ is set to $errno$ = 7. If $eta$ is greater than $1.0$, then no check on pivot size is made.

abortbool, optional

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

If $abort=False$, 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 $\text{errno}$ on entry.

io_managerFileObjManager, optional

Manager for I/O in this routine.

Returns

afloat, ndarray, shape $\left(\text{licn}\right)$

The nonzero elements in the $LU$ 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 $\left(n\right)$

If $grow=True$, $w\left[0\right]$ contains an estimate (an upper bound) of the increase in size of elements encountered during the factorization (see $grow$); the rest of the array is used as workspace.

If $grow=False$, the array is not used.

rpminfloat

If $eta$ is less than $1.0$, then $rpmin$ 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 $rpmin$ is very small it may be advisable to perform a new factorization using real_gen_sparse_lu().

Raises

NagValueError

(errno $1$)

On entry, $n=⟨value⟩$.

Constraint: $n>0$.

(errno $2$)

On entry, $\text{nz}=⟨value⟩$.

Constraint: $\text{nz}>0$.

(errno $3$)

On entry, $\text{licn}=⟨value⟩$ and $\text{nz}=⟨value⟩$.

Constraint: $\text{licn}\ge \text{nz}$.

(errno $4$)

On entry, $\text{irn}[I-1]$ in real_gen_sparse_lu() or $comm{[}^{\prime }ic{n}^{\prime }\left]\right[I-1]$ is out of range: $I=⟨value⟩$, $a[I-1]=⟨value⟩$ $\text{irn}[I-1]=⟨value⟩$ in real_gen_sparse_lu(), $comm{[}^{\prime }ic{n}^{\prime }\left]\right[I-1]=⟨value⟩$.

(errno $5$)

Nonzero element ($⟨value⟩$, $⟨value⟩$) was not in L/U pattern.

(errno $5$)

Nonzero element ($⟨value⟩$, $⟨value⟩$) in zero off-diagonal block.

(errno $6$)

Numerical singularity in row $⟨value⟩$ - decomposition aborted.

(errno $8$)

On entry, duplicate elements found – see advisory messages.

(errno $9$)

On entry, $warnlev=⟨value⟩$.

Constraint: $warnlev=0$ or $1$.

Warns

NagAlgorithmicWarning

(errno $7$)

Subthreshold pivot in row $⟨value⟩$ - 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 $LU$ 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 $Ax=b$ or $A^{T}x=b$.

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