Add documentation for all keyword arguments

src/bicgstab.jl

@@ -18,9 +18,10 @@ 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,
+                          ldiv::Bool=false, atol::T=√eps(T),
+                          rtol::T=√eps(T), itmax::Int=0,
                           verbose::Int=0, history::Bool=false,
-                          ldiv::Bool=false, callback=solver->false, iostream::IO=kstdout)
+                          callback=solver->false, iostream::IO=kstdout)
 
 `T` is an `AbstractFloat` such as `Float32`, `Float64` or `BigFloat`.
 `FC` is `T` or `Complex{T}`.
@@ -59,6 +60,20 @@ and `false` otherwise.
 
 * `x0`: a vector of length n that represents an initial guess of the solution x.
 
+#### Keyword arguments
+
+* `c`: the second initial vector of length `n` required by the Lanczos biorthogonalization process;
+* `M`: linear operator that models a nonsingular matrix of size `n` used for left preconditioning;
+* `N`: linear operator that models a nonsingular matrix of size `n` used for right preconditioning;
+* `ldiv`: define whether the preconditioners use `ldiv!` or `mul!`;
+* `atol`: absolute stopping tolerance based on the residual norm;
+* `rtol`: relative stopping tolerance based on the residual norm;
+* `itmax`: the maximum number of iterations. If `itmax=0`, the default number of iterations is set to `2n`;
+* `verbose`: additional details can be displayed if verbose mode is enabled (verbose > 0). Information will be displayed every `verbose` iterations;
+* `history`: collect additional statistics on the run such as residual norms, or Aᴴ-residual norms;
+* `callback`: function or functor called as `callback(solver)` that returns `true` if the Krylov method should terminate, and `false` otherwise;
+* `iostream`: stream to which output is logged.
+
 #### Output arguments
 
 * `x`: a dense vector of length n;
@@ -99,10 +114,12 @@ function bicgstab!(solver :: BicgstabSolver{T,FC,S}, A, b :: AbstractVector{FC},
   return solver
 end
 
-function bicgstab!(solver :: BicgstabSolver{T,FC,S}, 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, iostream :: IO=kstdout) where {T <: AbstractFloat, FC <: FloatOrComplex{T}, S <: DenseVector{FC}}
+function bicgstab!(solver :: BicgstabSolver{T,FC,S}, A, b :: AbstractVector{FC};
+                   c :: AbstractVector{FC}=b, M=I, N=I,
+                   ldiv :: Bool=false, atol :: T=√eps(T),
+                   rtol :: T=√eps(T), itmax :: Int=0,
+                   verbose :: Int=0, history :: Bool=false,
+                   callback = solver -> false, iostream :: IO=kstdout) where {T <: AbstractFloat, FC <: FloatOrComplex{T}, S <: DenseVector{FC}}
 
   m, n = size(A)
   m == n || error("System must be square")

src/bilq.jl

@@ -14,10 +14,10 @@ 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, iostream::IO=kstdout)
+                      c::AbstractVector{FC}=b, transfer_to_bicg::Bool=true,
+                      atol::T=√eps(T), rtol::T=√eps(T), itmax::Int=0,
+                      verbose::Int=0, history::Bool=false,
+                      callback=solver->false, iostream::IO=kstdout)
 
 `T` is an `AbstractFloat` such as `Float32`, `Float64` or `BigFloat`.
 `FC` is `T` or `Complex{T}`.
@@ -46,6 +46,18 @@ and `false` otherwise.
 
 * `x0`: a vector of length n that represents an initial guess of the solution x.
 
+#### Keyword arguments
+
+* `c`: the second initial vector of length `n` required by the Lanczos biorthogonalization process;
+* `transfer_to_bicg`: transfer from the BiLQ point to the BiCG point, when it exists. The transfer is based on the residual norm;
+* `atol`: absolute stopping tolerance based on the residual norm;
+* `rtol`: relative stopping tolerance based on the residual norm;
+* `itmax`: the maximum number of iterations. If `itmax=0`, the default number of iterations is set to `2n`;
+* `verbose`: additional details can be displayed if verbose mode is enabled (verbose > 0). Information will be displayed every `verbose` iterations;
+* `history`: collect additional statistics on the run such as residual norms, or Aᴴ-residual norms;
+* `callback`: function or functor called as `callback(solver)` that returns `true` if the Krylov method should terminate, and `false` otherwise;
+* `iostream`: stream to which output is logged.
+
 #### Output arguments
 
 * `x`: a dense vector of length n;
