naginterfaces.library.sparse.real_symm_precon_ichol¶
- naginterfaces.library.sparse.real_symm_precon_ichol(nnz, a, irow, icol, lfill, dtol, mic, dscale, ipiv, pstrat='M')[source]¶
real_symm_precon_ichol
computes an incomplete Cholesky factorization of a real sparse symmetric matrix, represented in symmetric coordinate storage format. This factorization may be used as a preconditioner in combination withreal_symm_solve_ichol()
orreal_symm_basic_solver()
.For full information please refer to the NAG Library document for f11ja
https://support.nag.com/numeric/nl/nagdoc_30.1/flhtml/f11/f11jaf.html
- Parameters
- nnzint
The number of nonzero elements in the lower triangular part of the matrix .
- afloat, array-like, shape
The nonzero elements in the lower triangular part of the matrix , ordered by increasing row index, and by increasing column index within each row. Multiple entries for the same row and column indices are not permitted. The function
real_symm_sort()
may be used to order the elements in this way.- irowint, array-like, shape
The row indices of the nonzero elements supplied in .
- icolint, array-like, shape
The column indices of the nonzero elements supplied in .
- lfillint
If its value is the maximum level of fill allowed in the decomposition (see Further Comments). A negative value of indicates that will be used to control the fill instead.
- dtolfloat
If , is used as a drop tolerance to control the fill-in (see Further Comments); otherwise is not referenced.
- micstr, length 1
Indicates whether or not the factorization should be modified to preserve row sums (see Choice of Arguments).
The factorization is modified.
The factorization is not modified.
- dscalefloat
The diagonal scaling parameter. All diagonal elements are multiplied by the factor () at the start of the factorization. This can be used to ensure that the preconditioner is positive definite. See Choice of Arguments.
- ipivint, array-like, shape
If , must specify the row index of the diagonal element used as a pivot at elimination stage . Otherwise need not be initialized.
- pstratstr, length 1, optional
Specifies the pivoting strategy to be adopted.
No pivoting is carried out.
Diagonal pivoting aimed at minimizing fill-in is carried out, using the Markowitz strategy.
Diagonal pivoting is carried out according to the user-defined input value of .
- Returns
- afloat, ndarray, shape
The first elements of contain the nonzero elements of and the next elements contain the elements of the lower triangular matrix . Matrix elements are ordered by increasing row index, and by increasing column index within each row.
- irowint, ndarray, shape
The row indices of the nonzero elements returned in .
- icolint, ndarray, shape
The column indices of the nonzero elements returned in .
- ipivint, ndarray, shape
The pivot indices. If then the diagonal element in row was used as the pivot at elimination stage .
- istrint, ndarray, shape
, for , is the starting address in the arrays , and of row of the matrix . is the address of the last nonzero element in plus one.
- nnzcint
The number of nonzero elements in the lower triangular matrix .
- npivmint
The number of pivots which were modified during the factorization to ensure that was positive definite. The quality of the preconditioner will generally depend on the returned value of . If is large the preconditioner may not be satisfactory. In this case it may be advantageous to call
real_symm_precon_ichol
again with an increased value of either or . See also Further Comments.
- Raises
- NagValueError
- (errno )
On entry, and .
Constraint: .
- (errno )
On entry, .
Constraint: .
- (errno )
On entry, .
Constraint: .
- (errno )
On entry, , or : .
- (errno )
On entry, or : .
- (errno )
On entry, .
Constraint: .
- (errno )
On entry, and .
Constraint: .
- (errno )
On entry, the location () is a duplicate: .
- (errno )
On entry, is out of order: .
- (errno )
On entry, , and .
Constraint: and .
- (errno )
On entry, , and .
Constraint: and .
- (errno )
On entry, a user-supplied value of is repeated.
- (errno )
On entry, a user-supplied value of lies outside the range .
- (errno )
The number of nonzero entries in the decomposition is too large. The decomposition has been terminated before completion. Either increase , or reduce the fill by setting , reducing , or increasing .
- (errno )
A serious error has occurred in an internal call. Check all function calls and array sizes. Seek expert help.
- Notes
In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.
real_symm_precon_ichol
computes an incomplete Cholesky factorization (see Meijerink and Van der Vorst (1977)) of a real sparse symmetric matrix . It is designed specifically for positive definite matrices, but may also work for some mildly indefinite cases. The factorization is intended primarily for use as a preconditioner with one of the symmetric iterative solversreal_symm_solve_ichol()
orreal_symm_basic_solver()
.The decomposition is written in the form
where
and is a permutation matrix, is lower triangular with unit diagonal elements, is diagonal and is a remainder matrix.
The amount of fill-in occurring in the factorization can vary from zero to complete fill, and can be controlled by specifying either the maximum level of fill , or the drop tolerance . The factorization may be modified in order to preserve row sums, and the diagonal elements may be perturbed to ensure that the preconditioner is positive definite. Diagonal pivoting may optionally be employed, either with a user-defined ordering, or using the Markowitz strategy (see Markowitz (1957)), which aims to minimize fill-in. For further details see Further Comments.
The sparse matrix is represented in symmetric coordinate storage (SCS) format (see the F11 Introduction). The array stores all the nonzero elements of the lower triangular part of , while arrays and store the corresponding row and column indices respectively. Multiple nonzero elements may not be specified for the same row and column index.
The preconditioning matrix is returned in terms of the SCS representation of the lower triangular matrix
- References
Chan, T F, 1991, Fourier analysis of relaxed incomplete factorization preconditioners, SIAM J. Sci. Statist. Comput. (12(2)), 668–680
Markowitz, H M, 1957, The elimination form of the inverse and its application to linear programming, Management Sci. (3), 255–269
Meijerink, J and Van der Vorst, H, 1977, An iterative solution method for linear systems of which the coefficient matrix is a symmetric M-matrix, Math. Comput. (31), 148–162
Salvini, S A and Shaw, G J, 1995, An evaluation of new NAG Library solvers for large sparse symmetric linear systems, NAG Technical Report TR1/95
Van der Vorst, H A, 1990, The convergence behaviour of preconditioned CG and CG-S in the presence of rounding errors, Lecture Notes in Mathematics, (eds O Axelsson and L Y Kolotilina) (1457), Springer–Verlag