

PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 
java.lang.Object org.apache.commons.math3.linear.IterativeLinearSolver org.apache.commons.math3.linear.PreconditionedIterativeLinearSolver org.apache.commons.math3.linear.SymmLQ
public class SymmLQ
Implementation of the SYMMLQ iterative linear solver proposed by Paige and Saunders (1975). This implementation is largely based on the FORTRAN code by Pr. Michael A. Saunders, available here.
SYMMLQ is designed to solve the system of linear equations A · x = b
where A is an n × n selfadjoint linear operator (defined as a
RealLinearOperator
), and b is a given vector. The operator A is not
required to be positive definite. If A is known to be definite, the method of
conjugate gradients might be preferred, since it will require about the same
number of iterations as SYMMLQ but slightly less work per iteration.
SYMMLQ is designed to solve the system (A  shift · I) · x = b, where shift is a specified scalar value. If shift and b are suitably chosen, the computed vector x may approximate an (unnormalized) eigenvector of A, as in the methods of inverse iteration and/or Rayleighquotient iteration. Again, the linear operator (A  shift · I) need not be positive definite (but must be selfadjoint). The work per iteration is very slightly less if shift = 0.
Preconditioning may reduce the number of iterations required. The solver may be provided with a positive definite preconditioner M = P^{T} · P that is known to approximate (A  shift · I)^{1} in some sense, where matrixvector products of the form M · y = x can be computed efficiently. Then SYMMLQ will implicitly solve the system of equations P · (A  shift · I) · P^{T} · x_{hat} = P · b, i.e. A_{hat} · x_{hat} = b_{hat}, where A_{hat} = P · (A  shift · I) · P^{T}, b_{hat} = P · b, and return the solution x = P^{T} · x_{hat}. The associated residual is r_{hat} = b_{hat}  A_{hat} · x_{hat} = P · [b  (A  shift · I) · x] = P · r.
In the case of preconditioning, the IterativeLinearSolverEvent
s that
this solver fires are such that
IterativeLinearSolverEvent.getNormOfResidual()
returns the norm of
the preconditioned, updated residual, P · r, not the norm
of the true residual r.
A default stopping criterion is implemented. The iterations stop when  rhat  ≤ δ  Ahat   xhat , where xhat is the current estimate of the solution of the transformed system, rhat the current estimate of the corresponding residual, and δ a userspecified tolerance.
In the present context, an iteration should be understood as one evaluation of the matrixvector product A · x. The initialization phase therefore counts as one iteration. If the user requires checks on the symmetry of A, this entails one further matrixvector product in the initial phase. This further product is not accounted for in the iteration count. In other words, the number of iterations required to reach convergence will be identical, whether checks have been required or not.
The present definition of the iteration count differs from that adopted in the original FOTRAN code, where the initialization phase was not taken into account.
The x
parameter in
solve(RealLinearOperator, RealVector, RealVector)
,solve(RealLinearOperator, RealLinearOperator, RealVector, RealVector)
},solveInPlace(RealLinearOperator, RealVector, RealVector)
,solveInPlace(RealLinearOperator, RealLinearOperator, RealVector, RealVector)
,solveInPlace(RealLinearOperator, RealLinearOperator, RealVector, RealVector, boolean, double)
,
Besides standard DimensionMismatchException
, this class might throw
NonSelfAdjointOperatorException
if the linear operator or the
preconditioner are not symmetric. In this case, the ExceptionContext
provides more information
"operator"
points to the offending linear operator, say L,"vector1"
points to the first offending vector, say x,
"vector2"
points to the second offending vector, say y, such
that x^{T} · L · y ≠ y^{T} · L
· x (within a certain accuracy).
NonPositiveDefiniteOperatorException
might also be thrown in case the
preconditioner is not positive definite. The relevant keys to the
ExceptionContext
are
"operator"
, which points to the offending linear operator,
say L,"vector"
, which points to the offending vector, say x, such
that x^{T} · L · x < 0.
Constructor Summary  

SymmLQ(int maxIterations,
double delta,
boolean check)
Creates a new instance of this class, with default stopping criterion. 

SymmLQ(IterationManager manager,
double delta,
boolean check)
Creates a new instance of this class, with default stopping criterion and custom iteration manager. 
Method Summary  

boolean 
getCheck()
Returns true if symmetry of the matrix, and symmetry as well as
positive definiteness of the preconditioner should be checked. 
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,
boolean goodb,
double shift)
Returns an estimate of the solution to the linear system (A  shift · I) · x = b. 
RealVector 
solve(RealLinearOperator a,
RealLinearOperator m,
RealVector b,
RealVector x)
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,
boolean goodb,
double shift)
Returns the solution to the system (A  shift · I) · x = b. 
RealVector 
solve(RealLinearOperator a,
RealVector b,
RealVector x)
Returns an estimate of the solution to the linear system A · x = b. 
RealVector 
solveInPlace(RealLinearOperator a,
RealLinearOperator m,
RealVector b,
RealVector x)
Returns an estimate of the solution to the linear system A · x = b. 
RealVector 
solveInPlace(RealLinearOperator a,
RealLinearOperator m,
RealVector b,
RealVector x,
boolean goodb,
double shift)
Returns an estimate of the solution to the linear system (A  shift · I) · x = b. 
RealVector 
solveInPlace(RealLinearOperator a,
RealVector b,
RealVector x)
Returns an estimate of the solution to the linear system A · x = b. 
Methods inherited from class org.apache.commons.math3.linear.PreconditionedIterativeLinearSolver 

