IterativeMatrixSolver (Cognitive Foundry)

java.lang.Object
- gov.sandia.cognition.learning.algorithm.minimization.matrix.IterativeMatrixSolver<Operator>

Type Parameters:

Operator - The operator for the solver.

All Implemented Interfaces:

AnytimeAlgorithm<InputOutputPair<Vector,Vector>>, IterativeAlgorithm, StoppableAlgorithm, BatchLearner<Operator,InputOutputPair<Vector,Vector>>, FunctionMinimizer<Vector,Vector,Operator>, CloneableSerializable, java.io.Serializable, java.lang.Cloneable

Direct Known Subclasses:

ConjugateGradientMatrixSolver, ConjugateGradientWithPreconditionerMatrixSolver, OverconstrainedConjugateGradientMatrixMinimizer, SteepestDescentMatrixSolver
```
@PublicationReference(author="Jonathan Richard Shewchuk",
                      title="An Introduction to the Conjugate Gradient Method Without the Agonizing Pain",
                      type=WebPage,
                      year=1994,
                      url="http://www.cs.cmu.edu/~quake-papers/painless-conjugate-gradient.pdf\u200e")
public abstract class IterativeMatrixSolver<Operator extends MatrixVectorMultiplier>
extends java.lang.Object
implements FunctionMinimizer<Vector,Vector,Operator>
```
Base class for all iterative matrix solvers that takes care of most of the basic iterative logic and the function minimizer interface.

Since:

4.0.0

Author:

Jeremy D. Wendt

See Also:

Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`protected int`	`iterationCounter` Counts the number of iterations executed thus far.
`protected java.util.Set<IterativeAlgorithmListener>`	`listeners` Listeners to the algorithms progress have the opportunity to stop the algorithm after a specified number of iterations.
`protected int`	`maxIterations` Execution will stop after this number of iterations even if it has not converged.
`protected Vector`	`rhs` The right-hand-side vector (b).
`protected boolean`	`shouldStop` If set to true, the algorithm will stop after the current iteration completes.
`protected double`	`tolerance` The tolerance of the error accepted before stopping iterations.
`protected Vector`	`x0` The initial guess for the left-hand-side vector (x).

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`IterativeMatrixSolver(IterativeMatrixSolver<Operator> copy)` Protected copy constructor
`protected`	`IterativeMatrixSolver(Vector x0, Vector rhs)` Initializes a solver with basic necessary values
`protected`	`IterativeMatrixSolver(Vector x0, Vector rhs, double tolerance)` Initializes a solver with a few more values
`protected`	`IterativeMatrixSolver(Vector x0, Vector rhs, double tolerance, int maxIterations)` Inititalizes a solver with all user-definable parameters

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addIterativeAlgorithmListener(IterativeAlgorithmListener listener)` Adds a listener for the iterations of the algorithm.
`abstract CloneableSerializable`	`clone()` Creates a new clone (shallow copy) of this object.
`protected abstract InputOutputPair<Vector,Vector>`	`completeSolver()` Called after the final iteration.
`boolean`	`equals(java.lang.Object o)`
`Vector`	`getInitialGuess()` Returns the initial guess at "x"
`int`	`getIteration()` Gets the current number of iterations executed by this algorithm since its it was started.
`int`	`getMaxIterations()` Gets the maximum number of total iterations before stopping.
`InputOutputPair<Vector,Vector>`	`getResult()` Gets the current result of the algorithm.
`double`	`getTolerance()` Gets the tolerance of the minimization algorithm
`int`	`hashCode()`
`protected abstract void`	`initializeSolver(Operator function)` Called before iterations begin in learn.
`boolean`	`isResultValid()` Returns true if execution stopped because the residual was below the acceptable tolerance (vs.
`protected abstract double`	`iterate()` Called during each step of the iterative solver.
`InputOutputPair<Vector,Vector>`	`learn(Operator function)` Shell that solves for Ax = b (x0 and rhs passed in on initialization, A is contained in function).
`void`	`removeIterativeAlgorithmListener(IterativeAlgorithmListener listener)` Removes a listener for the iterations of the algorithm.
`void`	`setInitialGuess(Vector initialGuess)` Sets the initial guess ("x0")
`void`	`setMaxIterations(int maxIterations)` Sets the maximum number of iterations before this will stop iterating.
`void`	`setTolerance(double tolerance)` Sets the minimum tolerance before iterations complete (must be non-negative).
`void`	`stop()` Execution will stop after the current iteration completes.

Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - tolerance
```
protected double tolerance
```
    The tolerance of the error accepted before stopping iterations.
  - x0
```
protected Vector x0
```
    The initial guess for the left-hand-side vector (x).
  - rhs
```
protected Vector rhs
```
    The right-hand-side vector (b).
  - maxIterations
```
protected int maxIterations
```
    Execution will stop after this number of iterations even if it has not converged.
  - listeners
```
protected java.util.Set<IterativeAlgorithmListener> listeners
```
    Listeners to the algorithms progress have the opportunity to stop the algorithm after a specified number of iterations.
  - iterationCounter
```
protected int iterationCounter
```
    Counts the number of iterations executed thus far.
  - shouldStop
```
protected boolean shouldStop
```
    If set to true, the algorithm will stop after the current iteration completes.
- Constructor Detail
  - IterativeMatrixSolver
```
protected IterativeMatrixSolver(Vector x0,
                                Vector rhs)
