Add references to the generic interface in the docstrings (#992)

* Improve the docstrings of in-place methods

* More documentation

* Add more references to the generic interface in the docstrings

Author: amontoison

docs/make.jl

@@ -21,7 +21,7 @@ makedocs(
                                 "Adjoint systems" => "solvers/as.md",
                                 "Saddle-point and Hermitian quasi-definite systems" => "solvers/sp_sqd.md",
                                 "Generalized saddle-point and non-Hermitian partitioned systems" => "solvers/gsp.md"],
-           "Block-Krylov methods" => "block_krylov.md",
+           "Block Krylov methods" => "block_krylov.md",
            "In-place methods" => "inplace.md",
            "Generic interface" => "generic_interface.md",
            "Storage requirements" => "storage.md",

src/bicgstab.jl

@@ -42,6 +42,12 @@ If BICGSTAB stagnates, we recommend DQGMRES and BiLQ as alternative methods for
 
 BICGSTAB stops when `itmax` iterations are reached or when `‖rₖ‖ ≤ atol + ‖b‖ * rtol`.
 
+#### Interface
+
+To easily switch between Krylov methods, use the generic interface [`krylov_solve`](@ref) with `method = :bicgstab`.
+
+For an in-place variant that reuses memory across solves, see [`bicgstab!`](@ref).
+
 #### Input arguments
 
 * `A`: a linear operator that models a matrix of dimension `n`;
@@ -82,9 +88,12 @@ function bicgstab end
     workspace = bicgstab!(workspace::BicgstabWorkspace, A, b; kwargs...)
     workspace = bicgstab!(workspace::BicgstabWorkspace, A, b, x0; kwargs...)
 
-where `kwargs` are keyword arguments of [`bicgstab`](@ref).
+In these calls, `kwargs` are keyword arguments of [`bicgstab`](@ref).
+
+See [`BicgstabWorkspace`](@ref) for instructions on how to create the `workspace`.
 
-See [`BicgstabWorkspace`](@ref) for more details about the `workspace`.
+For a more generic interface, you can use [`krylov_workspace`](@ref) to allocate the workspace,
+and [`krylov_solve!`](@ref) to run the Krylov method in-place.
 """
 function bicgstab! end
 

src/bilq.jl

@@ -33,6 +33,12 @@ The relation `bᴴc ≠ 0` must be satisfied and by default `c = b`.
 When `A` is Hermitian and `b = c`, BiLQ is equivalent to SYMMLQ.
 BiLQ requires support for `adjoint(M)` and `adjoint(N)` if preconditioners are provided.
 
+#### Interface
+
+To easily switch between Krylov methods, use the generic interface [`krylov_solve`](@ref) with `method = :bilq`.
+
+For an in-place variant that reuses memory across solves, see [`bilq!`](@ref).
+
 #### Input arguments
 
 * `A`: a linear operator that models a matrix of dimension `n`;
@@ -74,9 +80,12 @@ function bilq end
     workspace = bilq!(workspace::BilqWorkspace, A, b; kwargs...)
     workspace = bilq!(workspace::BilqWorkspace, A, b, x0; kwargs...)
 
-where `kwargs` are keyword arguments of [`bilq`](@ref).
+In these calls, `kwargs` are keyword arguments of [`bilq`](@ref).
+
+See [`BilqWorkspace`](@ref) for instructions on how to create the `workspace`.
 
-See [`BilqWorkspace`](@ref) for more details about the `workspace`.
+For a more generic interface, you can use [`krylov_workspace`](@ref) to allocate the workspace,
+and [`krylov_solve!`](@ref) to run the Krylov method in-place.
 """
 function bilq! end
 

src/bilqr.jl

@@ -35,6 +35,12 @@ The relation `bᴴc ≠ 0` must be satisfied.
 BiLQ is used for solving primal system `Ax = b` of size n.
 QMR is used for solving dual system `Aᴴy = c` of size n.
 
+#### Interface
+
+To easily switch between Krylov methods, use the generic interface [`krylov_solve`](@ref) with `method = :bilqr`.
+
+For an in-place variant that reuses memory across solves, see [`bilqr!`](@ref).
+
 #### Input arguments
 
 * `A`: a linear operator that models a matrix of dimension `n`;
@@ -74,9 +80,12 @@ function bilqr end
     workspace = bilqr!(workspace::BilqrWorkspace, A, b, c; kwargs...)
     workspace = bilqr!(workspace::BilqrWorkspace, A, b, c, x0, y0; kwargs...)
 
-where `kwargs` are keyword arguments of [`bilqr`](@ref).
+In these calls, `kwargs` are keyword arguments of [`bilqr`](@ref).
+
+See [`BilqrWorkspace`](@ref) for instructions on how to create the `workspace`.
 
-See [`BilqrWorkspace`](@ref) for more details about the `workspace`.
+For a more generic interface, you can use [`krylov_workspace`](@ref) to allocate the workspace,
+and [`krylov_solve!`](@ref) to run the Krylov method in-place.
 """
 function bilqr! end
 

src/block_gmres.jl

@@ -22,6 +22,12 @@ Block-GMRES can be warm-started from an initial guess `X0` where `kwargs` are th
 
 Solve the linear system AX = B of size n with p right-hand sides using block-GMRES.
 
+#### Interface
+
+To easily switch between block Krylov methods, use the generic interface [`krylov_solve`](@ref) with `method = :block_gmres`.
+
+For an in-place variant that reuses memory across solves, see [`block_gmres!`](@ref).
+
 #### Input arguments
 
 * `A`: a linear operator that models a matrix of dimension `n`;
@@ -59,13 +65,15 @@ function block_gmres end
     workspace = block_gmres!(workspace::BlockGmresWorkspace, B; kwargs...)
     workspace = block_gmres!(workspace::BlockGmresWorkspace, B, X0; kwargs...)
 
-where `kwargs` are keyword arguments of [`block_gmres`](@ref).
-
+In these calls, `kwargs` are keyword arguments of [`block_gmres`](@ref).
 The keyword argument `memory` is the only exception.
 It is only supported by `block_gmres` and is required to create a `BlockGmresWorkspace`.
 It cannot be changed later.
 
-See [`BlockGmresWorkspace`](@ref) for more details about the `workspace`.
+See [`BlockGmresWorkspace`](@ref) for instructions on how to create the `workspace`.
+
+For a more generic interface, you can use [`krylov_workspace`](@ref) to allocate the workspace,
+and [`krylov_solve!`](@ref) to run the block Krylov method in-place.
 """
 function block_gmres! end
 

src/block_minres.jl

@@ -21,6 +21,12 @@ Block-MINRES can be warm-started from an initial guess `X0` where `kwargs` are t
 
 Solve the Hermitian linear system AX = B of size n with p right-hand sides using block-MINRES.
 
+#### Interface
+
+To easily switch between block Krylov methods, use the generic interface [`krylov_solve`](@ref) with `method = :block_minres`.
+
+For an in-place variant that reuses memory across solves, see [`block_minres!`](@ref).
+
 #### Input arguments
 
 * `A`: a linear operator that models a Hermitian matrix of dimension `n`;
@@ -54,9 +60,12 @@ function block_minres end
     workspace = block_minres!(workspace::BlockMinresWorkspace, B; kwargs...)
     workspace = block_minres!(workspace::BlockMinresWorkspace, B, X0; kwargs...)
 
-where `kwargs` are keyword arguments of [`block_minres`](@ref).
+In these calls, `kwargs` are keyword arguments of [`block_minres`](@ref).
+
+See [`BlockMinresWorkspace`](@ref) for instructions on how to create the `workspace`.
 
-See [`BlockMinresWorkspace`](@ref) for more details about the `workspace`.
+For a more generic interface, you can use [`krylov_workspace`](@ref) to allocate the workspace,
+and [`krylov_solve!`](@ref) to run the block Krylov method in-place.
 """
 function block_minres! end
 

src/car.jl

@@ -30,6 +30,12 @@ CAR solves the Hermitian and positive definite linear system Ax = b of size n.
 CAR minimizes ‖Arₖ‖₂ when M = Iₙ and ‖AMrₖ‖_M otherwise.
 The estimates computed every iteration are ‖Mrₖ‖₂ and ‖AMrₖ‖_M.
 
+#### Interface
+
+To easily switch between Krylov methods, use the generic interface [`krylov_solve`](@ref) with `method = :car`.
+
+For an in-place variant that reuses memory across solves, see [`car!`](@ref).
+
 #### Input arguments
 
 * `A`: a linear operator that models a Hermitian positive definite matrix of dimension `n`;
@@ -67,9 +73,12 @@ function car end
     workspace = car!(workspace::CarWorkspace, A, b; kwargs...)
     workspace = car!(workspace::CarWorkspace, A, b, x0; kwargs...)
 
-where `kwargs` are keyword arguments of [`car`](@ref).
+In these calls, `kwargs` are keyword arguments of [`car`](@ref).
+
+See [`CarWorkspace`](@ref) for instructions on how to create the `workspace`.
 
-See [`CarWorkspace`](@ref) for more details about the `workspace`.
+For a more generic interface, you can use [`krylov_workspace`](@ref) to allocate the workspace,
+and [`krylov_solve!`](@ref) to run the Krylov method in-place.
 """
 function car! end
 

src/cg.jl

@@ -35,6 +35,12 @@ The conjugate gradient method to solve the Hermitian linear system Ax = b of siz
 The method does _not_ abort if A is not definite.
 M also indicates the weighted norm in which residuals are measured.
 
+#### Interface
+
+To easily switch between Krylov methods, use the generic interface [`krylov_solve`](@ref) with `method = :cg`.
+
+For an in-place variant that reuses memory across solves, see [`cg!`](@ref).
+
 #### Input arguments
 
 * `A`: a linear operator that models a Hermitian positive definite matrix of dimension `n`;
@@ -74,9 +80,12 @@ function cg end
     workspace = cg!(workspace::CgWorkspace, A, b; kwargs...)
     workspace = cg!(workspace::CgWorkspace, A, b, x0; kwargs...)
 
-where `kwargs` are keyword arguments of [`cg`](@ref).
+In these calls, `kwargs` are keyword arguments of [`cg`](@ref).
+
+See [`CgWorkspace`](@ref) for instructions on how to create the `workspace`.
 
-See [`CgWorkspace`](@ref) for more details about the `workspace`.
+For a more generic interface, you can use [`krylov_workspace`](@ref) to allocate the workspace,
+and [`krylov_solve!`](@ref) to run the Krylov method in-place.
 """
 function cg! end
 

src/cg_lanczos.jl

@@ -32,6 +32,12 @@ Hermitian linear system Ax = b of size n.
 
 The method does _not_ abort if A is not definite.
 
+#### Interface
+
+To easily switch between Krylov methods, use the generic interface [`krylov_solve`](@ref) with `method = :cg_lanczos`.
+
+For an in-place variant that reuses memory across solves, see [`cg_lanczos!`](@ref).
+
 #### Input arguments
 
 * `A`: a linear operator that models a Hermitian matrix of dimension `n`;
@@ -71,9 +77,12 @@ function cg_lanczos end
     workspace = cg_lanczos!(workspace::CgLanczosWorkspace, A, b; kwargs...)
     workspace = cg_lanczos!(workspace::CgLanczosWorkspace, A, b, x0; kwargs...)
 
-where `kwargs` are keyword arguments of [`cg_lanczos`](@ref).
+In these calls, `kwargs` are keyword arguments of [`cg_lanczos`](@ref).
+
+See [`CgLanczosWorkspace`](@ref) for instructions on how to create the `workspace`.
 
-See [`CgLanczosWorkspace`](@ref) for more details about the `workspace`.
+For a more generic interface, you can use [`krylov_workspace`](@ref) to allocate the workspace,
+and [`krylov_solve!`](@ref) to run the Krylov method in-place.
 """
 function cg_lanczos! end
 

src/cg_lanczos_shift.jl

@@ -18,8 +18,9 @@ export cg_lanczos_shift, cg_lanczos_shift!
                                   M=I, ldiv::Bool=false,
                                   check_curvature::Bool=false, atol::T=√eps(T),
                                   rtol::T=√eps(T), itmax::Int=0,
-                                  timemax::Float64=Inf, verbose::Int=0, history::Bool=false,
-                                  callback=workspace->false, iostream::IO=kstdout)
+                                  timemax::Float64=Inf, verbose::Int=0,
+                                  history::Bool=false, callback=workspace->false,
+                                  iostream::IO=kstdout)
 
 `T` is an `AbstractFloat` such as `Float32`, `Float64` or `BigFloat`.
 `FC` is `T` or `Complex{T}`.
