Improve the docstrings of Krylov.jl

src/bicgstab.jl

@@ -25,7 +25,7 @@ export bicgstab, bicgstab!
 
 `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.
@@ -44,12 +44,12 @@ BICGSTAB stops when `itmax` iterations are reached or when `‖rₖ‖ ≤ atol
 
 #### Input arguments
 
-* `A`: a linear operator that models a matrix of dimension n;
-* `b`: a vector of length n.
+* `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.
+* `x0`: a vector of length `n` that represents an initial guess of the solution `x`.
 
 #### Keyword arguments
 
@@ -68,7 +68,7 @@ BICGSTAB stops when `itmax` iterations are reached or when `‖rₖ‖ ≤ atol
 
 #### Output arguments
 
-* `x`: a dense vector of length n;
+* `x`: a dense vector of length `n`;
 * `stats`: statistics collected on the run in a [`SimpleStats`](@ref) structure.
 
 #### References

src/bilq.jl

@@ -35,12 +35,12 @@ BiLQ requires support for `adjoint(M)` and `adjoint(N)` if preconditioners are p
 
 #### Input arguments
 
-* `A`: a linear operator that models a matrix of dimension n;
-* `b`: a vector of length n.
+* `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.
+* `x0`: a vector of length `n` that represents an initial guess of the solution `x`.
 
 #### Keyword arguments
 
@@ -60,7 +60,7 @@ BiLQ requires support for `adjoint(M)` and `adjoint(N)` if preconditioners are p
 
 #### Output arguments
 
-* `x`: a dense vector of length n;
+* `x`: a dense vector of length `n`;
 * `stats`: statistics collected on the run in a [`SimpleStats`](@ref) structure.
 
 #### References

src/bilqr.jl

@@ -37,14 +37,14 @@ QMR is used for solving dual system `Aᴴy = c` of size n.
 
 #### Input arguments
 
-* `A`: a linear operator that models a matrix of dimension n;
-* `b`: a vector of length n;
-* `c`: a vector of length n.
+* `A`: a linear operator that models a matrix of dimension `n`;
+* `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.
+* `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
 
@@ -60,8 +60,8 @@ QMR is used for solving dual system `Aᴴy = c` of size n.
 
 #### Output arguments
 
-* `x`: a dense vector of length n;
-* `y`: a dense vector of length n;
+* `x`: a dense vector of length `n`;
+* `y`: a dense vector of length `n`;
 * `stats`: statistics collected on the run in an [`AdjointStats`](@ref) structure.
 
 #### Reference

src/block_gmres.jl

@@ -24,12 +24,12 @@ Solve the linear system AX = B of size n with p right-hand sides using block-GMR
 
 #### Input arguments
 
-* `A`: a linear operator that models a matrix of dimension n;
-* `B`: a matrix of size n × p.
+* `A`: a linear operator that models a matrix of dimension `n`;
+* `B`: a matrix of size `n × p`.
 
 #### Optional argument
 
-* `X0`: a matrix of size n × p that represents an initial guess of the solution X.
+* `X0`: a matrix of size `n × p` that represents an initial guess of the solution `X`.
 
 #### Keyword arguments
 
@@ -50,7 +50,7 @@ Solve the linear system AX = B of size n with p right-hand sides using block-GMR
 
 #### Output arguments
 
-* `X`: a dense matrix of size n × p;
+* `X`: a dense matrix of size `n × p`;
 * `stats`: statistics collected on the run in a [`SimpleStats`](@ref) structure.
 """
 function block_gmres end

src/block_krylov_processes.jl

@@ -3,8 +3,8 @@
 
 #### Input arguments
 
-* `A`: a linear operator that models an Hermitian matrix of dimension n;
-* `B`: a matrix of size n × p;
+* `A`: a linear operator that models an Hermitian matrix of dimension `n`;
+* `B`: a matrix of size `n × p`;
 * `k`: the number of iterations of the block Hermitian Lanczos process.
 
 #### Keyword arguments
@@ -13,9 +13,9 @@
 
 #### Output arguments
 
-* `V`: a dense n × p(k+1) matrix;
-* `Ψ`: a dense p × p upper triangular matrix such that V₁Ψ = B;
-* `T`: a sparse p(k+1) × pk block tridiagonal matrix with a bandwidth p.
+* `V`: a dense `n × p(k+1)` matrix;
+* `Ψ`: a dense `p × p` upper triangular matrix such that `V₁Ψ = B`;
+* `T`: a sparse `p(k+1) × pk` block tridiagonal matrix with a bandwidth `p`.
 """
 function hermitian_lanczos(A, B::AbstractMatrix{FC}, k::Int; algo::String="householder") where FC <: FloatOrComplex
   m, n = size(A)
@@ -101,19 +101,19 @@ end
 
 #### Input arguments
 
-* `A`: a linear operator that models a square matrix of dimension n;
-* `B`: a matrix of size n × p;
-* `C`: a matrix of size n × p;
+* `A`: a linear operator that models a square matrix of dimension `n`;
+* `B`: a matrix of size `n × p`;
+* `C`: a matrix of size `n × p`;
 * `k`: the number of iterations of the block non-Hermitian Lanczos process.
 
 #### Output arguments
 
-* `V`: a dense n × p(k+1) matrix;
-* `Ψ`: a dense p × p upper triangular matrix such that V₁Ψ = B;
-* `T`: a sparse p(k+1) × pk block tridiagonal matrix with a bandwidth p;
-* `U`: a dense n × p(k+1) matrix;
-* `Φᴴ`: a dense p × p upper triangular matrix such that U₁Φᴴ = C;
-* `Tᴴ`: a sparse p(k+1) × pk block tridiagonal matrix with a bandwidth p.
+* `V`: a dense `n × p(k+1)` matrix;
+* `Ψ`: a dense `p × p` upper triangular matrix such that `V₁Ψ = B`;
+* `T`: a sparse `p(k+1) × pk` block tridiagonal matrix with a bandwidth `p`;
+* `U`: a dense `n × p(k+1)` matrix;
+* `Φᴴ`: a dense `p × p` upper triangular matrix such that `U₁Φᴴ = C`;
+* `Tᴴ`: a sparse `p(k+1) × pk` block tridiagonal matrix with a bandwidth `p`.
 """
 function nonhermitian_lanczos(A, B::AbstractMatrix{FC}, C::AbstractMatrix{FC}, k::Int) where FC <: FloatOrComplex
   m, n = size(A)
@@ -231,8 +231,8 @@ end
 
 #### Input arguments
 
-* `A`: a linear operator that models a square matrix of dimension n;
-* `B`: a matrix of size n × p;
+* `A`: a linear operator that models a square matrix of dimension `n`;
+* `B`: a matrix of size `n × p`;
 * `k`: the number of iterations of the block Arnoldi process.
 
 #### Keyword arguments
@@ -242,9 +242,9 @@ end
 
 #### Output arguments
 
-* `V`: a dense n × p(k+1) matrix;
-* `Γ`: a dense p × p upper triangular matrix such that V₁Γ = B;
-* `H`: a dense p(k+1) × pk block upper Hessenberg matrix with a lower bandwidth p.
+* `V`: a dense `n × p(k+1)` matrix;
+* `Γ`: a dense `p × p` upper triangular matrix such that `V₁Γ = B`;
+* `H`: a dense `p(k+1) × pk` block upper Hessenberg matrix with a lower bandwidth `p`.
 """
 function arnoldi(A, B::AbstractMatrix{FC}, k::Int; algo::String="householder", reorthogonalization::Bool=false) where FC <: FloatOrComplex
   m, n = size(A)
@@ -308,8 +308,8 @@ end
 
 #### Input arguments
 
-* `A`: a linear operator that models a matrix of dimension m × n;
-* `B`: a matrix of size m × p;
+* `A`: a linear operator that models a matrix of dimension `m × n`;
+* `B`: a matrix of size `m × p`;
 * `k`: the number of iterations of the block Golub-Kahan process.
 
 #### Keyword argument
@@ -318,10 +318,10 @@ end
 
 #### Output arguments
 
-* `V`: a dense n × p(k+1) matrix;
-* `U`: a dense m × p(k+1) matrix;
-* `Ψ`: a dense p × p upper triangular matrix such that U₁Ψ = B;
-* `L`: a sparse p(k+1) × p(k+1) block lower bidiagonal matrix with a lower bandwidth p.
+* `V`: a dense `n × p(k+1)` matrix;
+* `U`: a dense `m × p(k+1)` matrix;
+* `Ψ`: a dense `p × p` upper triangular matrix such that `U₁Ψ = B`;
+* `L`: a sparse `p(k+1) × p(k+1)` block lower bidiagonal matrix with a lower bandwidth `p`.
 """
 function golub_kahan(A, B::AbstractMatrix{FC}, k::Int; algo::String="householder") where FC <: FloatOrComplex
   m, n = size(A)
@@ -421,9 +421,9 @@ end
 
 #### Input arguments
 
-* `A`: a linear operator that models a matrix of dimension m × n;
-* `B`: a matrix of size m × p;
-* `C`: a matrix of size n × p;
+* `A`: a linear operator that models a matrix of dimension `m × n`;
+* `B`: a matrix of size `m × p`;
+* `C`: a matrix of size `n × p`;
 * `k`: the number of iterations of the block Saunders-Simon-Yip process.
 
 #### Keyword argument
@@ -432,12 +432,12 @@ end
 
 #### Output arguments
 
-* `V`: a dense m × p(k+1) matrix;
-* `Ψ`: a dense p × p upper triangular matrix such that V₁Ψ = B;
-* `T`: a sparse p(k+1) × pk block tridiagonal matrix with a bandwidth p;
-* `U`: a dense n × p(k+1) matrix;
-* `Φᴴ`: a dense p × p upper triangular matrix such that U₁Φᴴ = C;
-* `Tᴴ`: a sparse p(k+1) × pk block tridiagonal matrix with a bandwidth p.
+* `V`: a dense `m × p(k+1)` matrix;
+* `Ψ`: a dense `p × p` upper triangular matrix such that `V₁Ψ = B`;
+* `T`: a sparse `p(k+1) × pk` block tridiagonal matrix with a bandwidth `p`;
+* `U`: a dense `n × p(k+1)` matrix;
+* `Φᴴ`: a dense `p × p` upper triangular matrix such that `U₁Φᴴ = C`;
+* `Tᴴ`: a sparse `p(k+1) × pk` block tridiagonal matrix with a bandwidth `p`.
 """
 function saunders_simon_yip(A, B::AbstractMatrix{FC}, C::AbstractMatrix{FC}, k::Int; algo::String="householder") where FC <: FloatOrComplex
   m, n = size(A)
@@ -573,12 +573,12 @@ end
 
 #### Output arguments
 
-* `V`: a dense m × p(k+1) matrix;
-* `Γ`: a dense p × p upper triangular matrix such that V₁Γ = D;
-* `H`: a dense p(k+1) × pk block upper Hessenberg matrix with a lower bandwidth p;
-* `U`: a dense n × p(k+1) matrix;
-* `Λ`: a dense p × p upper triangular matrix such that U₁Λ = C;
-* `F`: a dense p(k+1) × pk block upper Hessenberg matrix with a lower bandwidth p.
+* `V`: a dense `m × p(k+1)` matrix;
+* `Γ`: a dense `p × p` upper triangular matrix such that `V₁Γ = D`;
+* `H`: a dense `p(k+1) × pk` block upper Hessenberg matrix with a lower bandwidth `p`;
+* `U`: a dense `n × p(k+1)` matrix;
+* `Λ`: a dense `p × p` upper triangular matrix such that `U₁Λ = C`;
+* `F`: a dense `p(k+1) × pk` block upper Hessenberg matrix with a lower bandwidth `p`.
 """
 function montoison_orban(A, B, D::AbstractMatrix{FC}, C::AbstractMatrix{FC}, k::Int; algo::String="householder", reorthogonalization::Bool=false) where FC <: FloatOrComplex
   m, n = size(A)

src/block_krylov_utils.jl

@@ -1,13 +1,16 @@
 # """
-# Gram-Schmidt orthogonalization for a reduced QR decomposition:
-# Q, R = gs(A)
+#     Q, R = gs(A)
 #
-# Input :
-# A an n-by-k matrix, n ≥ k
+# Gram-Schmidt orthogonalization for a reduced QR decomposition.
 #
-# Output :
-# Q an n-by-k orthonormal matrix: QᴴQ = Iₖ
-# R an k-by-k upper triangular matrix: QR = A
+# #### Input argument
+#
+# * `A`: an n-by-k matrix, n ≥ k
+#
+# #### Output arguments
+#
+# * `Q` an n-by-k orthonormal matrix: QᴴQ = Iₖ
+# * `R` an k-by-k upper triangular matrix: QR = A
 # """
 function gs(A::AbstractMatrix{FC}) where FC <: FloatOrComplex
   n, k = size(A)

src/car.jl

@@ -32,12 +32,12 @@ The estimates computed every iteration are ‖Mrₖ‖₂ and ‖AMrₖ‖_M.
 
 #### Input arguments
 
-* `A`: a linear operator that models a Hermitian positive definite matrix of dimension n;
-* `b`: a vector of length n.
+* `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.
+* `x0`: a vector of length `n` that represents an initial guess of the solution `x`.
 
 #### Keyword arguments
 
