Package org.apache.commons.math3.linear

# Class PreconditionedIterativeLinearSolver

java.lang.Object
org.apache.commons.math3.linear.IterativeLinearSolver
org.apache.commons.math3.linear.PreconditionedIterativeLinearSolver

Direct Known Subclasses:
  `ConjugateGradient`, `SymmLQ`

public abstract class PreconditionedIterativeLinearSolver extends IterativeLinearSolver

This abstract class defines preconditioned iterative solvers. When A is ill-conditioned, instead of solving system A · x = b directly, it is preferable to solve either

(M · A) · x = M · b
(left preconditioning), or
(A · M) · y = b, followed by M · y = x
(right preconditioning), where M approximates in some way A-1, while matrix-vector products of the type M · y remain comparatively easy to compute. In this library, M (not M-1!) is called the preconditionner.

Concrete implementations of this abstract class must be provided with the preconditioner M, as a `RealLinearOperator`.

Since:
  3.0

## Constructor Summary

Constructors
Constructor
Description
`PreconditionedIterativeLinearSolver(int maxIterations)`
Creates a new instance of this class, with default iteration manager.
`PreconditionedIterativeLinearSolver(IterationManager manager)`
Creates a new instance of this class, with custom iteration manager.

## Method Summary

Modifier and Type
Method
Description
`protected static void`
`checkParameters(RealLinearOperator a, RealLinearOperator m, RealVector b, RealVector x0)`
Performs all dimension checks on the parameters of `solve` and `solveInPlace`, and throws an exception if one of the checks fails.
`RealVector`
`solve(RealLinearOperator a, RealLinearOperator m, RealVector b)`
Returns an estimate of the solution to the linear system A · x = b.
`RealVector`
`solve(RealLinearOperator a, RealLinearOperator m, RealVector b, RealVector x0)`
Returns an estimate of the solution to the linear system A · x = b.
`RealVector`
`solve(RealLinearOperator a, RealVector b)`
Returns an estimate of the solution to the linear system A · x = b.
`RealVector`
`solve(RealLinearOperator a, RealVector b, RealVector x0)`
Returns an estimate of the solution to the linear system A · x = b.
`abstract RealVector`
`solveInPlace(RealLinearOperator a, RealLinearOperator m, RealVector b, RealVector x0)`
Returns an estimate of the solution to the linear system A · x = b.
`RealVector`
`solveInPlace(RealLinearOperator a, RealVector b, RealVector x0)`
Returns an estimate of the solution to the linear system A · x = b.

### Methods inherited from class org.apache.commons.math3.linear.IterativeLinearSolver

`checkParameters, getIterationManager`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### PreconditionedIterativeLinearSolver

public PreconditionedIterativeLinearSolver(int maxIterations)
Creates a new instance of this class, with default iteration manager.

Parameters:
  `maxIterations` - the maximum number of iterations

### PreconditionedIterativeLinearSolver

public PreconditionedIterativeLinearSolver(IterationManager manager) throws NullArgumentException
Creates a new instance of this class, with custom iteration manager.

Parameters:
  `manager` - the custom iteration manager
Throws:
  `NullArgumentException` - if `manager` is `null`

## Method Details

### solve

public RealVector solve(RealLinearOperator a, RealLinearOperator m, RealVector b, RealVector x0) throws NullArgumentException, NonSquareOperatorException, DimensionMismatchException, MaxCountExceededException
Returns an estimate of the solution to the linear system A · x = b.

Parameters:
  `a` - the linear operator A of the system
  `m` - the preconditioner, M (can be `null`)
  `b` - the right-hand side vector
  `x0` - the initial guess of the solution
Returns:
  a new vector containing the solution
Throws:
  `NullArgumentException` - if one of the parameters is `null`
  `NonSquareOperatorException` - if `a` or `m` is not square
  `DimensionMismatchException` - if `m`, `b` or `x0` have dimensions inconsistent with `a`
  `MaxCountExceededException` - at exhaustion of the iteration count, unless a custom `callback` has been set at construction of the `IterationManager`

### solve

public RealVector solve(RealLinearOperator a, RealVector b) throws NullArgumentException, NonSquareOperatorException, DimensionMismatchException, MaxCountExceededException
Returns an estimate of the solution to the linear system A · x = b.

Overrides:
  `solve` in class `IterativeLinearSolver`
Parameters:
  `a` - the linear operator A of the system
  `b` - the right-hand side vector
Returns:
  a new vector containing the solution