```
    Initializes a solver with basic necessary values
    
    Parameters:
    
    x0 - The initial guess for x
    
    rhs - The "b" to solve
  - IterativeMatrixSolver
```
protected IterativeMatrixSolver(Vector x0,
                                Vector rhs,
                                double tolerance)
```
    Initializes a solver with a few more values
    
    Parameters:
    
    x0 - The initial guess for x
    
    rhs - The "b" to solve
    
    tolerance - The minimum acceptable error
  - IterativeMatrixSolver
```
protected IterativeMatrixSolver(Vector x0,
                                Vector rhs,
                                double tolerance,
                                int maxIterations)
```
    Inititalizes a solver with all user-definable parameters
    
    Parameters:
    
    x0 - The initial guess for x
    
    rhs - The "b" to solve
    
    tolerance - The minimum acceptable error
    
    maxIterations - The maximum number of iterations
  - IterativeMatrixSolver
```
protected IterativeMatrixSolver(IterativeMatrixSolver<Operator> copy)
```
    Protected copy constructor
    
    Parameters:
    
    copy - The "self" to copy
- Method Detail
  - learn
```
public final InputOutputPair<Vector,Vector> learn(Operator function)
```
    Shell that solves for Ax = b (x0 and rhs passed in on initialization, A is contained in function).
    
    Specified by:
    
    learn in interface BatchLearner<Operator extends MatrixVectorMultiplier,InputOutputPair<Vector,Vector>>
    
    Specified by:
    
    learn in interface FunctionMinimizer<Vector,Vector,Operator extends MatrixVectorMultiplier>
    
    Parameters:
    
    function - Matrix wrapper
    
    Returns:
    
    The input b and resulting x found.
  - initializeSolver
```
protected abstract void initializeSolver(Operator function)
```
    Called before iterations begin in learn. Iterative solvers can solve for initial state and should store function away.
    
    Parameters:
    
    function - The matrix wrapper to save for iterate.
  - iterate
```
protected abstract double iterate()
```
    Called during each step of the iterative solver. Take one step forward in the algorithm.
    
    Returns:
    
    the residual after this step.
  - completeSolver
```
protected abstract InputOutputPair<Vector,Vector> completeSolver()
```
    Called after the final iteration. The solver should clean up any intermediate results and return the final results.
    
    Returns:
    
    the final results of the algorithm.
  - clone
```
public abstract CloneableSerializable clone()
```
    Description copied from interface: CloneableSerializable
    
    Creates a new clone (shallow copy) of this object.
    
    Specified by:
    
    clone in interface CloneableSerializable
    
    Overrides:
    
    clone in class java.lang.Object
    
    Returns:
    
    A new clone (shallow copy) of this object.
    
    See Also:
    
    CloneableSerializable.clone()
  - getTolerance
```
public final double getTolerance()
```
    Description copied from interface: FunctionMinimizer
    
    Gets the tolerance of the minimization algorithm
    
    Specified by:
    
    getTolerance in interface FunctionMinimizer<Vector,Vector,Operator extends MatrixVectorMultiplier>
    
    Returns:
    
    Tolerance of the minimization algorithm
    
    See Also:
    
    FunctionMinimizer.getTolerance()
  - setTolerance
```
public final void setTolerance(double tolerance)
```
    Sets the minimum tolerance before iterations complete (must be non-negative). If set to zero, you'll likely go all iterations (to maxIterations) in most cases due to numerical precision issues.
    
    Specified by:
    
    setTolerance in interface FunctionMinimizer<Vector,Vector,Operator extends MatrixVectorMultiplier>
    
    Parameters:
    
    tolerance - The minimum tolerance acceptable before returning the result.
  - getInitialGuess
```
public final Vector getInitialGuess()
```
    Returns the initial guess at "x"
    
    Specified by:
    
    getInitialGuess in interface FunctionMinimizer<Vector,Vector,Operator extends MatrixVectorMultiplier>
    
    Returns:
    
    the initial guess at "x"
  - setInitialGuess
```
public final void setInitialGuess(Vector initialGuess)
```
    Sets the initial guess ("x0")
    
    Specified by:
    
    setInitialGuess in interface FunctionMinimizer<Vector,Vector,Operator extends MatrixVectorMultiplier>
    
    Parameters:
    
    initialGuess - the initial guess ("x0")
  - getMaxIterations
```
public final int getMaxIterations()
```
    Description copied from interface: AnytimeAlgorithm
    
    Gets the maximum number of total iterations before stopping.
    
    Specified by:
    
    getMaxIterations in interface AnytimeAlgorithm<InputOutputPair<Vector,Vector>>
    
    Returns:
    
    Maximum number of total iterations before stopping. Must be greater than zero.
    
    See Also:
    
    AnytimeAlgorithm.getMaxIterations()
  - setMaxIterations
```
public final void setMaxIterations(int maxIterations)
```
    Sets the maximum number of iterations before this will stop iterating. It will stop sooner if the residual is below the minimum residual. The number of iterations must be positive (>0).
    
    Specified by:
    
    setMaxIterations in interface AnytimeAlgorithm<InputOutputPair<Vector,Vector>>
    
    Parameters:
    
    maxIterations - The maximum number of iterations
  - getResult
```
public InputOutputPair<Vector,Vector> getResult()
```
    Description copied from interface: AnytimeAlgorithm
    
    Gets the current result of the algorithm.
    
    Specified by:
    
    getResult in interface AnytimeAlgorithm<InputOutputPair<Vector,Vector>>
    
    Returns:
    
    Current result of the algorithm.
    
    See Also:
    
    AnytimeAlgorithm.getResult()
  - getIteration
```
public int getIteration()
```
    Description copied from interface: IterativeAlgorithm
    
    Gets the current number of iterations executed by this algorithm since its it was started.
    
    Specified by:
    
    getIteration in interface IterativeAlgorithm
    
    Returns:
    
    Current number of iterations executed by this algorithm.
    
    See Also:
    
    IterativeAlgorithm.getIteration()
  - addIterativeAlgorithmListener
```
public final void addIterativeAlgorithmListener(IterativeAlgorithmListener listener)
```
    Description copied from interface: IterativeAlgorithm
    
    Adds a listener for the iterations of the algorithm.
    
    Specified by:
    
    addIterativeAlgorithmListener in interface IterativeAlgorithm
    
    Parameters:
    
    listener - The listener to add.
    
    See Also:
    
    IterativeAlgorithm.addIterativeAlgorithmListener(gov.sandia.cognition.algorithm.IterativeAlgorithmListener)
  - removeIterativeAlgorithmListener
```
public final void removeIterativeAlgorithmListener(IterativeAlgorithmListener listener)
```
    Description copied from interface: IterativeAlgorithm
    
    Removes a listener for the iterations of the algorithm.
    
    Specified by:
    
    removeIterativeAlgorithmListener in interface IterativeAlgorithm
    
    Parameters:
    
    listener - The listener to remove.
    
    See Also:
    
    IterativeAlgorithm.removeIterativeAlgorithmListener(gov.sandia.cognition.algorithm.IterativeAlgorithmListener)
  - stop
```
public void stop()
```
    Execution will stop after the current iteration completes.
    
    Specified by:
    
    stop in interface StoppableAlgorithm
  - isResultValid
```
public final boolean isResultValid()
```
    Returns true if execution stopped because the residual was below the acceptable tolerance (vs. due to stop being called or exceeding maxIterations).
    
    Specified by:
    
    isResultValid in interface StoppableAlgorithm
    
    Returns:
    
    true if execution stopped because the residual was below acceptable tolerance.
  - equals
```
public boolean equals(java.lang.Object o)
```
    Overrides:
    
    equals in class java.lang.Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class java.lang.Object
    
    See Also:
    
    Object.hashCode()

Class IterativeMatrixSolver<Operator extends MatrixVectorMultiplier>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

tolerance

x0

rhs

maxIterations

listeners

iterationCounter

shouldStop

Constructor Detail

IterativeMatrixSolver

IterativeMatrixSolver

IterativeMatrixSolver

IterativeMatrixSolver

Method Detail

learn

initializeSolver

iterate

completeSolver

clone

getTolerance

setTolerance

getInitialGuess

setInitialGuess

getMaxIterations

setMaxIterations

getResult

getIteration

addIterativeAlgorithmListener

removeIterativeAlgorithmListener

stop

isResultValid

equals

hashCode