From 9109b0dd37d9feac1b2516f7215bc25204ee32fa Mon Sep 17 00:00:00 2001 From: Alexis Montoison <35051714+amontoison@users.noreply.github.com> Date: Wed, 2 Oct 2024 15:00:51 -0500 Subject: [PATCH] Update the documentation (#879) * Update the documentation * Fix inplace.md --- docs/make.jl | 5 +++-- docs/src/gpu.md | 10 +++++++--- docs/src/inplace.md | 7 ++++--- docs/src/{factorization-free.md => matrix_free.md} | 4 ++-- docs/src/preconditioners.md | 11 +++++++++-- 5 files changed, 25 insertions(+), 12 deletions(-) rename docs/src/{factorization-free.md => matrix_free.md} (97%) diff --git a/docs/make.jl b/docs/make.jl index 7dd919b50..6afe6ebc1 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -23,11 +23,12 @@ makedocs( "Generalized saddle-point and non-Hermitian partitioned systems" => "solvers/gsp.md"], "Block-Krylov methods" => "block_krylov.md", "In-place methods" => "inplace.md", + "Storage requirements" => "storage.md", "Preconditioners" => "preconditioners.md", - "Storage requirements" => "storage.md", "GPU support" => "gpu.md", + # "KrylovPreconditioners.jl" => "krylov_preconditioners.md", "Warm-start" => "warm-start.md", - "Factorization-free operators" => "factorization-free.md", + "Matrix-free operators" => "matrix_free.md", "Callbacks" => "callbacks.md", "Performance tips" => "tips.md", "Tutorials" => ["CG" => "examples/cg.md", diff --git a/docs/src/gpu.md b/docs/src/gpu.md index 20055ed3b..2db45df1b 100644 --- a/docs/src/gpu.md +++ b/docs/src/gpu.md @@ -52,7 +52,7 @@ if CUDA.functional() end ``` -If you use a Krylov method that only requires `A * v` products (see [here](@ref factorization-free)), the most efficient format is `CuSparseMatrixCSR`. +If you use a Krylov method that only requires `A * v` products (see [here](@ref matrix-free)), the most efficient format is `CuSparseMatrixCSR`. Optimized operator-vector and operator-matrix products that exploit GPU features can be also used by means of linear operators. For instance, when executing sparse matrix products on NVIDIA GPUs, the `mul!` function utilized by Krylov.jl internally calls three routines from CUSPARSE. @@ -68,8 +68,8 @@ opA_gpu = KrylovOperator(A_gpu) x_gpu, stats = gmres(opA_gpu, b_gpu) ``` -Preconditioners, especially incomplete Cholesky or Incomplete LU factorizations that involve triangular solves, -can be applied directly on GPU thanks to efficient operators that take advantage of CUSPARSE routines. +Preconditioners, especially incomplete Cholesky or incomplete LU factorizations that involve sparse triangular solves, +can be applied directly on GPU thanks to efficient operators (like `TriangularOperator`) that take advantage of CUSPARSE routines. ### Example with a symmetric positive-definite system @@ -221,6 +221,10 @@ opA_gpu = KrylovOperator(A_gpu) x_gpu, stats = bicgstab(opA_gpu, b_gpu) ``` +Preconditioners, especially incomplete Cholesky or incomplete LU factorizations that involve sparse triangular solves, +can be applied directly on GPU thanks to efficient operators (like `TriangularOperator`) that take advantage of rocSPARSE routines. + + ## Intel GPUs All solvers in Krylov.jl can be used with [oneAPI.jl](https://github.com/JuliaGPU/oneAPI.jl) and allow computations on Intel GPUs. diff --git a/docs/src/inplace.md b/docs/src/inplace.md index c74d5fd99..99ad41c7b 100644 --- a/docs/src/inplace.md +++ b/docs/src/inplace.md @@ -1,7 +1,8 @@ -## In-place methods +## [In-place methods](@id in-place) All solvers in Krylov.jl have an in-place variant implemented in a method whose name ends with `!`. -A workspace (`KrylovSolver`) that contains the storage needed by a Krylov method can be used to solve multiple linear systems that have the same dimensions in the same floating-point precision. +A workspace (`KrylovSolver`), which contains the storage needed by a Krylov method, can be used to solve multiple linear systems with the same dimensions and the same floating-point precision. +The section [storage requirements](@ref storage-requirements) specifies the memory needed for each Krylov method. Each `KrylovSolver` has two constructors: ```@constructors @@ -50,7 +51,7 @@ Krylov.issolved ## Examples We illustrate the use of in-place Krylov solvers with two well-known optimization methods. -The details of the optimization methods are described in the section about [Factorization-free operators](@ref factorization-free). +The details of the optimization methods are described in the section about [Factorization-free operators](@ref matrix-free). ### Example 1: Newton's method for convex optimization without linesearch diff --git a/docs/src/factorization-free.md b/docs/src/matrix_free.md similarity index 97% rename from docs/src/factorization-free.md rename to docs/src/matrix_free.md index 7b4b399d8..c77ce346c 100644 --- a/docs/src/factorization-free.md +++ b/docs/src/matrix_free.md @@ -27,9 +27,9 @@ html.theme--documenter-dark .content table th:last-child { ``` -## [Factorization-free operators](@id factorization-free) +## [Matrix-free operators](@id matrix-free) -All methods are factorization-free, which means that you only need to provide operator-vector products. +All methods are matrix-free, which means that you only need to provide operator-vector products. The `A` or `B` input arguments of Krylov.jl solvers can be any object that represents a linear operator. That object must implement `mul!`, for multiplication with a vector, `size()` and `eltype()`. For certain methods it must also implement `adjoint()`. diff --git a/docs/src/preconditioners.md b/docs/src/preconditioners.md index 38da24cc5..62c67b98a 100644 --- a/docs/src/preconditioners.md +++ b/docs/src/preconditioners.md @@ -137,7 +137,7 @@ Methods concerned: [`CGNE`](@ref cgne), [`CRMR`](@ref crmr), [`LNLQ`](@ref lnlq) ## Packages that provide preconditioners -- [IncompleteLU.jl](https://github.com/haampie/IncompleteLU.jl) implements the left-looking and Crout versions of ILU decompositions. +- [KrylovPreconditioners.jl](https://github.com/JuliaSmoothOptimizers/KrylovPreconditioners.jl) implements block-Jacobi, IC(0) and ILU(0) preconditioners. - [ILUZero.jl](https://github.com/mcovalt/ILUZero.jl) is a Julia implementation of incomplete LU factorization with zero level of fill-in. - [LimitedLDLFactorizations.jl](https://github.com/JuliaSmoothOptimizers/LimitedLDLFactorizations.jl) for limited-memory LDLᵀ factorization of symmetric matrices. - [AlgebraicMultigrid.jl](https://github.com/JuliaLinearAlgebra/AlgebraicMultigrid.jl) provides two algebraic multigrid (AMG) preconditioners. @@ -146,6 +146,13 @@ Methods concerned: [`CGNE`](@ref cgne), [`CRMR`](@ref crmr), [`LNLQ`](@ref lnlq) ## Examples +```julia +using KrylovPreconditioners, Krylov + +P⁻¹ = BlockJacobiPreconditioner(A) # Block-Jacobi preconditioner +x, stats = gmres(A, b, M=P⁻¹) +``` + ```julia using Krylov n, m = size(A) @@ -163,7 +170,7 @@ x, stats = minres(A, b, M=P⁻¹) ``` ```julia -using IncompleteLU, Krylov +using KrylovPreconditioners, Krylov Pℓ = ilu(A) x, stats = gmres(A, b, M=Pℓ, ldiv=true) # left preconditioning ```