# Getting started

## Installation

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

`julia> Pkg.add("IterativeSolvers")`

## Interface

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`d`

th 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.

### 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`

.

## 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
```

`IterativeSolvers.ConvergenceHistory`

— TypeStore 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!`

### Plotting

`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.