naginterfaces.library.sparse.complex_herm_precon_ichol¶
- naginterfaces.library.sparse.complex_herm_precon_ichol(nnz, a, irow, icol, lfill, dtol, mic, dscale, ipiv, pstrat='M')[source]¶
complex_herm_precon_ichol
computes an incomplete Cholesky factorization of a complex sparse Hermitian matrix, represented in symmetric coordinate storage format. This factorization may be used as a preconditioner in combination withcomplex_herm_solve_ilu()
.For full information please refer to the NAG Library document for f11jn
https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/f11/f11jnf.html
- Parameters
- nnzint
The number of nonzero elements in the lower triangular part of the matrix .
- acomplex, 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
complex_herm_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 also Choice of Arguments.
- ipivint, array-like, shape
If , must specify the row index of the diagonal element to be 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 (see Markowitz (1957)).
Diagonal pivoting is carried out according to the user-defined input array .
- Returns
- acomplex, 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 , 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
complex_herm_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
complex_herm_precon_ichol
computes an incomplete Cholesky factorization (see Meijerink and Van der Vorst (1977)) of a complex sparse Hermitian 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 the complex Hermitian iterative solvercomplex_herm_solve_ilu()
.The decomposition is written in the form
where
and is a permutation matrix, is lower triangular complex with unit diagonal elements, is real 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