org.apache.commons.math3.linear
Class PreconditionedIterativeLinearSolver

java.lang.Object
  extended by org.apache.commons.math3.linear.IterativeLinearSolver
      extended by 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
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
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 © 2003-2013 The Apache Software Foundation. All Rights Reserved.