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.
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.
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.
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.
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.
ch.iters
Convergence status.
ch.isconverged
Stopping tolerances. (A Symbol key is needed to access)
ch[:tol]
Maximum number of iterations per restart. (Only on restarted methods)
nrests(ch)
Number of matrix-vectors and matrix-transposed-vector products.
nprods(ch)
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
+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.
ch.iters
Convergence status.
ch.isconverged
Stopping tolerances. (A Symbol key is needed to access)
ch[:tol]
Maximum number of iterations per restart. (Only on restarted methods)
nrests(ch)
Number of matrix-vectors and matrix-transposed-vector products.
nprods(ch)
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.
Fields
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.
Constructors
ConvergenceHistory()
-ConvergenceHistory(restart)
Create ConvergenceHistory with empty fields.
Arguments
restart: number of iterations per restart.
Plots
Supports plots using the Plots.jl package via a type recipe. Vectors are ploted as series and matrices as scatterplots.
Implements
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.
plot(ch)
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.