Throws:
  `NullArgumentException` - if one of the parameters is `null`
  `NonSquareOperatorException` - if `a` is not square
  `DimensionMismatchException` - if `b` has dimensions inconsistent with `a`
  `MaxCountExceededException` - at exhaustion of the iteration count, unless a custom `callback` has been set at construction of the `IterationManager`

### solve

public RealVector solve(RealLinearOperator a, RealVector b, RealVector x0) throws NullArgumentException, NonSquareOperatorException, DimensionMismatchException, MaxCountExceededException
Returns an estimate of the solution to the linear system A · x = b.

Overrides:
  `solve` in class `IterativeLinearSolver`
Parameters:
  `a` - the linear operator A of the system
  `b` - the right-hand side vector
  `x0` - the initial guess of the solution
Returns:
  a new vector containing the solution
Throws:
  `NullArgumentException` - if one of the parameters is `null`
  `NonSquareOperatorException` - if `a` is not square
  `DimensionMismatchException` - if `b` or `x0` have dimensions inconsistent with `a`
  `MaxCountExceededException` - at exhaustion of the iteration count, unless a custom `callback` has been set at construction of the `IterationManager`

### checkParameters

protected static void checkParameters(RealLinearOperator a, RealLinearOperator m, RealVector b, RealVector x0) throws NullArgumentException, NonSquareOperatorException, DimensionMismatchException
Performs all dimension checks on the parameters of `solve` and `solveInPlace`, and throws an exception if one of the checks fails.

Parameters:
  `a` - the linear operator A of the system
  `m` - the preconditioner, M (can be `null`)
  `b` - the right-hand side vector
  `x0` - the initial guess of the solution
Throws:
  `NullArgumentException` - if one of the parameters is `null`
  `NonSquareOperatorException` - if `a` or `m` is not square
  `DimensionMismatchException` - if `m`, `b` or `x0` have dimensions inconsistent with `a`

### solve

public RealVector solve(RealLinearOperator a, RealLinearOperator m, RealVector b) throws NullArgumentException, NonSquareOperatorException, DimensionMismatchException, MaxCountExceededException
Returns an estimate of the solution to the linear system A · x = b.

Parameters:
  `a` - the linear operator A of the system
  `m` - the preconditioner, M (can be `null`)
  `b` - the right-hand side vector
Returns:
  a new vector containing the solution
Throws:
  `NullArgumentException` - if one of the parameters is `null`
  `NonSquareOperatorException` - if `a` or `m` is not square
  `DimensionMismatchException` - if `m` or `b` have dimensions inconsistent with `a`
  `MaxCountExceededException` - at exhaustion of the iteration count, unless a custom `callback` has been set at construction of the `IterationManager`

### solveInPlace

public abstract RealVector solveInPlace(RealLinearOperator a, RealLinearOperator m, RealVector b, RealVector x0) throws NullArgumentException, NonSquareOperatorException, DimensionMismatchException, MaxCountExceededException
Returns an estimate of the solution to the linear system A · x = b. The solution is computed in-place (initial guess is modified).

Parameters:
  `a` - the linear operator A of the system
  `m` - the preconditioner, M (can be `null`)
  `b` - the right-hand side vector
  `x0` - the initial guess of the solution
Returns:
  a reference to `x0` (shallow copy) updated with the solution
Throws:
  `NullArgumentException` - if one of the parameters is `null`
  `NonSquareOperatorException` - if `a` or `m` is not square
  `DimensionMismatchException` - if `m`, `b` or `x0` have dimensions inconsistent with `a`
  `MaxCountExceededException` - at exhaustion of the iteration count, unless a custom `callback` has been set at construction of the `IterationManager`

### solveInPlace

public RealVector solveInPlace(RealLinearOperator a, RealVector b, RealVector x0) throws NullArgumentException, NonSquareOperatorException, DimensionMismatchException, MaxCountExceededException
Returns an estimate of the solution to the linear system A · x = b. The solution is computed in-place (initial guess is modified).

Specified by:
  `solveInPlace` in class `IterativeLinearSolver`
Parameters:
  `a` - the linear operator A of the system
  `b` - the right-hand side vector
  `x0` - initial guess of the solution
Returns:
  a reference to `x0` (shallow copy) updated with the solution
Throws:
  `NullArgumentException` - if one of the parameters is `null`
  `NonSquareOperatorException` - if `a` is not square
  `DimensionMismatchException` - if `b` or `x0` have dimensions inconsistent with `a`
  `MaxCountExceededException` - at exhaustion of the iteration count, unless a custom `callback` has been set at construction of the `IterationManager`