Add optional argument(s) in the docstrings

src/bicgstab.jl

@@ -16,14 +16,19 @@
 export bicgstab, bicgstab!
 
 """
-    (x, stats) = bicgstab(A, b::AbstractVector{FC}; c::AbstractVector{FC}=b,
-                          M=I, N=I, atol::T=√eps(T), rtol::T=√eps(T),
-                          itmax::Int=0, verbose::Int=0, history::Bool=false,
+    (x, stats) = bicgstab(A, b::AbstractVector{FC};
+                          c::AbstractVector{FC}=b, M=I, N=I,
+                          atol::T=√eps(T), rtol::T=√eps(T), itmax::Int=0,
+                          verbose::Int=0, history::Bool=false,
                           ldiv::Bool=false, callback=solver->false)
 
 `T` is an `AbstractFloat` such as `Float32`, `Float64` or `BigFloat`.
 `FC` is `T` or `Complex{T}`.
 
+    (x, stats) = bicgstab(A, b, x0::AbstractVector; kwargs...)
+
+BICGSTAB can be warm-started from an initial guess `x0` where `kwargs` are the same keyword arguments as above.
+
 Solve the square linear system Ax = b of size n using BICGSTAB.
 BICGSTAB requires two initial vectors `b` and `c`.
 The relation `bᴴc ≠ 0` must be satisfied and by default `c = b`.
@@ -42,12 +47,6 @@ Information will be displayed every `verbose` iterations.
 
 This implementation allows a left preconditioner `M` and a right preconditioner `N`.
 
-BICGSTAB can be warm-started from an initial guess `x0` with
-
-    (x, stats) = bicgstab(A, b, x0; kwargs...)
-
-where `kwargs` are the same keyword arguments as above.
-
 The callback is called as `callback(solver)` and should return `true` if the main loop should terminate,
 and `false` otherwise.
 
@@ -56,6 +55,10 @@ and `false` otherwise.
 * `A`: a linear operator that models a matrix of dimension n;
 * `b`: a vector of length n.
 
+#### Optional argument
+
+* `x0`: a vector of length n that represents an initial guess of the solution x.
+
 #### Output arguments
 
 * `x`: a dense vector of length n;

src/bilq.jl

@@ -13,29 +13,27 @@
 export bilq, bilq!
 
 """
-    (x, stats) = bilq(A, b::AbstractVector{FC}; c::AbstractVector{FC}=b,
-                      atol::T=√eps(T), rtol::T=√eps(T), transfer_to_bicg::Bool=true,
-                      itmax::Int=0, verbose::Int=0, history::Bool=false,
-                      callback=solver->false)
+    (x, stats) = bilq(A, b::AbstractVector{FC};
+                      c::AbstractVector{FC}=b, atol::T=√eps(T),
+                      rtol::T=√eps(T), transfer_to_bicg::Bool=true,
+                      itmax::Int=0, verbose::Int=0,
+                      history::Bool=false, callback=solver->false)
 
 `T` is an `AbstractFloat` such as `Float32`, `Float64` or `BigFloat`.
 `FC` is `T` or `Complex{T}`.
 
-Solve the square linear system Ax = b of size n using BiLQ.
+    (x, stats) = bilq(A, b, x0::AbstractVector; kwargs...)
+
+BiLQ can be warm-started from an initial guess `x0` where `kwargs` are the same keyword arguments as above.
 
+Solve the square linear system Ax = b of size n using BiLQ.
 BiLQ is based on the Lanczos biorthogonalization process and requires two initial vectors `b` and `c`.
 The relation `bᴴc ≠ 0` must be satisfied and by default `c = b`.
 When `A` is symmetric and `b = c`, BiLQ is equivalent to SYMMLQ.
 
 An option gives the possibility of transferring to the BiCG point,
 when it exists. The transfer is based on the residual norm.
 
-BiLQ can be warm-started from an initial guess `x0` with
-
-    (x, stats) = bilq(A, b, x0; kwargs...)
-
-where `kwargs` are the same keyword arguments as above.
-
 The callback is called as `callback(solver)` and should return `true` if the main loop should terminate,
 and `false` otherwise.
 
@@ -44,6 +42,10 @@ and `false` otherwise.
 * `A`: a linear operator that models a matrix of dimension n;
 * `b`: a vector of length n.
 
+#### Optional argument
+
+* `x0`: a vector of length n that represents an initial guess of the solution x.
+
 #### Output arguments
 
 * `x`: a dense vector of length n;

