Getting started


The package can be installed via Julia's package manager.

julia> Pkg.add("IterativeSolvers")


Virtually all solvers have the common function declarations:

solver(A, args...; kwargs...)
solver!(x, A, args...; kwargs...)

where A is a linear operator and x an initial guess. The second declaration also updates x in-place.

Explicit matrices and the matrix-free approach

Rather than constructing an explicit matrix A of the type Matrix or SparseMatrixCSC, it is also possible to pass a general linear operator that performs matrix operations implicitly. This is called the matrix-free approach.

For matrix-free types of A the following interface is expected to be defined:

  • A*v computes the matrix-vector product on a v::AbstractVector;
  • mul!(y, A, v) computes the matrix-vector product on a v::AbstractVector in-place;
  • eltype(A) returns the element type implicit in the equivalent matrix representation of A;
  • size(A, d) returns the nominal dimensions along the dth axis in the equivalent matrix representation of A.
Matrix-free with LinearMaps.jl

We strongly recommend LinearMaps.jl for matrix-free linear operators, as it implements the above methods already for you; you just have to write the action of the linear map.

Additional arguments

Keyword names will vary depending on the method, however some of them will always have the same spelling:

  • tol: (relative) stopping tolerance of the method;
  • verbose: print information during the iterations;
  • maxiter: maximum number of allowed iterations;
  • Pl and Pr: left and right preconditioner. See Preconditioning;
  • log::Bool = false: output an extra element of type ConvergenceHistory containing the convergence history.

log keyword

Most solvers contain the log keyword. This is to be used when obtaining more information is required, to use it place the set log to true.

x, ch = cg(Master, rand(10, 10), rand(10) log=true)
svd, L, ch = svdl(Master, rand(100, 100), log=true)

The function will now return one more parameter of type ConvergenceHistory.


A ConvergenceHistory instance stores information of a solver.

Number of iterations.


Convergence status.


Stopping tolerances. (A Symbol key is needed to access)


Maximum number of iterations per restart. (Only on restarted methods)


Number of matrix-vectors and matrix-transposed-vector products.


Data stored on each iteration, accessed information can be either a vector or matrix. This data can be a lot of things, most commonly residual. (A Symbol key is needed to access)

ch[:resnorm] #Vector or Matrix
ch[:resnorm, x] #Vector or Matrix element
ch[:resnorm, x, y] #Matrix element

Store general and in-depth information about an iterative method.


mvps::Int: number of matrix vector products.

mtvps::Int: number of transposed matrix-vector products

iters::Int: iterations taken by the method.

restart::T: restart relevant information.

  • T == Int: iterations per restart.
  • T == Nothing: methods without restarts.

isconverged::Bool: convergence of the method.

data::Dict{Symbol,Any}: Stores all the information stored during the method execution. It stores tolerances, residuals and other information, e.g. Ritz values in svdl.



Create ConvergenceHistory with empty fields.


restart: number of iterations per restart.


Supports plots using the Plots.jl package via a type recipe. Vectors are ploted as series and matrices as scatterplots.


Base: getindex, setindex!, push!



ConvergeHistory provides a recipe to use with the package Plots.jl, this makes it really easy to plot on different plot backends. There are two recipes provided:

One for the whole ConvergenceHistory.


The other one to plot data binded to a key.

_, ch = gmres(rand(10,10), rand(10), maxiter = 100, log=true)
plot(ch, :resnorm, sep = :blue)

Plot additional keywords

sep::Symbol = :white: color of the line separator in restarted methods.