checkParameters 
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 

public SymmLQ(int maxIterations, double delta, boolean check)
check
to true
entails an extra matrixvector product in the initial phase.
maxIterations
 the maximum number of iterationsdelta
 the δ parameter for the default stopping criterioncheck
 true
if selfadjointedness of both matrix and
preconditioner should be checkedpublic SymmLQ(IterationManager manager, double delta, boolean check)
check
to true
entails an extra matrixvector product in
the initial phase.
manager
 the custom iteration managerdelta
 the δ parameter for the default stopping criterioncheck
 true
if selfadjointedness of both matrix and
preconditioner should be checkedMethod Detail 

public final boolean getCheck()
true
if symmetry of the matrix, and symmetry as well as
positive definiteness of the preconditioner should be checked.
true
if the tests are to be performedpublic RealVector solve(RealLinearOperator a, RealLinearOperator m, RealVector b) throws NullArgumentException, NonSquareOperatorException, DimensionMismatchException, MaxCountExceededException, NonSelfAdjointOperatorException, NonPositiveDefiniteOperatorException, IllConditionedOperatorException
solve
in class PreconditionedIterativeLinearSolver
a
 the linear operator A of the systemm
 the preconditioner, M (can be null
)b
 the righthand side vector
NonSelfAdjointOperatorException
 if getCheck()
is
true
, and a
or m
is not selfadjoint
NonPositiveDefiniteOperatorException
 if m
is not
positive definite
IllConditionedOperatorException
 if a
is illconditioned
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
public RealVector solve(RealLinearOperator a, RealLinearOperator m, RealVector b, boolean goodb, double shift) throws NullArgumentException, NonSquareOperatorException, DimensionMismatchException, MaxCountExceededException, NonSelfAdjointOperatorException, NonPositiveDefiniteOperatorException, IllConditionedOperatorException
If the solution x is expected to contain a large multiple of b
(as in Rayleighquotient iteration), then better precision may be
achieved with goodb
set to true
; this however requires an
extra call to the preconditioner.
shift
should be zero if the system A · x = b is to be
solved. Otherwise, it could be an approximation to an eigenvalue of A,
such as the Rayleigh quotient b^{T} · A · b /
(b^{T} · b) corresponding to the vector b. If b is
sufficiently like an eigenvector corresponding to an eigenvalue near
shift, then the computed x may have very large components. When
normalized, x may be closer to an eigenvector than b.
a
 the linear operator A of the systemm
 the preconditioner, M (can be null
)b
 the righthand side vectorgoodb
 usually false
, except if x
is expected to
contain a large multiple of b
shift
 the amount to be subtracted to all diagonal elements of A
x
(shallow copy)
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
NonSelfAdjointOperatorException
 if getCheck()
is
true
, and a
or m
is not selfadjoint
NonPositiveDefiniteOperatorException
 if m
is not
positive definite
IllConditionedOperatorException
 if a
is illconditionedpublic RealVector solve(RealLinearOperator a, RealLinearOperator m, RealVector b, RealVector x) throws NullArgumentException, NonSquareOperatorException, DimensionMismatchException, NonSelfAdjointOperatorException, NonPositiveDefiniteOperatorException, IllConditionedOperatorException, MaxCountExceededException
solve
in class PreconditionedIterativeLinearSolver
x
 not meaningful in this implementation; should not be considered
as an initial guess (more)a
 the linear operator A of the systemm
 the preconditioner, M (can be null
)b
 the righthand side vector
NonSelfAdjointOperatorException
 if getCheck()
is
true
, and a
or m
is not selfadjoint
NonPositiveDefiniteOperatorException
 if m
is not positive
definite
IllConditionedOperatorException
 if a
is illconditioned
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
public RealVector solve(RealLinearOperator a, RealVector b) throws NullArgumentException, NonSquareOperatorException, DimensionMismatchException, NonSelfAdjointOperatorException, IllConditionedOperatorException, MaxCountExceededException
solve
in class PreconditionedIterativeLinearSolver
a
 the linear operator A of the systemb
 the righthand side vector
NonSelfAdjointOperatorException
 if getCheck()
is
true
, and a
is not selfadjoint
IllConditionedOperatorException
 if a
