naginterfaces.library.matop.real_gen_sparse_lu¶
- naginterfaces.library.matop.real_gen_sparse_lu(n, nz, warnlev, errlev, a, irn, icn, abort, pivot=0.1, lblock=True, grow=True, io_manager=None)[source]¶
real_gen_sparse_lu
factorizes a real sparse matrix. The function either forms the factorization of a permutation of the entire matrix, or, optionally, first permutes the matrix to block lower triangular form and then only factorizes the diagonal blocks.For full information please refer to the NAG Library document for f01br
https://www.nag.com/numeric/nl/nagdoc_29/flhtml/f01/f01brf.html
- Parameters
- nint
, the order of the matrix .
- nzint
The number of nonzero elements in the matrix .
- warnlevint
Setting disables output of warning messages during the process of the computation. Setting enables these messages.
- errlevint
Setting disables output of error 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
will reorder them.- irnint, array-like, shape
, for , must contain the row index of the nonzero element stored in .
- icnint, array-like, shape
, for , must contain the column index of the nonzero element stored in .
- abortbool, array-like, shape
If ,
real_gen_sparse_lu
will exit immediately on detecting a structural singularity (one that depends on the pattern of nonzeros) and return = 1; otherwise it will complete the factorization (see Singular and Rectangular Systems).If ,
real_gen_sparse_lu
will exit immediately on detecting a numerical singularity (one that depends on the numerical values) and return = 2; otherwise it will complete the factorization (see Singular and Rectangular Systems).If ,
real_gen_sparse_lu
will exit immediately (with = 5) when the arrays and [‘icn’] are filled up by the previously factorized, active and unfactorized parts of the matrix; otherwise it continues so that better guidance on necessary array sizes can be given in and , and will exit with in the range to .Note that there is always an immediate error exit if the array is too small.
If ,
real_gen_sparse_lu
exits immediately (with = 13) if it finds duplicate elements in the input matrix.If ,
real_gen_sparse_lu
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.Suggested value:
- pivotfloat, optional
Should have a value in the range and is used to control the choice of pivots. If , the value is assumed, and if , the value is assumed. When searching a row for a pivot, any element is excluded which is less than times the largest of those elements in the row available as pivots. Thus decreasing biases the algorithm to maintaining sparsity at the expense of stability.
- lblockbool, optional
If , the matrix is preordered into block lower triangular form before the factorization is performed; otherwise the entire matrix is factorized.
- growbool, optional
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).
- 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
and a call oflinsys.real_sparse_fac_solve
.- irnint, ndarray, shape
is overwritten and is not needed for subsequent calls of
real_gen_sparse_lu_reuse()
orlinsys.real_sparse_fac_solve
.- commdict, communication object
Information about the factorization for subsequent communication to
real_gen_sparse_lu_reuse()
orlinsys.real_sparse_fac_solve
.- increaseNone or float
If , contains an estimate (an upper bound) of the increase in size of elements encountered during the factorization (see ).
- Raises
- NagValueError
- (errno )
Matrix is structurally singular – decomposition aborted .
- (errno )
Matrix is structurally singular – decomposition aborted.
- (errno )
Matrix is numerically singular – decomposition aborted.
- (errno )
too small. Decomposition aborted at stage in block with first row and last row . To continue set to at least .
- (errno )
too small. Decomposition aborted at stage in block with first row and last row .
- (errno )
much too small. Decomposition aborted at stage in block with first row and last row . To continue set to at least .
- (errno )
much too small. Decomposition aborted at stage in block with first row and last row .
- (errno )
too small. Decomposition aborted at stage in block with first row and last row .
- (errno )
too small. Decomposition aborted at stage in block with first row and last row . To continue set to at least .
- (errno )
too small. For successful decomposition set to at least .
- (errno )
and too small. Decomposition aborted at stage in block with first row and last row . To continue set to at least .
- (errno )
and too small. Decomposition aborted at stage in block with first row and last row .
- (errno )
not big enough for permutation – increase by .
- (errno )
On entry, .
Constraint: .
- (errno )
On entry, .
Constraint: .
- (errno )
On entry, and .
Constraint: .
- (errno )
On entry, and .
Constraint: .
- (errno )
On entry, or is out of range: , , .
- (errno )
On entry, duplicate elements found – see advisory messages.
- (errno )
On entry, .
Constraint: or .
- (errno )
On entry, .
Constraint: or .
- Warns
- NagAlgorithmicWarning
- (errno )
Matrix is numerically singular – decomposition completed.
- (errno )
Matrix is structurally singular – decomposition completed.
- Notes
No equivalent traditional C interface for this routine exists in the NAG Library.
Given a real sparse matrix ,
real_gen_sparse_lu
may be used to obtain the factorization of a permutation of ,where and are permutation matrices, is unit lower triangular and is upper triangular. The function uses a sparse variant of Gaussian elimination, and the pivotal strategy is designed to compromise between maintaining sparsity and controlling loss of accuracy through round-off.
Optionally the function first permutes the matrix into block lower triangular form and then only factorizes the diagonal blocks. For some matrices this gives a considerable saving in storage and execution time.
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 . If several matrices of the same sparsity pattern are to be factorized,real_gen_sparse_lu_reuse()
should be used for the second and subsequent matrices.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