Iterative linear solvers and preconditioners. Solves the linear problem

    A x = b

with respect to `x`. A must be an `n*n` non-singular matrix, and `x` and `b` are `n`-vectors. Note that the value of `x` is used as an initial guess, and the convergence can be improved by using a good guess.

### Iterative linear solvers

The solvers are modified versions of the Templates versions. All the solvers implement the interface {@link jmp.iter.linear.LinearSolver LinearSolver}, and its usage can be illustrated by an example:

    double[] solver(Matrix A, Vector x, Vector b) {
      LinearSolver solver = new CG();
      try {
        x = solver.solve(A, x, b);
      } catch (LinearNotConvergedException e) {
        System.err.println("Linear solver did not converge");
        System.err.println("Final residual = " + e.getResidual());
        System.err.println("Number of iterations = " + e.getIterations());
        System.err.print("Reason = ");
        if (e.getReason() == NotConvergedException.BREAKDOWN)
          System.err.println("breakdown");
        else if (e.getReason() == NotConvergedException.DIVERGENCE)
          System.err.println("divergence");
        else if (e.getReason() == NotConvergedException.ITERATIONS)
          System.err.println("too many iterations");
      }
      return State.BLAS.getArrayCopy(x);
    }

In this example, the solver {@link jmp.iter.linear.CG CG} was used. Other solvers include the following:

Solver | SPD | Transpose | Notes
--- | --- | --- | ---
{@link jmp.iter.linear.BiCG BiCG} |  | Yes |
{@link jmp.iter.linear.BiCGstab BiCGstab} |  |  |
{@link jmp.iter.linear.CG CG} | Yes |  |
{@link jmp.iter.linear.CGS CGS} |  |  |
{@link jmp.iter.linear.Chebyshev Chebyshev} | Yes |  | Needs extremal eigenvalues
{@link jmp.iter.linear.GMRES GMRES} |  |  | Restarted version
{@link jmp.iter.linear.IR IR} |  |  |
{@link jmp.iter.linear.QMR QMR} |  | Yes | Uses left and right preconditioning

SPD means that the matrix must be symmetrical, positive definite, while transpose means that transpose matrix/vector multiplication and preconditioning is necessary.

### Convergence criteria

{@link jmp.iter.linear.LinearIteration LinearIteration} monitors the iteration, and provides both convergence tracking and detection. There are two implementations of `LinearIteration`:

- {@link jmp.iter.linear.DefaultLinearIteration DefaultLinearIteration} - declares convergence when the current residual has decrease by a certain factor compared to the initial residual
- {@link jmp.iter.linear.MatrixLinearIteration MatrixLinearIteration} - as `DefaultLinearIteration`, but the matrix-norm to scale the initial residual

The method {@link jmp.iter.linear.LinearSolver#setIteration(jmp.iter.linear.LinearIteration) setIteration} is used to set a `LinearIteration`.

Another use of the iteration objects is in the monitoring they can perform. By default, no monitoring is done, but the method {@link jmp.iter.linear.LinearIteration#setIterationMonitor(jmp.iter.linear.LinearIterationMonitor) LinearIteration.setIterationMonitor} allows one to attach a monitor. The following are available:

- {@link jmp.iter.linear.ArrayLinearIterationMonitor ArrayLinearIterationMonitor} - stores the iteration progress in an array
- {@link jmp.iter.linear.OutputLinearIterationMonitor OutputLinearIterationMonitor} - outputs the information to a stream, by default `System.err`

An easy way to attach a monitor without changing the iteration object is the following:

    LinearSolver solver = new CG();
    solver.getIteration().setIterationMonitor(new OutputLinearIterationMonitor());

### Preconditioning

To speed up convergence of the iterative solvers, preconditioners are often necessary. Use the method {@link jmp.iter.linear.LinearSolver#setPreconditioner(jmp.iter.linear.Preconditioner) LinearSolver.setPreconditioner} to set the preconditioner. Available preconditoners are:

Preconditioner | Parallel | Notes
--- | --- | ---
{@link jmp.iter.linear.DiagonalPreconditioner DiagonalPreconditioner} | Yes |
{@link jmp.iter.linear.GaussSeidel GaussSeidel} |  |
{@link jmp.iter.linear.ICC ICC} |  | Optional fill-in and diagonal scaling
{@link jmp.iter.linear.ILU ILU} |  | Optional fill-in and diagonal scaling
{@link jmp.iter.linear.Jacobi Jacobi} | Yes |
{@link jmp.iter.linear.PolynomialPreconditioner PolynomialPreconditioner} | Yes |
{@link jmp.iter.linear.SOR SOR} |  |
{@link jmp.iter.linear.SSOR SSOR} |  |
{@link jmp.iter.linear.BlockDiagonalPreconditioner BlockDiagonalPreconditioner} | Yes | Needs sub-preconditioners
{@link jmp.iter.linear.Multigrid Multigrid} | Yes | Geometrical variant
{@link jmp.iter.linear.CholeskyPreconditioner CholeskyPreconditioner} |  | For sub-problems only
{@link jmp.iter.linear.LUPreconditioner LUPreconditioner} |  | For sub-problems only
{@link jmp.iter.linear.QRPreconditioner QRPreconditioner} |  | For sub-problems only
{@link jmp.iter.linear.CompositePreconditioner CompositePreconditioner} |  | Applies a sequence of preconditioners
{@link jmp.iter.linear.IdentityPreconditioner IdentityPreconditioner} |  | Default preconditioner, does nothing
{@link jmp.iter.linear.IterativeSolverPreconditioner IterativeSolverPreconditioner} | Yes | Has slack convergence criteria

For further details on the preconditioners, see the Templates page.