src/bilqr.jl

@@ -21,6 +21,10 @@ export bilqr, bilqr!
 `T` is an `AbstractFloat` such as `Float32`, `Float64` or `BigFloat`.
 `FC` is `T` or `Complex{T}`.
 
+    (x, y, stats) = bilqr(A, b, c, x0::AbstractVector, y0::AbstractVector; kwargs...)
+
+BiLQR can be warm-started from initial guesses `x0` and `y0` where `kwargs` are the same keyword arguments as above.
+
 Combine BiLQ and QMR to solve adjoint systems.
 
     [0  A] [y] = [b]
@@ -33,12 +37,6 @@ QMR is used for solving dual system `Aᴴy = c` of size n.
 An option gives the possibility of transferring from the BiLQ point to the
 BiCG point, when it exists. The transfer is based on the residual norm.
 
-BiLQR can be warm-started from initial guesses `x0` and `y0` with
-
-    (x, y, stats) = bilqr(A, b, c, x0, y0; kwargs...)
-
-where `kwargs` are the same keyword arguments as above.
-
 The callback is called as `callback(solver)` and should return `true` if the main loop should terminate,
 and `false` otherwise.
 
@@ -48,11 +46,16 @@ and `false` otherwise.
 * `b`: a vector of length n;
 * `c`: a vector of length n.
 
+#### Optional arguments
+
+* `x0`: a vector of length n that represents an initial guess of the solution x;
+* `y0`: a vector of length n that represents an initial guess of the solution y.
+
 #### Output arguments
 
 * `x`: a dense vector of length n;
 * `y`: a dense vector of length n;
-* `stats`: statistics collected on the run in a [`AdjointStats`](@ref) structure.
+* `stats`: statistics collected on the run in an [`AdjointStats`](@ref) structure.
 
 #### Reference
 

src/cg.jl

@@ -26,6 +26,10 @@ export cg, cg!
 `T` is an `AbstractFloat` such as `Float32`, `Float64` or `BigFloat`.
 `FC` is `T` or `Complex{T}`.
 
+    (x, stats) = cg(A, b, x0::AbstractVector; kwargs...)
+
+CG can be warm-started from an initial guess `x0` where `kwargs` are the same keyword arguments as above.
+
 The conjugate gradient method to solve the Hermitian linear system Ax = b of size n.
 
 The method does _not_ abort if A is not definite.
@@ -36,12 +40,6 @@ M also indicates the weighted norm in which residuals are measured.
 
 If `itmax=0`, the default number of iterations is set to `2 * n`.
 
-CG can be warm-started from an initial guess `x0` with
-
-    (x, stats) = cg(A, b, x0; kwargs...)
-
-where `kwargs` are the same keyword arguments as above.
-
 The callback is called as `callback(solver)` and should return `true` if the main loop should terminate,
 and `false` otherwise.
 
@@ -50,6 +48,10 @@ and `false` otherwise.
 * `A`: a linear operator that models a Hermitian positive definite matrix of dimension n;
 * `b`: a vector of length n.
 
+#### Optional argument
+
+* `x0`: a vector of length n that represents an initial guess of the solution x.
+
 #### Output arguments
 
 * `x`: a dense vector of length n;

src/cg_lanczos.jl

@@ -22,6 +22,10 @@ export cg_lanczos, cg_lanczos!
 `T` is an `AbstractFloat` such as `Float32`, `Float64` or `BigFloat`.
 `FC` is `T` or `Complex{T}`.
 
+    (x, stats) = cg_lanczos(A, b, x0::AbstractVector; kwargs...)
+
+CG-LANCZOS can be warm-started from an initial guess `x0` where `kwargs` are the same keyword arguments as above.
+
 The Lanczos version of the conjugate gradient method to solve the
 Hermitian linear system Ax = b of size n.
 
@@ -30,12 +34,6 @@ The method does _not_ abort if A is not definite.
 A preconditioner M may be provided in the form of a linear operator and is
 assumed to be Hermitian and positive definite.
 
-CG-LANCZOS can be warm-started from an initial guess `x0` with
-
-    (x, stats) = cg_lanczos(A, b, x0; kwargs...)
-
-where `kwargs` are the same keyword arguments as above.
-
 The callback is called as `callback(solver)` and should return `true` if the main loop should terminate,
 and `false` otherwise.
 
