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
  Version:
    $Id: PreconditionedIterativeLinearSolver.java 1416643 2012-12-03 19:37:14Z tn $

- - ### Constructor Summary

    Constructors
    Constructor and 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

    Methods
    Modifier and Type | Method and 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 Detail

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

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

Copyright (c) 2003-2013 Apache Software Foundation