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 M^-1 · A · x = M^-1 · b, where M approximates in some way A, while remaining comparatively easier to invert. M (not M^-1!) is called the preconditionner.

Concrete implementations of this abstract class must be provided with M^-1, the inverse of the preconditioner, as a RealLinearOperator.

Since:

3.0

Version:

$Id: PreconditionedIterativeLinearSolver.java 1244107 2012-02-14 16:17:55Z erans $

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 minv, 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 minv, RealVector b) Returns an estimate of the solution to the linear system A · x = b.
RealVector	solve(RealLinearOperator a, RealLinearOperator minv, 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 minv, 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 minv,
               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

minv - the inverse of the preconditioner, M^-1 (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 minv is not square

DimensionMismatchException - if minv, b or x0 have dimensions inconsistent with a

MaxCountExceededException - at exhaustion of the iteration count, unless a custom callback has been set at construction

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

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

checkParameters

protected static void checkParameters(RealLinearOperator a,
                   RealLinearOperator minv,
                   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

minv - the inverse of the preconditioner, M^-1 (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 minv is not square

DimensionMismatchException - if minv, b or x0 have dimensions inconsistent with a

solve

public RealVector solve(RealLinearOperator a,
               RealLinearOperator minv,
               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

minv - the inverse of the preconditioner, M^-1 (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 minv is not square

DimensionMismatchException - if minv or b have dimensions inconsistent with a

MaxCountExceededException - at exhaustion of the iteration count, unless a custom callback has been set at construction

solveInPlace

public abstract RealVector solveInPlace(RealLinearOperator a,
                      RealLinearOperator minv,
                      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

minv - the inverse of the preconditioner, M^-1 (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 minv is not square

DimensionMismatchException - if minv, b or x0 have dimensions inconsistent with a

MaxCountExceededException - at exhaustion of the iteration count, unless a custom callback has been set at construction.

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