@@ -54,10 +54,11 @@ The estimates computed every iteration are ‖Mrₖ‖₂ and ‖AMrₖ‖_M.
 
 #### Output arguments
 
-* `x`: a dense vector of length n;
+* `x`: a dense vector of length `n`;
 * `stats`: statistics collected on the run in a [`SimpleStats`](@ref) structure.
 
 #### Reference
+
 * A. Montoison, D. Orban and M. A. Saunders, [*MinAres: An Iterative Solver for Symmetric Linear Systems*](https://doi.org/10.13140/RG.2.2.18163.91683), Cahier du GERAD G-2023-40, GERAD, Montréal, 2023.
 """
 function car end

src/cg.jl

@@ -37,12 +37,12 @@ M also indicates the weighted norm in which residuals are measured.
 
 #### Input arguments
 
-* `A`: a linear operator that models a Hermitian positive definite matrix of dimension n;
-* `b`: a vector of length n.
+* `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.
+* `x0`: a vector of length `n` that represents an initial guess of the solution `x`.
 
 #### Keyword arguments
 
@@ -61,7 +61,7 @@ M also indicates the weighted norm in which residuals are measured.
 
 #### Output arguments
 
-* `x`: a dense vector of length n;
+* `x`: a dense vector of length `n`;
 * `stats`: statistics collected on the run in a [`SimpleStats`](@ref) structure.
 
 #### Reference

src/cg_lanczos.jl

@@ -34,12 +34,12 @@ The method does _not_ abort if A is not definite.
 
 #### Input arguments
 
-* `A`: a linear operator that models a Hermitian matrix of dimension n;
-* `b`: a vector of length n.
+* `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.
+* `x0`: a vector of length `n` that represents an initial guess of the solution `x`.
 
 #### Keyword arguments
 
@@ -57,7 +57,7 @@ The method does _not_ abort if A is not definite.
 
 #### Output arguments
 
-* `x`: a dense vector of length n;
+* `x`: a dense vector of length `n`;
 * `stats`: statistics collected on the run in a [`LanczosStats`](@ref) structure.
 
 #### References

src/cg_lanczos_shift.jl

@@ -33,9 +33,9 @@ of size n. The method does _not_ abort if A + αI is not definite.
 
 #### Input arguments
 
-* `A`: a linear operator that models a Hermitian matrix of dimension n;
-* `b`: a vector of length n;
-* `shifts`: a vector of length p.
+* `A`: a linear operator that models a Hermitian matrix of dimension `n`;
+* `b`: a vector of length `n`;
+* `shifts`: a vector of length `p`.
 
 #### Keyword arguments
 
@@ -53,7 +53,7 @@ of size n. The method does _not_ abort if A + αI is not definite.
 
 #### Output arguments
 
-* `x`: a vector of p dense vectors, each one of length n;
+* `x`: a vector of `p` dense vectors, each one of length `n`;
 * `stats`: statistics collected on the run in a [`LanczosShiftStats`](@ref) structure.
 
 #### References