@@ -44,6 +42,10 @@ and `false` otherwise.
 * `A`: a linear operator that models a Hermitian matrix of dimension n;
 * `b`: a vector of length n.
 
+#### Optional argument
+
+* `x0`: a vector of length n that represents an initial guess of the solution x.
+
 #### Output arguments
 
 * `x`: a dense vector of length n;

src/cgs.jl

@@ -11,14 +11,18 @@
 export cgs, cgs!
 
 """
-    (x, stats) = cgs(A, b::AbstractVector{FC}; c::AbstractVector{FC}=b,
-                     M=I, N=I, atol::T=√eps(T), rtol::T=√eps(T),
-                     itmax::Int=0, verbose::Int=0, history::Bool=false,
-                     ldiv::Bool=false, callback=solver->false)
+    (x, stats) = cgs(A, b::AbstractVector{FC};
+                     c::AbstractVector{FC}=b, M=I, N=I, atol::T=√eps(T),
+                     rtol::T=√eps(T), itmax::Int=0, verbose::Int=0,
+                     history::Bool=false, ldiv::Bool=false, callback=solver->false)
 
 `T` is an `AbstractFloat` such as `Float32`, `Float64` or `BigFloat`.
 `FC` is `T` or `Complex{T}`.
 
+    (x, stats) = cgs(A, b, x0::AbstractVector; kwargs...)
+
+CGS can be warm-started from an initial guess `x0` where `kwargs` are the same keyword arguments as above.
+
 Solve the consistent linear system Ax = b of size n using CGS.
 CGS requires two initial vectors `b` and `c`.
 The relation `bᴴc ≠ 0` must be satisfied and by default `c = b`.
@@ -40,12 +44,6 @@ TFQMR and BICGSTAB were developed to remedy this difficulty.»
 
 This implementation allows a left preconditioner M and a right preconditioner N.
 
-CGS can be warm-started from an initial guess `x0` with
-
-    (x, stats) = cgs(A, b, x0; kwargs...)
-
-where `kwargs` are the same keyword arguments as above.
-
 The callback is called as `callback(solver)` and should return `true` if the main loop should terminate,
 and `false` otherwise.
 
@@ -54,6 +52,10 @@ and `false` otherwise.
 * `A`: a linear operator that models a matrix of dimension n;
 * `b`: a vector of length n.
 
+#### Optional argument
+
+* `x0`: a vector of length n that represents an initial guess of the solution x.
+
 #### Output arguments
 
 * `x`: a dense vector of length n;

src/cr.jl

@@ -16,13 +16,18 @@ export cr, cr!
 
 """
     (x, stats) = cr(A, b::AbstractVector{FC};
-                    M=I, atol::T=√eps(T), rtol::T=√eps(T), γ::T=√eps(T), itmax::Int=0,
-                    radius::T=zero(T), verbose::Int=0, linesearch::Bool=false, history::Bool=false,
+                    M=I, atol::T=√eps(T), rtol::T=√eps(T), γ::T=√eps(T),
+                    itmax::Int=0, radius::T=zero(T), verbose::Int=0,
+                    linesearch::Bool=false, history::Bool=false,
                     ldiv::Bool=false, callback=solver->false)
 
 `T` is an `AbstractFloat` such as `Float32`, `Float64` or `BigFloat`.
 `FC` is `T` or `Complex{T}`.
 
+    (x, stats) = cr(A, b, x0::AbstractVector; kwargs...)
+
+CR can be warm-started from an initial guess `x0` where `kwargs` are the same keyword arguments as above.
+
 A truncated version of Stiefel’s Conjugate Residual method to solve the Hermitian linear system Ax = b
 of size n or the least-squares problem min ‖b - Ax‖ if A is singular.
 The matrix A must be Hermitian semi-definite.
@@ -34,12 +39,6 @@ In a linesearch context, 'linesearch' must be set to 'true'.
 
 If `itmax=0`, the default number of iterations is set to `2 * n`.
 
-CR can be warm-started from an initial guess `x0` with
-
-    (x, stats) = cr(A, b, x0; kwargs...)
-
-where `kwargs` are the same keyword arguments as above.
-
 The callback is called as `callback(solver)` and should return `true` if the main loop should terminate,
 and `false` otherwise.
 
@@ -48,6 +47,10 @@ and `false` otherwise.
 * `A`: a linear operator that models a Hermitian positive definite matrix of dimension n;
 * `b`: a vector of length n.
 
