ptolemy.domains.ct.kernel
Interface CTStepSizeControlActor

All Superinterfaces:
ptolemy.actor.Actor, ptolemy.actor.Executable
All Known Implementing Classes:
CTBaseIntegrator, CTCompositeActor, LevelCrossingDetector, ThresholdMonitor

public interface CTStepSizeControlActor
extends ptolemy.actor.Actor

Interface for actors that controls integration step sizes for handling unpredictable breakpoints or controlling numerical error. Typically, the actors that implement this interface are dynamic actors and event detectors.

Actors can affect the integration step size in two ways. The first one is by introducing predictable breakpoints. When the fireAt() method of the CTDirector is called with an argument t, the CTDirector will treat t as a breakpoint. Actors that only introduce predictable breakpoints need not implement this interface.

The second way of controlling step size is through the accuracy checking after each integration step. Accuracy, in this context, means that the numerical integration error is less than the error tolerance and there is no (unpredictable) breakpoints within this step. Actors that uses this mechanism need to implement this interface. At the end of each integration step, each CTStepSizeControlActors will be asked whether this step is accurate by calling their isThisStepAccurate() method. If it returns false, that actor will then be asked to suggest a refined step size. If there are more than one actors find that this step is not accurate, then the smallest of the suggested step size will be used by the director to restart the integration step.

If all step size control actors find the integration step accurate, then they will be asked for a (predicted) next step size. The smallest predicted next step size will be used for the next integration step.

If there are no step size control actors in a model, the step size is controlled by the director. Most (or possibly all) CT directors will leave default the step size at its initial value, and only deviate from these steps when there is a predictable breakpoint that does not coincide with one of these steps.

Since:
Ptolemy II 0.2
Version:
$Id: CTStepSizeControlActor.java,v 1.25 2004/04/13 03:26:40 cxh Exp $
Author:
Jie Liu
Accepted Rating:
Green (yuhong)
Proposed Rating:
Green (liuj)

Field Summary
 
Fields inherited from interface ptolemy.actor.Executable
COMPLETED, NOT_READY, STOP_ITERATING
 
Method Summary
 boolean isThisStepAccurate()
          Implementations of this method should return true if the current integration step is accurate from this actor's point of view.
 double predictedStepSize()
          Implementations of this method should return the predicted next step size.
 double refinedStepSize()
          Implementations of this method should return the refined step size for restarting the current step.
 
Methods inherited from interface ptolemy.actor.Actor
getDirector, getExecutiveDirector, getFunctionDependency, getManager, inputPortList, newReceiver, outputPortList
 
Methods inherited from interface ptolemy.actor.Executable
fire, initialize, iterate, postfire, prefire, preinitialize, stop, stopFire, terminate, wrapup
 

Method Detail

isThisStepAccurate

public boolean isThisStepAccurate()
Implementations of this method should return true if the current integration step is accurate from this actor's point of view. Actors that implement this interface will interpret "accurate" themselves. For example, for integrators, "accurate" could mean that the local truncation error is small enough; for event detectors, "accurate" could mean that there is not event missed during the integration step. The actor may only care about one of these aspects.

Returns:
True if the current integration step is accurate.

predictedStepSize

public double predictedStepSize()
Implementations of this method should return the predicted next step size. If the current integration step is accurate, the actor will be asked for the prediction of the next step size. If the actor that implement this interface does not know how to predict the next step size, it should return java.lang.Double.MAX_VALUE.

Returns:
The predicted next step size.

refinedStepSize

public double refinedStepSize()
Implementations of this method should return the refined step size for restarting the current step. If this actor returns false when calling isThisStepAccurate, then it will be asked for a refined step size. If the actor does not want to restart the current integration step, this method should return the current step size of the director.

Returns:
The refined step size.