Class ConjugateGradient
- java.lang.Object
-
- org.apache.commons.math3.linear.IterativeLinearSolver
-
- org.apache.commons.math3.linear.PreconditionedIterativeLinearSolver
-
- org.apache.commons.math3.linear.ConjugateGradient
-
public class ConjugateGradient extends PreconditionedIterativeLinearSolver
This is an implementation of the conjugate gradient method for
RealLinearOperator
. It follows closely the template by Barrett et al. (1994) (figure 2.5). The linear system at hand is A · x = b, and the residual is r = b - A · x.Default stopping criterion
A default stopping criterion is implemented. The iterations stop when || r || ≤ δ || b ||, where b is the right-hand side vector, r the current estimate of the residual, and δ a user-specified tolerance. It should be noted that r is the so-called updated residual, which might differ from the true residual due to rounding-off errors (see e.g. Strakos and Tichy, 2002).
Iteration count
In the present context, an iteration should be understood as one evaluation of the matrix-vector product A · x. The initialization phase therefore counts as one iteration.
Exception context
Besides standard
DimensionMismatchException
, this class might throwNonPositiveDefiniteOperatorException
if the linear operator or the preconditioner are not positive definite. In this case, theExceptionContext
provides some more information- key
"operator"
points to the offending linear operator, say L, - key
"vector"
points to the offending vector, say x, such that xT · L · x < 0.
References
- Barret et al. (1994)
- R. Barrett, M. Berry, T. F. Chan, J. Demmel, J. M. Donato, J. Dongarra, V. Eijkhout, R. Pozo, C. Romine and H. Van der Vorst, Templates for the Solution of Linear Systems: Building Blocks for Iterative Methods, SIAM
- Strakos and Tichy (2002)
- Z. Strakos and P. Tichy, On error estimation in the conjugate gradient method and why it works in finite precision computations, Electronic Transactions on Numerical Analysis 13: 56-80, 2002
- Since:
- 3.0
- key
-
-
Field Summary
Fields Modifier and Type Field Description private boolean
check
true
if positive-definiteness of matrix and preconditioner should be checked.private double
delta
The value of δ, for the default stopping criterion.static java.lang.String
OPERATOR
Key for the exception context.static java.lang.String
VECTOR
Key for the exception context.
-
Constructor Summary
Constructors Constructor Description ConjugateGradient(int maxIterations, double delta, boolean check)
Creates a new instance of this class, with default stopping criterion.ConjugateGradient(IterationManager manager, double delta, boolean check)
Creates a new instance of this class, with default stopping criterion and custom iteration manager.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description boolean
getCheck()
Returnstrue
if positive-definiteness should be checked for both matrix and preconditioner.RealVector
solveInPlace(RealLinearOperator a, RealLinearOperator m, 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.PreconditionedIterativeLinearSolver
checkParameters, solve, solve, solve, solve, solveInPlace
-
Methods inherited from class org.apache.commons.math3.linear.IterativeLinearSolver
checkParameters, getIterationManager
-
-
-
-
Field Detail
-
OPERATOR
public static final java.lang.String OPERATOR
Key for the exception context.- See Also:
- Constant Field Values
-
VECTOR
public static final java.lang.String VECTOR
Key for the exception context.- See Also:
- Constant Field Values
-
check
private boolean check
true
if positive-definiteness of matrix and preconditioner should be checked.
-
delta
private final double delta
The value of δ, for the default stopping criterion.
-
-
Constructor Detail
-
ConjugateGradient
public ConjugateGradient(int maxIterations, double delta, boolean check)
Creates a new instance of this class, with default stopping criterion.- Parameters:
maxIterations
- the maximum number of iterationsdelta
- the δ parameter for the default stopping criterioncheck
-true
if positive definiteness of both matrix and preconditioner should be checked
-
ConjugateGradient
public ConjugateGradient(IterationManager manager, double delta, boolean check) throws NullArgumentException
Creates a new instance of this class, with default stopping criterion and custom iteration manager.- Parameters:
manager
- the custom iteration managerdelta
- the δ parameter for the default stopping criterioncheck
-true
if positive definiteness of both matrix and preconditioner should be checked- Throws:
NullArgumentException
- ifmanager
isnull
-
-
Method Detail
-
getCheck
public final boolean getCheck()
Returnstrue
if positive-definiteness should be checked for both matrix and preconditioner.- Returns:
true
if the tests are to be performed
-
solveInPlace
public RealVector solveInPlace(RealLinearOperator a, RealLinearOperator m, RealVector b, RealVector x0) throws NullArgumentException, NonPositiveDefiniteOperatorException, 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 classPreconditionedIterativeLinearSolver
- Parameters:
a
- the linear operator A of the systemm
- the preconditioner, M (can benull
)b
- the right-hand side vectorx0
- the initial guess of the solution- Returns:
- a reference to
x0
(shallow copy) updated with the solution - Throws:
NonPositiveDefiniteOperatorException
- ifa
orm
is not positive definiteNullArgumentException
- if one of the parameters isnull
NonSquareOperatorException
- ifa
orm
is not squareDimensionMismatchException
- ifm
,b
orx0
have dimensions inconsistent witha
MaxCountExceededException
- at exhaustion of the iteration count, unless a customcallback
has been set at construction of theIterationManager
-
-