@@ -31,6 +32,12 @@ of shifted systems
 
 of size n. The method does _not_ abort if A + αI is not definite.
 
+#### Interface
+
+To easily switch between Krylov methods, use the generic interface [`krylov_solve`](@ref) with `method = :cg_lanczos_shift`.
+
+For an in-place variant that reuses memory across solves, see [`cg_lanczos_shift!`](@ref).
+
 #### Input arguments
 
 * `A`: a linear operator that models a Hermitian matrix of dimension `n`;
@@ -66,9 +73,12 @@ function cg_lanczos_shift end
 """
     workspace = cg_lanczos_shift!(workspace::CgLanczosShiftWorkspace, A, b, shifts; kwargs...)
 
-where `kwargs` are keyword arguments of [`cg_lanczos_shift`](@ref).
+In this call, `kwargs` are keyword arguments of [`cg_lanczos_shift`](@ref).
+
+See [`CgLanczosShiftWorkspace`](@ref) for instructions on how to create the `workspace`.
 
-See [`CgLanczosShiftWorkspace`](@ref) for more details about the `workspace`.
+For a more generic interface, you can use [`krylov_workspace`](@ref) to allocate the workspace,
+and [`krylov_solve!`](@ref) to run the Krylov method in-place.
 """
 function cg_lanczos_shift! end