@@ -86,9 +98,10 @@ function bilq!(solver :: BilqSolver{T,FC,S}, A, b :: AbstractVector{FC}, x0 :: A
   return solver
 end
 
-function bilq!(solver :: BilqSolver{T,FC,S}, 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,
+function bilq!(solver :: BilqSolver{T,FC,S}, A, b :: AbstractVector{FC};
+               c :: AbstractVector{FC}=b, transfer_to_bicg :: Bool=true,
+               atol :: T=√eps(T), rtol :: T=√eps(T), itmax :: Int=0,
+               verbose :: Int=0, history :: Bool=false,
                callback = solver -> false, iostream :: IO=kstdout) where {T <: AbstractFloat, FC <: FloatOrComplex{T}, S <: DenseVector{FC}}
 
   m, n = size(A)

src/bilqr.jl

@@ -14,8 +14,9 @@ export bilqr, bilqr!
 
 """
     (x, y, stats) = bilqr(A, b::AbstractVector{FC}, c::AbstractVector{FC};
-                          atol::T=√eps(T), rtol::T=√eps(T), transfer_to_bicg::Bool=true,
-                          itmax::Int=0, verbose::Int=0, history::Bool=false,
+                          transfer_to_bicg::Bool=true, atol::T=√eps(T),
+                          rtol::T=√eps(T), itmax::Int=0,
+                          verbose::Int=0, history::Bool=false,
                           callback=solver->false, iostream::IO=kstdout)
 
 `T` is an `AbstractFloat` such as `Float32`, `Float64` or `BigFloat`.
@@ -51,6 +52,17 @@ and `false` otherwise.
 * `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.
 
+#### Keyword arguments
+
+* `transfer_to_bicg`: transfer from the BiLQ point to the BiCG point, when it exists. The transfer is based on the residual norm;
+* `atol`: absolute stopping tolerance based on the residual norm;
+* `rtol`: relative stopping tolerance based on the residual norm;
+* `itmax`: the maximum number of iterations. If `itmax=0`, the default number of iterations is set to `2n`;
+* `verbose`: additional details can be displayed if verbose mode is enabled (verbose > 0). Information will be displayed every `verbose` iterations;
+* `history`: collect additional statistics on the run such as residual norms, or Aᴴ-residual norms;
+* `callback`: function or functor called as `callback(solver)` that returns `true` if the Krylov method should terminate, and `false` otherwise;
+* `iostream`: stream to which output is logged.
+
 #### Output arguments
 
 * `x`: a dense vector of length n;
@@ -93,8 +105,9 @@ function bilqr!(solver :: BilqrSolver{T,FC,S}, A, b :: AbstractVector{FC}, c ::
 end
 
 function bilqr!(solver :: BilqrSolver{T,FC,S}, A, b :: AbstractVector{FC}, c :: AbstractVector{FC};
-                atol :: T=√eps(T), rtol :: T=√eps(T), transfer_to_bicg :: Bool=true,
-                itmax :: Int=0, verbose :: Int=0, history :: Bool=false,
+                transfer_to_bicg :: Bool=true, atol :: T=√eps(T),
+                rtol :: T=√eps(T), itmax :: Int=0,
+                verbose :: Int=0, history :: Bool=false,
                 callback = solver -> false, iostream :: IO=kstdout) where {T <: AbstractFloat, FC <: FloatOrComplex{T}, S <: DenseVector{FC}}
 
   m, n = size(A)

src/cg.jl

@@ -15,13 +15,13 @@
 
 export cg, cg!
 
-
 """
     (x, stats) = cg(A, b::AbstractVector{FC};
-                    M=I, atol::T=√eps(T), rtol::T=√eps(T),
-                    itmax::Int=0, radius::T=zero(T), linesearch::Bool=false,
+                    M=I, ldiv::Bool=false, radius::T=zero(T),
+                    linesearch::Bool=false, atol::T=√eps(T),
+                    rtol::T=√eps(T), itmax::Int=0,
                     verbose::Int=0, history::Bool=false,
-                    ldiv::Bool=false, callback=solver->false, iostream::IO=kstdout)
+                    callback=solver->false, iostream::IO=kstdout)
 
 `T` is an `AbstractFloat` such as `Float32`, `Float64` or `BigFloat`.
 `FC` is `T` or `Complex{T}`.
@@ -52,6 +52,20 @@ and `false` otherwise.
 
 * `x0`: a vector of length n that represents an initial guess of the solution x.
 
+#### Keyword arguments
+
+* `M`: linear operator that models a Hermitian positive-definite matrix of size `n` used for centered preconditioning;
+* `ldiv`: define whether the preconditioner uses `ldiv!` or `mul!`;
+* `radius`: add the trust-region constraint ‖x‖ ≤ `radius` if `radius > 0`. Useful to compute a step in a trust-region method for optimization;
+* `linesearch`: if `true`, indicate that the solution is to be used in an inexact Newton method with linesearch. If negative curvature is detected at iteration k > 0, the solution of iteration k-1 is returned. If negative curvature is detected at iteration 0, the right-hand side is returned (i.e., the negative gradient);
+* `atol`: absolute stopping tolerance based on the residual norm;
+* `rtol`: relative stopping tolerance based on the residual norm;
+* `itmax`: the maximum number of iterations. If `itmax=0`, the default number of iterations is set to `2n`;
+* `verbose`: additional details can be displayed if verbose mode is enabled (verbose > 0). Information will be displayed every `verbose` iterations;
+* `history`: collect additional statistics on the run such as residual norms, or Aᴴ-residual norms;
+* `callback`: function or functor called as `callback(solver)` that returns `true` if the Krylov method should terminate, and `false` otherwise;
+* `iostream`: stream to which output is logged.
+
 #### Output arguments
 
 * `x`: a dense vector of length n;
@@ -92,10 +106,11 @@ function cg!(solver :: CgSolver{T,FC,S}, A, b :: AbstractVector{FC}, x0 :: Abstr
 end
 
 function cg!(solver :: CgSolver{T,FC,S}, A, b :: AbstractVector{FC};
-             M=I, atol :: T=√eps(T), rtol :: T=√eps(T),
-             itmax :: Int=0, radius :: T=zero(T), linesearch :: Bool=false,
+             M=I, ldiv :: Bool=false, radius :: T=zero(T),
+             linesearch :: Bool=false, atol :: T=√eps(T),
+             rtol :: T=√eps(T), itmax :: Int=0,
              verbose :: Int=0, history :: Bool=false,
-             ldiv :: Bool=false, callback = solver -> false, iostream :: IO=kstdout) where {T <: AbstractFloat, FC <: FloatOrComplex{T}, S <: DenseVector{FC}}
+             callback = solver -> false, iostream :: IO=kstdout) where {T <: AbstractFloat, FC <: FloatOrComplex{T}, S <: DenseVector{FC}}
 
   linesearch && (radius > 0) && error("`linesearch` set to `true` but trust-region radius > 0")
 

src/cg_lanczos.jl

@@ -12,12 +12,13 @@
 
 export cg_lanczos, cg_lanczos!
 
-
 """
     (x, stats) = cg_lanczos(A, b::AbstractVector{FC};
-                            M=I, atol::T=√eps(T), rtol::T=√eps(T), itmax::Int=0,
-                            check_curvature::Bool=false, verbose::Int=0, history::Bool=false,
-                            ldiv::Bool=false, callback=solver->false, iostream::IO=kstdout)
+                            M=I, ldiv::Bool=false,
+                            check_curvature::Bool=false, atol::T=√eps(T),
+                            rtol::T=√eps(T), itmax::Int=0,
+                            verbose::Int=0, history::Bool=false,
+                            callback=solver->false, iostream::IO=kstdout)
 
 `T` is an `AbstractFloat` such as `Float32`, `Float64` or `BigFloat`.
 `FC` is `T` or `Complex{T}`.
@@ -46,6 +47,19 @@ and `false` otherwise.
 
 * `x0`: a vector of length n that represents an initial guess of the solution x.
 
+#### Keyword arguments
+
+* `M`: linear operator that models a Hermitian positive-definite matrix of size `n` used for centered preconditioning;
+* `ldiv`: define whether the preconditioner uses `ldiv!` or `mul!`;
+* `check_curvature`: if `true`, check that the curvature of the quadratic along the search direction is positive, and abort if not, unless `linesearch` is also `true`;
+* `atol`: absolute stopping tolerance based on the residual norm;
+* `rtol`: relative stopping tolerance based on the residual norm;
+* `itmax`: the maximum number of iterations. If `itmax=0`, the default number of iterations is set to `2n`;
+* `verbose`: additional details can be displayed if verbose mode is enabled (verbose > 0). Information will be displayed every `verbose` iterations;
+* `history`: collect additional statistics on the run such as residual norms, or Aᴴ-residual norms;
+* `callback`: function or functor called as `callback(solver)` that returns `true` if the Krylov method should terminate, and `false` otherwise;
+* `iostream`: stream to which output is logged.
+
 #### Output arguments
 
 * `x`: a dense vector of length n;
@@ -87,9 +101,11 @@ function cg_lanczos!(solver :: CgLanczosSolver{T,FC,S}, A, b :: AbstractVector{F
 end
 
 function cg_lanczos!(solver :: CgLanczosSolver{T,FC,S}, A, b :: AbstractVector{FC};
-                     M=I, atol :: T=√eps(T), rtol :: T=√eps(T), itmax :: Int=0,
-                     check_curvature :: Bool=false, verbose :: Int=0, history :: Bool=false,
-                     ldiv :: Bool=false, callback = solver -> false, iostream :: IO=kstdout) where {T <: AbstractFloat, FC <: FloatOrComplex{T}, S <: DenseVector{FC}}
+                     M=I, ldiv :: Bool=false,
+                     check_curvature :: Bool=false, atol :: T=√eps(T),
+                     rtol :: T=√eps(T), itmax :: Int=0,
+                     verbose :: Int=0, history :: Bool=false,
+                     callback = solver -> false, iostream :: IO=kstdout) where {T <: AbstractFloat, FC <: FloatOrComplex{T}, S <: DenseVector{FC}}
 
   m, n = size(A)
   m == n || error("System must be square")

src/cg_lanczos_shift.jl

@@ -13,14 +13,13 @@
 
 export cg_lanczos_shift, cg_lanczos_shift!
 
-
 """
     (x, stats) = cg_lanczos_shift(A, b::AbstractVector{FC}, shifts::AbstractVector{T};
-                                  M=I, atol::T=√eps(T), rtol::T=√eps(T),
-                                  itmax::Int=0, check_curvature::Bool=false,
+                                  M=I, ldiv::Bool=false,
+                                  check_curvature::Bool=false, atol::T=√eps(T),
+                                  rtol::T=√eps(T), itmax::Int=0,
                                   verbose::Int=0, history::Bool=false,
-                                  ldiv::Bool=false, callback=solver->false,
-                                  iostream::IO=kstdout)
+                                  callback=solver->false, iostream::IO=kstdout)
 
 `T` is an `AbstractFloat` such as `Float32`, `Float64` or `BigFloat`.
 `FC` is `T` or `Complex{T}`.
