ptolemy.actor.continuous

Interface ContinuousStepSizeController

All Known Subinterfaces:

Advanceable

All Known Implementing Classes:

ContinuousDirector, ContinuousIntegrator, FMUImport, FMUImportHybrid, FMUQSS, HybridModalDirector, Integrator, LevelCrossingDetector

public interface ContinuousStepSizeController

Interface for actors and directors that control integration step sizes. This interface should be implemented by components that discover breakpoints during an integration step (such as level-crossing detectors) and by integrators.

Actors can affect the integration step size in two ways. The first one is by introducing predictable breakpoints. To request a breakpoint at time t, an actor can call the fireAt() method of ContinuousDirector with a time argument t, the director will treat t as a breakpoint. Actors that only introduce predictable breakpoints need not implement this interface. The director guarantees that no step size will be use that is large enough to step over t.

The second way of controlling step size is through checking the accuracy after each integration step. We treat an integration step as accurate if the numerical integration error is less than the error tolerance and there are no (unpredicted) breakpoints within this step. Actors that use this mechanism need to implement this interface. At the end of each integration step, each actor that implements this interface will be asked whether this step is accurate by calling its isStepSizeAccurate() method. If this method returns false, then all actors that implement this interface will be asked to suggest a refined step size (by calling refinedStepSize()). The integration step will be repeated with the smallest of these suggestions.

If all actors that implement this interface find the integration step accurate, then they will be asked for a suggested next step size (by calling suggestedStepSize()). The smallest of these suggested step sizes 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 the default 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 10.0

Version:

$Id$

Author:

Jie Liu, Haiyang Zheng, Edward A. Lee

Pt.AcceptedRating:

Green (eal)

Pt.ProposedRating:

Green (hyzheng)

Method Summary

Modifier and Type	Method and Description
boolean	isStepSizeAccurate() Implementations of this method should return true if the current integration step size is sufficiently small for this actor to give accurate results.
double	refinedStepSize() Implementations of this method should return the suggested refined step size for restarting the current integration.
double	suggestedStepSize() Implementations of this method should return the suggested next step size.

Method Detail

isStepSizeAccurate

boolean isStepSizeAccurate()

Implementations of this method should return true if the current integration step size is sufficiently small for this actor to give accurate results.

Returns:

True if the current step is accurate.

suggestedStepSize

double suggestedStepSize()
                  throws IllegalActionException

Implementations of this method should return the suggested next step size. If the current integration step is accurate, each actor will be asked for its suggestion for the next step size. If the actor that implements this interface does not care what the next step size is, it should return java.lang.Double.MAX_VALUE.

Returns:

The suggested next step size.

Throws:

IllegalActionException - If an actor suggests an illegal step size.

refinedStepSize

double refinedStepSize()
                throws IllegalActionException

Implementations of this method should return the suggested refined step size for restarting the current integration. If any actor returns false when isStepSizeAccurate() is called, then this method will be called on all actors that implement this interface. The minimum of their returned value will be the new step size. If the actor does not need a smaller step size, then this method should return the current step size.

Returns:

The suggested refined step size.

Throws:

IllegalActionException - If the step size cannot be further refined.