ru.sscc.util
Class IterationController

java.lang.Object
  |
  +--ru.sscc.util.IterationController

public class IterationController

extends java.lang.Object

implements java.io.Serializable

The controller of an iteration algorithm. When a numerical algorithm uses iterations, the main control parameter that has an influence on the decision "to stop or to continue iterations" is the reached accuracy of the approximate solution. This parameter is usually the relative accuracy, and the iterative method must stop iterations if the reached accuracy is the sufficiently small positive value. The iteration controller allows to set the accuracy limit needed and to stop iterations when the current accuracy is less than or equal to the accuracy limit. This class implements the simple controller that tests the accuracy only, but its interface allows to implement an advanced control.

The specific of iterative algorithms is the unlimittedness of the processing time and number of iterations needed to reach the required accuracy. So, an advanced iteration controller can test these parameters also and stop iterations if the convergence rate is too low. To provide advanced control, a developer can extend this class and override the startIterations, needStopIterations, and finishIterations methods. The agreements on using the iteration controller by an iterative algorithm are the following:

(1) When an iterative algorithm starts, it calls the startIterations method to notify the controller on this event.

(2) At every next iteration, it asks the controller by the needStopIterations method. The controller should return the true if the iterations must be stopped because the reached accuracy is good. If the reached accuracy is bad, but the iterations must be stopped by another reason, the controller throws the BreakIterationException.

(3) If the iterative algorithm decides that further iterations are not efficient (the accuracy cannot be improved), it can stop the iterations independently and must notify the iteration controller by the finishIterations method.

See Also:

Serialized Form

Field Summary

protected double	accuracy The current accuracy.
protected double	accuracyLimit The accuracy limit.

Constructor Summary

IterationController()
Constructs an instance with zero accuracy limit.

IterationController(double accuracyLimit)
Constructs an instance with a specified accuracy limit.

Method Summary

void	finishIterations(int count, double accuracy) This method notifies the controller that iteration process finished and passes to it the final values of the iteration count and accuracy.
double	getAccuracyLimit() Returns the accuracy limit.
double	getReachedAccuracy() Returns the current value of the accuracy.
boolean	needStopIterations(int count, double accuracy) This method tests the new iteration count and accuracy and decides: to stop iterations or not.
void	setAccuracyLimit(double accuracyLimit) Sets the accuracy limit.
void	startIterations(int count, double accuracy) This method notifies the controller that iteration process began and passes to it the initial values of the iteration count and accuracy.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

accuracyLimit

protected double accuracyLimit

The accuracy limit.

accuracy

protected double accuracy

The current accuracy.

Constructor Detail

IterationController

public IterationController()

Constructs an instance with zero accuracy limit.

IterationController

public IterationController(double accuracyLimit)

Constructs an instance with a specified accuracy limit.

Method Detail

getAccuracyLimit

public final double getAccuracyLimit()

Returns the accuracy limit.

setAccuracyLimit

public final void setAccuracyLimit(double accuracyLimit)

Sets the accuracy limit.

getReachedAccuracy

public final double getReachedAccuracy()

Returns the current value of the accuracy.

startIterations

public void startIterations(int count,
                            double accuracy)

This method notifies the controller that iteration process began and passes to it the initial values of the iteration count and accuracy.

Parameters:

count - the initial iteration count

accuracy - the initial accuracy

needStopIterations

public boolean needStopIterations(int count,
                                  double accuracy)

This method tests the new iteration count and accuracy and decides: to stop iterations or not. It must return the true value if the new accuracy is less than or equal to the accuracy limit. If the break must be done by another reason (request from user or too many iterations or something else), it must throw the BreakIterationException.

Parameters:

count - the current iteration count

accuracy - the current accuracy

Returns:

true if the accuracy limit reached

Throws:

BreakIterationException - if iterations must be stopped by another reason

finishIterations

public void finishIterations(int count,
                             double accuracy)

This method notifies the controller that iteration process finished and passes to it the final values of the iteration count and accuracy.

Parameters:

count - the final iteration count

accuracy - the final accuracy