Documentation update on preconditioners

Author: j-fu

Project.toml

@@ -1,7 +1,7 @@
 name = "ExtendableSparse"
 uuid = "95c220a8-a1cf-11e9-0c77-dbfce5f500b3"
 authors = ["Juergen Fuhrmann <juergen.fuhrmann@wias-berlin.de>"]
-version = "0.6.0"
+version = "0.6.1"
 
 [deps]
 DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"

README.md

@@ -16,6 +16,8 @@ Any linear algebra method on `ExtendableSparseMatrix` starts with a `flush!` met
 
 `ExtendableSparseMatrix` is aimed to work as a drop-in replacement to `SparseMatrixCSC` in finite element and finite volume codes especally in those cases where the sparsity structure is hard to detect a priori and where working with an intermediadte COO representation appears to be not convenient.
 
+
+
 ## Caveat
 
 This package assumes that a $m \times n$  matrix is sparse if *each* row and *each* column have less than $C$ entries with
@@ -50,5 +52,18 @@ See [Julia issue #15630](https://github.com/JuliaLang/julia/issues/15630) for a
 
 
 
+## Preconditioners
+The package provides a common API for factorizations and preconditioners supporting
+series of solutions as during nonlinear and transient solves.
+For details, see the [corresponding documentation](https://j-fu.github.io/ExtendableSparse.jl/stable/iter/).
+
+## Interfaces to other packages
+The package provides interfaces to other sparse matrix solvers and preconditioners. Dependencies on these
+packages are handeled via [Requires.jl](https://github.com/JuliaPackaging/Requires.jl).
+Currently, support includes:
 
+- [Pardiso.jl](https://github.com/JuliaSparse/Pardiso.jl) (both ["project Pardiso"](https://pardiso-project.org)
+  and [MKL Pardiso](https://software.intel.com/content/www/us/en/develop/documentation/onemkl-developer-reference-fortran/top/sparse-solver-routines/onemkl-pardiso-parallel-direct-sparse-solver-interface.html))
+- [IncompleteLU.jl](https://github.com/haampie/IncompleteLU.jl)
+- [AlgebraicMultigrid.jl](https://github.com/JuliaLinearAlgebra/AlgebraicMultigrid.jl) (Ruge-Stüben AMG)
 

docs/Project.toml

@@ -1,9 +1,9 @@
 [deps]
-AlgebraicMultigrid = "2169fc97-5a83-5252-b627-83903c6c433c"
 BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
 DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterTools = "35a29f4d-8980-5a13-9543-d66fff28ecb8"
 ExtendableSparse = "95c220a8-a1cf-11e9-0c77-dbfce5f500b3"
 IncompleteLU = "40713840-3770-5561-ab4c-a76e7d0d7895"
+IterativeSolvers = "42fd0dbc-a981-5370-80f2-aaf504508153"
 Pardiso = "46dd5b70-b6fb-5a00-ae2d-e8fea33afaf2"

docs/src/iter.md

@@ -15,12 +15,113 @@ Private = false
 ```
 
 ## LU Factorizations
+Handling of the LU factorizations is meant to support
+a workflow where sequences of problems are solved based
+on the same matrix, where one possibly wants to re-use
+existing symbolic factorization data. 
+
+The support comes in two flavors.
+
+- Using [`factorize!`](@ref) which can work as a drop-in replacement for `lu!`:
+
+```@example
+using ExtendableSparse, LinearAlgebra
+using Pardiso
+A=fdrand(20,20,1,matrixtype=ExtendableSparseMatrix)
+n=size(A,1)
+b=rand(n)
+factorization=MKLPardisoLU()
+factorize!(factorization,A)
+nm1=norm(factorization\b)
+
+# mock update from Newton etc.
+for i=4:n-3
+    A[i,i+3]-=1.0e-4
+end
+factorize!(factorization,A)
+nm2=norm(factorization\b)
+nm1,nm2
+```
+
+- Using [`update!`](@ref), where the matrix only needs to be given at construction time:
+```@example
+using ExtendableSparse, LinearAlgebra
+A=fdrand(20,20,1,matrixtype=ExtendableSparseMatrix)
+n=size(A,1)
+b=rand(n)
+factorization=CholeskyFactorization(A)
+nm1=norm(factorization\b)
+
+# mock update from Newton etc.
+for i=4:n-3
+    A[i,i+3]-=1.0e-4
+    A[i-3,i]-=1.0e-4
+end
+update!(factorization)
+nm2=norm(factorization\b)
+nm1,nm2
+```
+
+
+### API
 ```@autodocs
 Modules = [ExtendableSparse]
 Pages = ["umfpack_lu.jl", "pardiso_lu.jl"]
 ```
 
 ## Preconditioners
+
+The API is similar to that for LU factorizations.
+
+
+The support comes in two flavors.
+
+- Using [`factorize!`](@ref):
+
+
+```@example
+using ExtendableSparse, LinearAlgebra
+using IterativeSolvers,IncompleteLU
+A=fdrand(20,20,1,matrixtype=ExtendableSparseMatrix)
+n=size(A,1)
+b=rand(n)
+preconditioner=ILUTPreconditioner(droptol=1.0e-2)
+factorize!(preconditioner,A)
+
+# mock update from Newton etc.
+nm1=norm(bicgstabl(A,b,1,Pl=preconditioner))
+for i=4:n-3
+    A[i,i+3]-=1.0e-4
+end
+factorize!(preconditioner,A)
+nm2=norm(bicgstabl(A,b,1,Pl=preconditioner))
+nm1,nm2
+```
+
+- Using [`update!`](@ref):
+
+```@example
+using ExtendableSparse, LinearAlgebra
+using IterativeSolvers
+A=fdrand(20,20,1,matrixtype=ExtendableSparseMatrix)
+n=size(A,1)
+b=rand(n)
+preconditioner=ILU0Preconditioner(A)
+nm1=norm(cg(A,b,Pl=preconditioner))
+
+# mock update from Newton etc.
+for i=4:n-3
+    A[i,i+3]-=1.0e-4
+    A[i-3,i]-=1.0e-4
+end
+update!(preconditioner)
+nm2=norm(cg(A,b,Pl=preconditioner))
+nm1,nm2
+```
+
+
+### API
+
 ```@autodocs
 Modules = [ExtendableSparse]
 Pages = ["jacobi.jl","ilu0.jl","parallel_jacobi.jl","ilut.jl","amg.jl"]