+#### Optional argument
+
+* `x0`: a vector of length n that represents an initial guess of the solution x.
+
 #### Output arguments
 
 * `x`: a dense vector of length n;

src/diom.jl

@@ -11,15 +11,19 @@
 export diom, diom!
 
 """
-    (x, stats) = diom(A, b::AbstractVector{FC}; memory::Int=20,
-                      M=I, N=I, atol::T=√eps(T), rtol::T=√eps(T),
-                      reorthogonalization::Bool=false, itmax::Int=0,
-                      verbose::Int=0, history::Bool=false,
+    (x, stats) = diom(A, b::AbstractVector{FC};
+                      memory::Int=20, M=I, N=I, atol::T=√eps(T),
+                      rtol::T=√eps(T), reorthogonalization::Bool=false,
+                      itmax::Int=0, verbose::Int=0, history::Bool=false,
                       ldiv::Bool=false, callback=solver->false)
 
 `T` is an `AbstractFloat` such as `Float32`, `Float64` or `BigFloat`.
 `FC` is `T` or `Complex{T}`.
 
+    (x, stats) = diom(A, b, x0::AbstractVector; kwargs...)
+
+DIOM can be warm-started from an initial guess `x0` where `kwargs` are the same keyword arguments as above.
+
 Solve the consistent linear system Ax = b of size n using DIOM.
 
 DIOM only orthogonalizes the new vectors of the Krylov basis against the `memory` most recent vectors.
@@ -34,12 +38,6 @@ and indefinite systems of linear equations can be handled by this single algorit
 
 This implementation allows a left preconditioner M and a right preconditioner N.
 
-DIOM can be warm-started from an initial guess `x0` with
-
-    (x, stats) = diom(A, b, x0; kwargs...)
-
-where `kwargs` are the same keyword arguments as above.
-
 The callback is called as `callback(solver)` and should return `true` if the main loop should terminate,
 and `false` otherwise.
 
@@ -48,6 +46,10 @@ and `false` otherwise.
 * `A`: a linear operator that models a matrix of dimension n;
 * `b`: a vector of length n.
 
+#### Optional argument
+
+* `x0`: a vector of length n that represents an initial guess of the solution x.
+
 #### Output arguments
 
 * `x`: a dense vector of length n;

src/dqgmres.jl

@@ -11,15 +11,19 @@
 export dqgmres, dqgmres!
 
 """
-    (x, stats) = dqgmres(A, b::AbstractVector{FC}; memory::Int=20,
-                         M=I, N=I, atol::T=√eps(T), rtol::T=√eps(T),
-                         reorthogonalization::Bool=false, itmax::Int=0,
-                         verbose::Int=0, history::Bool=false,
+    (x, stats) = dqgmres(A, b::AbstractVector{FC};
+                         memory::Int=20, M=I, N=I, atol::T=√eps(T),
+                         rtol::T=√eps(T), reorthogonalization::Bool=false,
+                         itmax::Int=0, verbose::Int=0, history::Bool=false,
                          ldiv::Bool=false, callback=solver->false)
 
 `T` is an `AbstractFloat` such as `Float32`, `Float64` or `BigFloat`.
 `FC` is `T` or `Complex{T}`.
 
+    (x, stats) = dqgmres(A, b, x0::AbstractVector; kwargs...)
+
+DQGMRES can be warm-started from an initial guess `x0` where `kwargs` are the same keyword arguments as above.
+
 Solve the consistent linear system Ax = b of size n using DQGMRES.
 
 DQGMRES algorithm is based on the incomplete Arnoldi orthogonalization process
@@ -34,12 +38,6 @@ Partial reorthogonalization is available with the `reorthogonalization` option.
 
 This implementation allows a left preconditioner M and a right preconditioner N.
 
-DQGMRES can be warm-started from an initial guess `x0` with
-
-    (x, stats) = dqgmres(A, b, x0; kwargs...)
-
-where `kwargs` are the same keyword arguments as above.
-
 The callback is called as `callback(solver)` and should return `true` if the main loop should terminate,
 and `false` otherwise.
 
@@ -48,6 +46,10 @@ and `false` otherwise.
 * `A`: a linear operator that models a matrix of dimension n;
 * `b`: a vector of length n.
 
+#### Optional argument
+
+* `x0`: a vector of length n that represents an initial guess of the solution x.
+
 #### Output arguments
 
 * `x`: a dense vector of length n;