Top Description Constructors Methods
org.apache.commons.math3.linear

public abstract Class PreconditionedIterativeLinearSolver

extends IterativeLinearSolver
Class Inheritance
Known Direct Subclasses
org.apache.commons.math3.linear.SymmLQ, org.apache.commons.math3.linear.ConjugateGradient
Imports
org.apache.commons.math3.exception.DimensionMismatchException, .MaxCountExceededException, .NullArgumentException, org.apache.commons.math3.util.IterationManager, .MathUtils

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

AccessConstructor and Description
public
PreconditionedIterativeLinearSolver(final int
the maximum number of iterations
maxIterations
)

Creates a new instance of this class, with default iteration manager.

public
PreconditionedIterativeLinearSolver(final IterationManager
the custom iteration manager
manager
)

Creates a new instance of this class, with custom iteration manager.

Method Summary

Modifier and TypeMethod and Description
protected static void
checkParameters(final RealLinearOperator
the linear operator A of the system
a
,
final RealLinearOperator
the preconditioner, M (can be null)
m
,
final RealVector
the right-hand side vector
b
,
final RealVector
the initial guess of the solution
x0
)

Performs all dimension checks on the parameters of solve and solveInPlace, and throws an exception if one of the checks fails.

public RealVector

Returns:

a new vector containing the solution
solve
(final RealLinearOperator
the linear operator A of the system
a
,
final RealLinearOperator
the preconditioner, M (can be null)
m
,
final RealVector
the right-hand side vector
b
,
final RealVector
the initial guess of the solution
x0
)

Returns an estimate of the solution to the linear system A · x = b.

public RealVector
solve(final RealLinearOperator
the linear operator A of the system
a
,
final RealVector
the right-hand side vector
b
)

Overrides org.apache.commons.math3.linear.IterativeLinearSolver.solve.

Returns an estimate of the solution to the linear system A · x = b.

public RealVector
solve(final RealLinearOperator
the linear operator A of the system
a
,
final RealVector
the right-hand side vector
b
,
final RealVector
the initial guess of the solution
x0
)

Overrides org.apache.commons.math3.linear.IterativeLinearSolver.solve.

Returns an estimate of the solution to the linear system A · x = b.

public RealVector

Returns:

a new vector containing the solution
solve
(RealLinearOperator
the linear operator A of the system
a
,
RealLinearOperator
the preconditioner, M (can be null)
m
,
RealVector
the right-hand side vector
b
)

Returns an estimate of the solution to the linear system A · x = b.

public abstract RealVector

Returns:

a reference to x0 (shallow copy) updated with the solution
solveInPlace
(RealLinearOperator
the linear operator A of the system
a
,
RealLinearOperator
the preconditioner, M (can be null)
m
,
RealVector
the right-hand side vector
b
,
RealVector
the initial guess of the solution
x0
)

Returns an estimate of the solution to the linear system A · x = b.

public RealVector
solveInPlace(final RealLinearOperator
the linear operator A of the system
a
,
final RealVector
the right-hand side vector
b
,
final RealVector
initial guess of the solution
x0
)

Implements abstract org.apache.commons.math3.linear.IterativeLinearSolver.solveInPlace.

Returns an estimate of the solution to the linear system A · x = b.

Inherited from org.apache.commons.math3.linear.IterativeLinearSolver:
checkParametersgetIterationManager

Constructor Detail

PreconditionedIterativeLinearSolverback to summary
public PreconditionedIterativeLinearSolver(final int maxIterations)

Creates a new instance of this class, with default iteration manager.

Parameters
maxIterations:int

the maximum number of iterations

PreconditionedIterativeLinearSolverback to summary
public PreconditionedIterativeLinearSolver(final IterationManager manager) throws NullArgumentException

Creates a new instance of this class, with custom iteration manager.

Parameters
manager:IterationManager

the custom iteration manager

Exceptions
NullArgumentException:
if manager is null

Method Detail

checkParametersback to summary
protected static void checkParameters(final RealLinearOperator a, final RealLinearOperator m, final RealVector b, final 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:RealLinearOperator

the linear operator A of the system

m:RealLinearOperator

the preconditioner, M (can be null)

b:RealVector

the right-hand side vector

x0:RealVector

the initial guess of the solution

Exceptions
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
solveback to summary
public RealVector solve(final RealLinearOperator a, final RealLinearOperator m, final RealVector b, final RealVector x0) throws NullArgumentException, NonSquareOperatorException, DimensionMismatchException, MaxCountExceededException

Returns an estimate of the solution to the linear system A · x = b.

Parameters
a:RealLinearOperator

the linear operator A of the system

m:RealLinearOperator

the preconditioner, M (can be null)

b:RealVector

the right-hand side vector

x0:RealVector

the initial guess of the solution

Returns:RealVector

a new vector containing the solution

Exceptions
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
solveback to summary
public RealVector solve(final RealLinearOperator a, final RealVector b) throws NullArgumentException, NonSquareOperatorException, DimensionMismatchException, MaxCountExceededException

Overrides org.apache.commons.math3.linear.IterativeLinearSolver.solve.

Doc from org.apache.commons.math3.linear.IterativeLinearSolver.solve.

Returns an estimate of the solution to the linear system A · x = b.

Parameters
a:RealLinearOperator

the linear operator A of the system

b:RealVector

the right-hand side vector

Returns:RealVector

a new vector containing the solution

Annotations
@Override
Exceptions
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
solveback to summary
public RealVector solve(final RealLinearOperator a, final RealVector b, final RealVector x0) throws NullArgumentException, NonSquareOperatorException, DimensionMismatchException, MaxCountExceededException

Overrides org.apache.commons.math3.linear.IterativeLinearSolver.solve.

Doc from org.apache.commons.math3.linear.IterativeLinearSolver.solve.

Returns an estimate of the solution to the linear system A · x = b.

Parameters
a:RealLinearOperator

the linear operator A of the system

b:RealVector

the right-hand side vector

x0:RealVector

the initial guess of the solution

Returns:RealVector

a new vector containing the solution

Annotations
@Override
Exceptions
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
solveback to summary
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:RealLinearOperator

the linear operator A of the system

m:RealLinearOperator

the preconditioner, M (can be null)

b:RealVector

the right-hand side vector

Returns:RealVector

a new vector containing the solution

Exceptions
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
solveInPlaceback to summary
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:RealLinearOperator

the linear operator A of the system

m:RealLinearOperator

the preconditioner, M (can be null)

b:RealVector

the right-hand side vector

x0:RealVector

the initial guess of the solution

Returns:RealVector

a reference to x0 (shallow copy) updated with the solution

Exceptions
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
solveInPlaceback to summary
public RealVector solveInPlace(final RealLinearOperator a, final RealVector b, final RealVector x0) throws NullArgumentException, NonSquareOperatorException, DimensionMismatchException, MaxCountExceededException

Implements abstract org.apache.commons.math3.linear.IterativeLinearSolver.solveInPlace.

Doc from org.apache.commons.math3.linear.IterativeLinearSolver.solveInPlace.

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:RealLinearOperator

the linear operator A of the system

b:RealVector

the right-hand side vector

x0:RealVector

initial guess of the solution

Returns:RealVector

a reference to x0 (shallow copy) updated with the solution

Annotations
@Override
Exceptions
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