is illconditioned
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
public RealVector solve(RealLinearOperator a, RealVector b, boolean goodb, double shift) throws NullArgumentException, NonSquareOperatorException, DimensionMismatchException, NonSelfAdjointOperatorException, IllConditionedOperatorException, MaxCountExceededException
If the solution x is expected to contain a large multiple of b
(as in Rayleighquotient iteration), then better precision may be
achieved with goodb
set to true
.
shift
should be zero if the system A · x = b is to be
solved. Otherwise, it could be an approximation to an eigenvalue of A,
such as the Rayleigh quotient b^{T} · A · b /
(b^{T} · b) corresponding to the vector b. If b is
sufficiently like an eigenvector corresponding to an eigenvalue near
shift, then the computed x may have very large components. When
normalized, x may be closer to an eigenvector than b.
a
 the linear operator A of the systemb
 the righthand side vectorgoodb
 usually false
, except if x
is expected to
contain a large multiple of b
shift
 the amount to be subtracted to all diagonal elements of A
x
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
NonSelfAdjointOperatorException
 if getCheck()
is
true
, and a
is not selfadjoint
IllConditionedOperatorException
 if a
is illconditionedpublic RealVector solve(RealLinearOperator a, RealVector b, RealVector x) throws NullArgumentException, NonSquareOperatorException, DimensionMismatchException, NonSelfAdjointOperatorException, IllConditionedOperatorException, MaxCountExceededException
solve
in class PreconditionedIterativeLinearSolver
x
 not meaningful in this implementation; should not be considered
as an initial guess (more)a
 the linear operator A of the systemb
 the righthand side vector
NonSelfAdjointOperatorException
 if getCheck()
is
true
, and a
is not selfadjoint
IllConditionedOperatorException
 if a
is illconditioned
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
public RealVector solveInPlace(RealLinearOperator a, RealLinearOperator m, RealVector b, RealVector x) throws NullArgumentException, NonSquareOperatorException, DimensionMismatchException, NonSelfAdjointOperatorException, NonPositiveDefiniteOperatorException, IllConditionedOperatorException, MaxCountExceededException
solveInPlace
in class PreconditionedIterativeLinearSolver
x
 the vector to be updated with the solution; x
should
not be considered as an initial guess (more)a
 the linear operator A of the systemm
 the preconditioner, M (can be null
)b
 the righthand side vector
x0
(shallow copy) updated with the
solution
NonSelfAdjointOperatorException
 if getCheck()
is
true
, and a
or m
is not selfadjoint
NonPositiveDefiniteOperatorException
 if m
is not
positive definite
IllConditionedOperatorException
 if a
is illconditioned
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
public RealVector solveInPlace(RealLinearOperator a, RealLinearOperator m, RealVector b, RealVector x, boolean goodb, double shift) throws NullArgumentException, NonSquareOperatorException, DimensionMismatchException, NonSelfAdjointOperatorException, NonPositiveDefiniteOperatorException, IllConditionedOperatorException, MaxCountExceededException
If the solution x is expected to contain a large multiple of b
(as in Rayleighquotient iteration), then better precision may be
achieved with goodb
set to true
; this however requires an
extra call to the preconditioner.
shift
should be zero if the system A · x = b is to be
solved. Otherwise, it could be an approximation to an eigenvalue of A,
such as the Rayleigh quotient b^{T} · A · b /
(b^{T} · b) corresponding to the vector b. If b is
sufficiently like an eigenvector corresponding to an eigenvalue near
shift, then the computed x may have very large components. When
normalized, x may be closer to an eigenvector than b.
a
 the linear operator A of the systemm
 the preconditioner, M (can be null
)b
 the righthand side vectorx
 the vector to be updated with the solution; x
should
not be considered as an initial guess (more)goodb
 usually false
, except if x
is expected to
contain a large multiple of b
shift
 the amount to be subtracted to all diagonal elements of A
x
(shallow copy).
NullArgumentException
 if one of the parameters is null
NonSquareOperatorException
 if a
or m
is not square
DimensionMismatchException
 if m
, b
or x
have dimensions inconsistent with a
.
MaxCountExceededException
 at exhaustion of the iteration count,
unless a custom
callback
has been set at construction of the IterationManager
NonSelfAdjointOperatorException
 if getCheck()
is
true
, and a
or m
is not selfadjoint
NonPositiveDefiniteOperatorException
 if m
is not positive
definite
IllConditionedOperatorException
 if a
is illconditionedpublic RealVector solveInPlace(RealLinearOperator a, RealVector b, RealVector x) throws NullArgumentException, NonSquareOperatorException, DimensionMismatchException, NonSelfAdjointOperatorException, IllConditionedOperatorException, MaxCountExceededException
solveInPlace
in class PreconditionedIterativeLinearSolver
x
 the vector to be updated with the solution; x
should
not be considered as an initial guess (more)a
 the linear operator A of the systemb
 the righthand side vector
x0
(shallow copy) updated with the
solution
NonSelfAdjointOperatorException
 if getCheck()
is
true
, and a
is not selfadjoint
IllConditionedOperatorException
 if a
is illconditioned
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


PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 