@@ -44,6 +43,19 @@ and `false` otherwise.
 * `b`: a vector of length n;
 * `shifts`: a vector of length p.
 
+#### Keyword arguments
+
+* `M`: linear operator that models a Hermitian positive-definite matrix of size `n` used for centered preconditioning;
+* `ldiv`: define whether the preconditioner uses `ldiv!` or `mul!`;
+* `check_curvature`: if `true`, check that the curvature of the quadratic along the search direction is positive, and abort if not, unless `linesearch` is also `true`;
+* `atol`: absolute stopping tolerance based on the residual norm;
+* `rtol`: relative stopping tolerance based on the residual norm;
+* `itmax`: the maximum number of iterations. If `itmax=0`, the default number of iterations is set to `2n`;
+* `verbose`: additional details can be displayed if verbose mode is enabled (verbose > 0). Information will be displayed every `verbose` iterations;
+* `history`: collect additional statistics on the run such as residual norms, or Aᴴ-residual norms;
+* `callback`: function or functor called as `callback(solver)` that returns `true` if the Krylov method should terminate, and `false` otherwise;
+* `iostream`: stream to which output is logged.
+
 #### Output arguments
 
 * `x`: a vector of p dense vectors, each one of length n;
@@ -73,11 +85,11 @@ See [`CgLanczosShiftSolver`](@ref) for more details about the `solver`.
 function cg_lanczos_shift! end
 
 function cg_lanczos_shift!(solver :: CgLanczosShiftSolver{T,FC,S}, A, b :: AbstractVector{FC}, shifts :: AbstractVector{T};
-                           M=I, atol :: T=√eps(T), rtol :: T=√eps(T),
-                           itmax :: Int=0, check_curvature :: Bool=false,
+                           M=I, ldiv :: Bool=false,
+                           check_curvature :: Bool=false, atol :: T=√eps(T),
+                           rtol :: T=√eps(T), itmax :: Int=0,
                            verbose :: Int=0, history :: Bool=false,
-                           ldiv :: Bool=false, callback = solver -> false,
-                           iostream :: IO=kstdout) where {T <: AbstractFloat, FC <: FloatOrComplex{T}, S <: DenseVector{FC}}
+                           callback = solver -> false, iostream :: IO=kstdout) where {T <: AbstractFloat, FC <: FloatOrComplex{T}, S <: DenseVector{FC}}
 
   m, n = size(A)
   m == n || error("System must be square")