ptolemy.domains.continuous.kernel
Class ContinuousDirector

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.util.Attribute
          ptolemy.actor.Director
              ptolemy.actor.sched.StaticSchedulingDirector
                  ptolemy.actor.sched.FixedPointDirector
                      ptolemy.domains.continuous.kernel.ContinuousDirector

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Executable, Initializable, SuperdenseTimeDirector, TimedDirector, ContinuousStatefulComponent, ContinuousStepSizeController, Suspendable, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

public class ContinuousDirector
extends FixedPointDirector
implements TimedDirector, ContinuousStatefulComponent, ContinuousStepSizeController, Suspendable

The continuous time domain is a timed domain that supports continuous-time signals, discrete-event signals, and mixtures of the two. There is a global notion of time that all the actors are aware of. The semantics of this domain is given in the following two papers:

• Edward A. Lee and Haiyang Zheng, "Operational Semantics of Hybrid Systems," Invited paper in Proceedings of Hybrid Systems: Computation and Control (HSCC) LNCS 3414, Zurich, Switzerland, March 9-11, 2005.
• Edward A. Lee, Haiyang Zheng, "Leveraging Synchronous Language Principles for Heterogeneous Modeling and Design of Embedded Systems," EMSOFT 07, September 30-October 3, 2007, Salzburg, Austria.

A signal is a set of "events," each of which has a tag and value. The set of values includes a special element, called "absent", denoting the absence of a (normal) value. This director uses superdense time, where every event has a tag that is a member of the set RxN. R is a connected subset of the real numbers (giving "time", and approximated by instances of the Time class), and N is the natural numbers (giving an "index"). At a time t, a signal may have multiple values in sequence with tags (t, 0), (t, 1)... Its "initial value" is the value at tag (t, 0). It typically settles to a "final value" after a finite number of indices. If it fails to settle to a final value, the signal is said to have a "stuttering Zeno" condition, and time will not progress.

In our semantics, all signals are piecewise continuous. This means that the initial value, as a function of time, is continuous on the left, the final value, as a function of time, is continuous on the right, and the signal has exactly one value (meaning the initial value and the final value are the same) at all times except those on a discrete subset D.

A purely continuous signal has exactly one value at all times, meaning that the final value equals the initial value at all times. A purely discrete signal has initial value "absent" and final value "absent" at all times, and at a discrete subset of the times, it may have non-absent values. The only signal that is both purely continuous and purely discrete is the one that is absent at all tags.

A signal may be mostly continuous, but have multiple values at a discrete subset of times. These multiple values semantically represent discontinuities in a continuous signal that is not purely continuous.

The set of times where signals have more than one distinct value is a discrete subset D of the time line. These times are called "breakpoints" and are treated specially in the execution. Between these times, an ordinary differential equation (ODE) solver governs the execution. Initial values are always given by the ODE solver.

The parameters of this director are:

• startTime: The start time of the execution. This parameter has no effect if this director is not at the top-level of a model.
• stopTime: The stop time of the execution. When the current time reaches this value, postfire() will return false. This will occur whether or not this director is at the top level.
• initStepSize: The suggested integration step size. If the ODE solver is a fixed step size solver, then this parameter gives the step size taken. Otherwise, at the start of execution, this provides the first guess for the integration step size. In later iterations, the integrators provide the suggested step size. This is a double with default value 0.1
• maxStepSize: The maximum step size. This can be used to prevent the solver from too few samples of signals. That is, for certain models, it might be possible to get accurate results for very large step sizes, but plots of the signals may be misleading (even if they are accurate) because they represent the signal with only a few samples. The default value is 1.0.
• maxIterations: The maximum number of iterations that an ODE solver can use to resolve the states of integrators. Implicit solvers, for example, iterate until they converge, and this parameter bounds the number of iterations. An example of an implicit solver is the BackwardsEuler solver. The default value is 20, and the type is int. FIXME: Currently, this package implements no implicit solvers.
• ODESolver: The class name of the ODE solver used for integration. This is a string that defaults to "ExplicitRK23Solver", a solver that tends to deliver smooth renditions of signals. The "ExplicitRK45Solver" may be more efficient in that it can use larger step sizes, but the resulting signals when displayed may be more jagged in appearance. Solvers are all required to be in package "ptolemy.domains.continuous.kernel.solver". If there is another ContinuousDirector above this one in the hierarchy, then the value of this parameter is ignored and the solver given by the first ContinuousDirector above will be used.
• errorTolerance: This is the local truncation error tolerance, used for controlling the integration accuracy in variable step size ODE solvers, and also for determining whether unpredictable breakpoints have been accurately identified. Any actor that implements ContinuousStepSizeControl may use this error tolerance to determine whether the current step is accurate. For example, if the local truncation error in some integrator is greater than this tolerance, then the integration step is considered to have failed, and should be restarted with a reduced step size. The default value is 1e-4.

This director maintains a breakpoint table to record all predictable breakpoints that are greater than or equal to the current time. The breakpoints are sorted in chronological order. Breakpoints at the same time are considered to be identical, and the breakpoint table does not contain duplicate time points. A breakpoint can be inserted into the table by calling the fireAt() method. The fireAt method may be requested by the director, which inserts the stop time of the execution. The fireAt method may also be requested by actors and the requested firing time will be inserted into the breakpoint table.

This director is designed to work with any other director that implements the strict actor semantics. As long as the other director does not commit state changes except in postfire(), that director can be used within the model controlled by this director. If, in addition to implementing the strict actor semantics that other director also respects calls to fireAt(), then this director may be used within a model governed by that director.

This director is based on the CTDirector by Jie Liu and Haiyang Zheng, but it has a much simpler scheduler and a fixed-point semantics.

Since:

Ptolemy II 6.0

Version:

$Id: ContinuousDirector.java 59167 2010-09-21 17:08:02Z cxh $

Author:

Haiyang Zheng and Edward A. Lee, based on CTDirector by Jie Liu and Haiyang Zheng

See Also:

Serialized Form

Accepted Rating:

Red (hyzheng)

Proposed Rating:

Yellow (hyzheng)

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.kernel.util.NamedObj

NamedObj.ContainedObjectsIterator

Field Summary

private Time	_accumulatedSuspendTime The accumulated suspend time relative to an eclosing ContinuousDirector, calculated as a side effect of calling _enclosingContinuousDirector().
private TotallyOrderedSet	_breakpoints A table for breakpoints.
private boolean	_commitIsPending Flag indicating that postfire() did not commit the state at the local current time.
private double	_currentStepSize Simulation step sizes.
private ContinuousDirector	_enclosingContinuousDirector The enclosing continuous director.
private long	_enclosingContinuousDirectorVersion The version for __enclosingContinuousDirector.
private double	_errorTolerance The error tolerance for state resolution.
private boolean	_ignoreSetTime Flag to temporarily ignore the setModelTime() calls.
private double	_initStepSize A cache of the value of initStepSize.
protected boolean	_isInitializing A local boolean variable indicating whether this director is in initialization phase execution.
private boolean	_isIntermediateStep Flag indicating that the solver is iterating through the first or intermediate steps in a multi-step solver.
private int	_iterationBeginIndex The index of the time at which the current integration step began.
protected Time	_iterationBeginTime The current time at the start of the current integration step.
private Time	_lastSuspendTime The environment time when this refinement was last suspended (that is, the enclosing state was exited).
private int	_maxIterations The maximum iterations for implicit ODE solver to resolve states.
private double	_maxStepSize The maximum step size used for integration.
private ContinuousODESolver	_ODESolver The ODE solver, which is an instance of the class given by the ODESolver parameter.
private boolean	_redoingSolverIteration Flag indicating that we are redoing a speculative solver iteration.
private static java.lang.String	_solverClasspath The package name for the solvers supported by this director.
private Time	_startTime The cached value of the startTime parameter.
private java.util.List	_statefulComponents The list of stateful actors.
private long	_statefulComponentsVersion The version for the list of step size control actors.
private java.util.List	_stepSizeControllers The list of step size control actors.
private long	_stepSizeControllersVersion The version for the list of step size control actors.
private Time	_stopTime The cached value of the stopTime parameter.
protected long	_timeBase The real starting time in term of system millisecond counts.
private boolean	_triedTheMinimumStepSize The local flag variable indicating whether the we have tried the time resolution as the integration step size.
private Time	_zeroTime Time with value 0.0.
Parameter	errorTolerance Error tolerance for data values, used with variable step size solvers to determine whether the current step size is accurate.
Parameter	initStepSize User's hint for the initial integration step size.
Parameter	maxIterations The maximum number of rounds that an ODE solver can use to resolve the states of integrators.
Parameter	maxStepSize The maximum step size.
StringParameter	ODESolver The class name of the ODE solver used for integration.
Parameter	startTime Starting time of the execution.
Parameter	stopTime Stop time of the simulation.

Fields inherited from class ptolemy.actor.sched.FixedPointDirector

_index, _receivers, iterations, synchronizeToRealTime

Fields inherited from class ptolemy.actor.sched.StaticSchedulingDirector

_postfireReturns

Fields inherited from class ptolemy.actor.Director

_actorsFinishedExecution, _currentTime, _finishRequested, _initializables, _stopRequested, timeResolution

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS

Fields inherited from interface ptolemy.actor.Executable

COMPLETED, NOT_READY, STOP_ITERATING

Constructor Summary

ContinuousDirector(CompositeEntity container, java.lang.String name)
Construct a director in the given container with the given name.

Method Summary

private void	_assertAbsentInside() Set all receivers on the inside of input ports to absent.
private boolean	_commit() Commit the current state by postfiring the actors under the control of this director.
private ContinuousDirector	_enclosingContinuousDirector() Return the enclosing continuous director, or null if there is none.
protected double	_getCurrentStepSize() Return the current step size.
protected ContinuousODESolver	_getODESolver() Return the ODE solver used to resolve states by the director.
private void	_handleBreakpointsBefore(Time time, int index) Throw an exception if there are any breakpoints in the breakpoint table before the specified time.
private void	_initializeLocalVariables() Initialize the local variables of this ContinuousDirector.
protected void	_initParameters() Create and initialize all parameters to their default values.
protected ContinuousODESolver	_instantiateODESolver(java.lang.String className) Instantiate an ODESolver from its classname.
protected boolean	_isDebugging() Return true if debugging is turned on.
protected boolean	_isIntermediateStep() Return true if the solver is at the first or intermediate steps of a multi-step solver.
private boolean	_postfireAtTopLevel() Postfire method when this director is at the top level.
private boolean	_postfireWithEnclosingContinuousDirector() Postfire method when the enclosing director is an instance of this same class.
private boolean	_postfireWithEnclosingNonContinuousDirector() Postfire method when the enclosing director is not an instance of this same class.
private boolean	_prefireAtTopLevel() Prefire method when this director is at the top level.
private boolean	_prefireWithEnclosingContinuousDirector() Prefire method when the enclosing director is an instance of this same class.
private boolean	_prefireWithEnclosingNonContinuousDirector() Prefire method when the enclosing director is not an instance of this same class.
protected void	_reportDebugMessage(java.lang.String message) Expose the debug method to the package.
private void	_setCurrentStepSize(double stepSize) Set the current step size.
private java.util.List	_statefulComponents() Return a list of stateful components, which includes actors deeply contained within the container of this director that implement the ContinuousStatefulComponent interface and directors of opaque composite actors within the container of this director that implement the same interface.
private java.util.List	_stepSizeControllers() Return a list of step-size controllers.
private boolean	_transferInputsToInside() Transfer inputs from the environment to inside.
private void	_transferOutputsToEnvironment() Transfer outputs to the environment.
Time	accumulatedSuspendTime() Return the accumulated time that the actor has been suspended since the last call to initialize(), or null if it has never been suspended.
void	attributeChanged(Attribute attribute) React to a change in an attribute.
java.lang.Object	clone(Workspace workspace) Clone the object into the specified workspace.
Dependency	delayDependency(double delay) Return a boolean dependency representing a model-time delay of the specified amount.
void	fire() Perform an integration step.
Time	fireAt(Actor actor, Time time) Handle firing requests from the contained actors by registering breakpoints.
double	getCurrentStepSize() Return the current integration step size.
double	getErrorTolerance() Return the local truncation error tolerance.
Time	getModelNextIterationTime() Return the next time of interest in the model being executed by this director or the director of any enclosing model up the hierarchy.
Time	getModelStartTime() Return the start time.
Time	getModelStopTime() Return the stop time, which is the value of the stopTime parameter, represented as an instance of the Time class.
void	initialize() Initialize model after type resolution.
boolean	isStepSizeAccurate() Return true if all step size control actors agree that the current step is accurate and if there are no breakpoints in the past.
boolean	postfire() If this director is not at the top level and the breakpoint table is not empty, request a refiring at the first breakpoint or at the local current time (iteration start time plus the step size), whichever is less.
boolean	prefire() Initialize the fixed-point iteration by setting all receivers to unknown, and return true if we have not passed the stop time.
void	preinitialize() Preinitialize the model for an execution.
double	refinedStepSize() Return the refined step size, which is the minimum of the current step size and the suggested step size of all actors that implement ContinuousStepSizeController and that also ensures that we do not pass a breakpoint.
void	resume(Time time) Resume the actor at the specified time.
void	rollBackToCommittedState() Roll back all actors that implement ContinuousStatefulComponent to committed state, and set local model time to the start of the integration period.
void	setModelTime(Time newTime) Set a new value to the current time of the model.
java.lang.String[]	suggestedModalModelDirectors() Return an array of suggested ModalModel directors to use with ContinuousDirector.
double	suggestedStepSize() Return the suggested step size for next integration.
void	suspend(Time time) Resume the actor at the specified time.
boolean	transferInputs(IOPort port) Override the base class to do nothing.
boolean	transferOutputs(IOPort port) Override the base class to do nothing.

Methods inherited from class ptolemy.actor.sched.FixedPointDirector

_receiverChanged, _resetAllReceivers, _synchronizeToRealTime, getIndex, implementsStrictActorSemantics, isFireFunctional, isStrict, newReceiver, setIndex

Methods inherited from class ptolemy.actor.sched.StaticSchedulingDirector

_setScheduler, addDebugListener, getScheduler, invalidateSchedule, isScheduleValid, removeDebugListener, setScheduler

Methods inherited from class ptolemy.actor.Director

_description, _fireContainerAt, _isEmbedded, _isTopLevel, _transferInputs, _transferOutputs, addInitializable, createSchedule, defaultDependency, finish, fireAt, fireAtCurrentTime, getCausalityInterface, getCurrentTime, getGlobalTime, getModelTime, getNextIterationTime, getStartTime, getStopTime, getTimeResolution, initialize, invalidateResolvedTypes, isStopRequested, iterate, preinitialize, removeInitializable, requestInitialization, setContainer, setCurrentTime, stop, stopFire, supportMultirateFiring, terminate, wrapup

Methods inherited from class ptolemy.kernel.util.Attribute

_checkContainer, _getContainedObject, _propagateExistence, getContainer, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, setName, updateContent

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _recordDecoratedAttributes, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, propagateExistence, propagateValue, propagateValues, removeChangeListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, uniqueName, validateSettables, workspace

Methods inherited from class java.lang.Object

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

Methods inherited from interface ptolemy.actor.TimedDirector

getModelTime, getTimeResolution

Methods inherited from interface ptolemy.actor.Executable

isFireFunctional, isStrict, iterate, stop, stopFire, terminate

Methods inherited from interface ptolemy.actor.Initializable

addInitializable, removeInitializable, wrapup

Field Detail

errorTolerance

public Parameter errorTolerance

Error tolerance for data values, used with variable step size solvers to determine whether the current step size is accurate. The default value is 1e-4, and the type is double.

initStepSize

public Parameter initStepSize

User's hint for the initial integration step size. The default value is 0.1, and the type is double.

maxIterations

public Parameter maxIterations

The maximum number of rounds that an ODE solver can use to resolve the states of integrators. Many solvers, such as RK 2-3 and RK 4-5, use a fixed number of rounds (3 and 6, respectively). Implicit ODE solvers use however many rounds it takes to converge to a solution within a specified accuracy (given by errorTolerance). An example of an implicit solver is the BackwardsEuler solver. This parameter limits the number of rounds. The default value is 20, and the type is int.

maxStepSize

public Parameter maxStepSize

The maximum step size. The default value is 1.0, and the type is double.

ODESolver

public StringParameter ODESolver

The class name of the ODE solver used for integration. This is a string that defaults to "ExplicitRK23Solver". Solvers are all required to be in package "ptolemy.domains.continuous.kernel.solver". If a solver is changed during execution, the change does not take effect until the next execution of the model. If there is another ContinuousDirector above this one in the hierarchy, separated possibly by MultiComposite, then the value of this parameter is ignored and the solver given by the other ContinuousDirector will be used.

startTime

public Parameter startTime

Starting time of the execution. The default value is 0.0, and the type is double. This parameter has no effect if this director is used inside an enclosing ContinuousDirector and after the simulation starts.

stopTime

public Parameter stopTime

Stop time of the simulation. The default value is Infinity, and the type is double. This parameter has no effect after the simulation starts.

_isInitializing

protected boolean _isInitializing

A local boolean variable indicating whether this director is in initialization phase execution.

_iterationBeginTime

protected Time _iterationBeginTime

The current time at the start of the current integration step.

_timeBase

protected long _timeBase

The real starting time in term of system millisecond counts.

_accumulatedSuspendTime

private Time _accumulatedSuspendTime

The accumulated suspend time relative to an eclosing ContinuousDirector, calculated as a side effect of calling _enclosingContinuousDirector().

_breakpoints

private TotallyOrderedSet _breakpoints

A table for breakpoints.

_commitIsPending

private boolean _commitIsPending

Flag indicating that postfire() did not commit the state at the local current time.

_currentStepSize

private double _currentStepSize

Simulation step sizes.

_enclosingContinuousDirector

private ContinuousDirector _enclosingContinuousDirector

The enclosing continuous director.

_enclosingContinuousDirectorVersion

private long _enclosingContinuousDirectorVersion

The version for __enclosingContinuousDirector.

_errorTolerance

private double _errorTolerance

The error tolerance for state resolution.

_ignoreSetTime

private boolean _ignoreSetTime

Flag to temporarily ignore the setModelTime() calls.

_initStepSize

private double _initStepSize

A cache of the value of initStepSize.

_isIntermediateStep

private boolean _isIntermediateStep

Flag indicating that the solver is iterating through the first or intermediate steps in a multi-step solver.

_iterationBeginIndex

private int _iterationBeginIndex

The index of the time at which the current integration step began.

_lastSuspendTime

private Time _lastSuspendTime

The environment time when this refinement was last suspended (that is, the enclosing state was exited). This is null if the actor has not been suspended since initialize() or resume() has been called more recently than suspend().

_maxIterations

private int _maxIterations

The maximum iterations for implicit ODE solver to resolve states.

_maxStepSize

private double _maxStepSize

The maximum step size used for integration.

_ODESolver

private ContinuousODESolver _ODESolver

The ODE solver, which is an instance of the class given by the ODESolver parameter.

_redoingSolverIteration

private boolean _redoingSolverIteration

Flag indicating that we are redoing a speculative solver iteration.

_solverClasspath

private static java.lang.String _solverClasspath

The package name for the solvers supported by this director.

_startTime

private Time _startTime

The cached value of the startTime parameter.

_statefulComponents

private java.util.List _statefulComponents

The list of stateful actors.

_statefulComponentsVersion

private long _statefulComponentsVersion

The version for the list of step size control actors.

_stepSizeControllers

private java.util.List _stepSizeControllers

The list of step size control actors.

_stepSizeControllersVersion

private long _stepSizeControllersVersion

The version for the list of step size control actors.

_stopTime

private Time _stopTime

The cached value of the stopTime parameter.

_triedTheMinimumStepSize

private boolean _triedTheMinimumStepSize

The local flag variable indicating whether the we have tried the time resolution as the integration step size.

_zeroTime

private Time _zeroTime

Time with value 0.0.

Constructor Detail

ContinuousDirector

public ContinuousDirector(CompositeEntity container,
                          java.lang.String name)
                   throws IllegalActionException,
                          NameDuplicationException

Construct a director in the given container with the given name. The container argument must not be null, or a NullPointerException will be thrown. If the name argument is null, then the name is set to the empty string. All the parameters take their default values.

Parameters:

container - The container.

name - Name of this director.

Throws:

IllegalActionException - If the director is not compatible with the specified container. May be thrown by a derived class.

NameDuplicationException - If the name collides with a property in the container.

Method Detail

accumulatedSuspendTime

public Time accumulatedSuspendTime()

Return the accumulated time that the actor has been suspended since the last call to initialize(), or null if it has never been suspended.

Specified by:

accumulatedSuspendTime in interface Suspendable

Returns:

The total time between calls to suspend and subsequent calls to resume, or null if the actor has not been suspended.

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

React to a change in an attribute. If the changed attribute matches a parameter of the director, then the corresponding local copy of the parameter value will be updated.

Overrides:

attributeChanged in class Director

Parameters:

attribute - The changed parameter.

Throws:

IllegalActionException - If the new parameter value is not valid.

clone

public java.lang.Object clone(Workspace workspace)
                       throws java.lang.CloneNotSupportedException

Clone the object into the specified workspace. The new object is not added to the directory of that workspace (you must do this yourself if you want it there).

Overrides:

clone in class FixedPointDirector

Parameters:

workspace - The workspace for the cloned object.

Returns:

The new Attribute.

Throws:

java.lang.CloneNotSupportedException - Not thrown in this base class

See Also:

NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

delayDependency

public Dependency delayDependency(double delay)

Return a boolean dependency representing a model-time delay of the specified amount.

Specified by:

delayDependency in interface TimedDirector

Parameters:

delay - A non-negative delay.

Returns:

A boolean dependency representing a delay.

fire

public void fire()
          throws IllegalActionException

Perform an integration step. This invokes prefire() and fire() of actors (possibly repeatedly) and advances the local view of time by one step. This normally involves three nested iterative procedures. The outer procedure invokes the possibly multiple steps of the solver (if it is a multistep solver), unless the step size is zero. The middle one iterates until a suitable step size is found. The inner one, implemented by the superclass, iterates until a fixed point is found at each time point.

If there is an enclosing ContinuousDirector, however, then this method simply performs the current round of execution of the enclosing director, using the step size of the enclosing director.

Specified by:

fire in interface Executable

Overrides:

fire in class FixedPointDirector

Throws:

IllegalActionException - If an actor throws it.

fireAt

public Time fireAt(Actor actor,
                   Time time)
            throws IllegalActionException

Handle firing requests from the contained actors by registering breakpoints. If the specified time is earlier than the current time, then request a firing at the current time. Otherwise, insert the specified time into the breakpoint table. If the specified time is earlier than or equal to the current time, then for the breakpoint table entry, use an index one larger than the current index, unless this director is currently in initialize(), in which case use the current index.

Overrides:

fireAt in class Director

Parameters:

actor - The actor that requests the firing.

time - The requested firing time.

Returns:

The time at which the actor passed as an argument will be fired.

Throws:

IllegalActionException - If the time is earlier than the current time.

See Also:

Director.fireAtCurrentTime(Actor)

getCurrentStepSize

public final double getCurrentStepSize()

Return the current integration step size.

Returns:

The current integration step size.

getErrorTolerance

public final double getErrorTolerance()

Return the local truncation error tolerance.

Overrides:

getErrorTolerance in class Director

Returns:

The local truncation error tolerance.

getModelNextIterationTime

public Time getModelNextIterationTime()

Return the next time of interest in the model being executed by this director or the director of any enclosing model up the hierarchy. If this director is at the top level, then this default implementation simply returns infinity, indicating that this director has no interest in any future time. If this director is not at the top level, then return whatever the enclosing director returns.

This method is useful for domains that perform speculative execution (such as Continuous itself). Such a domain in a hierarchical model (i.e. CT inside DE) uses this method to determine how far into the future to execute. This is simply an optimization that reduces the likelihood of having to roll back.

The base class implementation in Director is almost right, but not quite, because at the top level it returns current time. However, this director should not constrain any director below it from speculatively executing into the future. Instead, it assumes that any director below it implements a strict actor semantics. Note in particular that the implementation below would block time advancement in a Continuous in DE in Continuous model because the top-level model will usually only invoke the DE model during a zero-step execution, which means that the returned next iteration time will always be current time, which will force the inside Continuous director to have a zero step size always.

Overrides:

getModelNextIterationTime in class Director

Returns:

The next time of interest.

See Also:

Director.getModelTime()

getModelStartTime

public final Time getModelStartTime()
                             throws IllegalActionException

Return the start time. If this director is not at the top level, then this method returns the start time of the executive director. Otherwise, it returns the value given by the startTime parameter. This will be null before preinitialize() is called.

Overrides:

getModelStartTime in class Director

Returns:

The start time.

Throws:

IllegalActionException - If the enclosing director throws it.

getModelStopTime

public final Time getModelStopTime()

Return the stop time, which is the value of the stopTime parameter, represented as an instance of the Time class. This will be null before preinitialize() is called.

Overrides:

getModelStopTime in class Director

Returns:

The stop time.

initialize

public void initialize()
                throws IllegalActionException

Initialize model after type resolution. In addition to calling the initialize() method of the super class, this method records the current system time as the "real" starting time of the execution. This starting time is used when the execution is synchronized to real time.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class FixedPointDirector

Throws:

IllegalActionException - If the super class throws it.

isStepSizeAccurate

public boolean isStepSizeAccurate()

Return true if all step size control actors agree that the current step is accurate and if there are no breakpoints in the past.

Specified by:

isStepSizeAccurate in interface ContinuousStepSizeController

Returns:

True if all step size control actors agree with the current step size.

postfire

public boolean postfire()
                 throws IllegalActionException

If this director is not at the top level and the breakpoint table is not empty, request a refiring at the first breakpoint or at the local current time (iteration start time plus the step size), whichever is less. Postfire all controlled actors.

If the synchronizeToRealTime parameter is true, then this method will block execution until the real time catches up with current model time. The units for time are seconds.

Specified by:

postfire in interface Executable

Overrides:

postfire in class FixedPointDirector

Returns:

True if the Director wants to be fired again in the future.

Throws:

IllegalActionException - If the current model time exceeds the stop time, or refiring can not be granted, or the super class throws it.

prefire

public boolean prefire()
                throws IllegalActionException

Initialize the fixed-point iteration by setting all receivers to unknown, and return true if we have not passed the stop time. Record the current model time as the beginning time of the current iteration, and if there is a pending invocation of postfire() from a previous integration step, invoke that now.

Specified by:

prefire in interface Executable

Overrides:

prefire in class FixedPointDirector

Returns:

True if this director is ready to fire.

Throws:

IllegalActionException - If thrown by the super class, or if the model time of the environment is less than our current model time.

preinitialize

public void preinitialize()
                   throws IllegalActionException

Preinitialize the model for an execution. This method is called only once for each simulation.

Specified by:

preinitialize in interface Initializable

Overrides:

preinitialize in class Director

Throws:

IllegalActionException - If the super class throws it, or local variables cannot be initialized.

refinedStepSize

public double refinedStepSize()
                       throws IllegalActionException

Return the refined step size, which is the minimum of the current step size and the suggested step size of all actors that implement ContinuousStepSizeController and that also ensures that we do not pass a breakpoint. If these actors request a step size smaller than the time resolution, then the first time this happens this method returns the time resolution. If it happens again on the next call to this method, then this method throws an exception.

Specified by:

refinedStepSize in interface ContinuousStepSizeController

Returns:

The refined step size.

Throws:

IllegalActionException - If the scheduler throws it or the refined step size is less than the time resolution.

resume

public void resume(Time time)
            throws IllegalActionException

Resume the actor at the specified time. If the actor has not been suspended since the last call to initialize(), then this has no effect.

Specified by:

resume in interface Suspendable

Parameters:

time - The time at which the actor is resumed.

Throws:

IllegalActionException - If the fireAt() request throws it.

rollBackToCommittedState

public void rollBackToCommittedState()

Roll back all actors that implement ContinuousStatefulComponent to committed state, and set local model time to the start of the integration period.

Specified by:

rollBackToCommittedState in interface ContinuousStatefulComponent

setModelTime

public final void setModelTime(Time newTime)
                        throws IllegalActionException

Set a new value to the current time of the model. This overrides the base class to allow time to move backwards (to support rollback) and to discard any breakpoints in the breakpoint table that are in the past relative to the specified time. This overrides the setCurrentTime() in the Director base class. Although this method is public, actors should never call it.

Overrides:

setModelTime in class Director

Parameters:

newTime - The new current simulation time.

Throws:

IllegalActionException - If the time is in the past relative to the time of local committed state.

See Also:

Director.getModelTime()

suggestedModalModelDirectors

public java.lang.String[] suggestedModalModelDirectors()

Return an array of suggested ModalModel directors to use with ContinuousDirector. The only available director is ModalDirector because we need a director that implements the strict actor semantics.

Overrides:

suggestedModalModelDirectors in class FixedPointDirector

Returns:

An array of suggested directors to be used with ModalModel.

See Also:

Director.suggestedModalModelDirectors()

suggestedStepSize

public double suggestedStepSize()
                         throws IllegalActionException

Return the suggested step size for next integration. The suggested step size is the minimum of suggestions from all step size control actors and the time until the next breakpoint, and it never exceeds 10 times of the current step size. If there are no step size control actors at all, then return 5 times of the current step size. However, the suggested step size never exceeds the maximum step size. If this director has not been fired since initialize() or the previous call to suggestedStepSize(), then return the value of maxStepSize.

Specified by:

suggestedStepSize in interface ContinuousStepSizeController

Returns:

The suggested step size for next integration.

Throws:

IllegalActionException - If an actor suggests an illegal step size.

suspend

public void suspend(Time time)
             throws IllegalActionException

Resume the actor at the specified time. If the actor has not been suspended since the last call to initialize(), then this has no effect.

Specified by:

suspend in interface Suspendable

Parameters:

time - The time at which the actor is suspended.

Throws:

IllegalActionException - If the suspend cannot be completed.

transferInputs

public boolean transferInputs(IOPort port)
                       throws IllegalActionException

Override the base class to do nothing. The fire() method of this director handles transferring inputs.

Overrides:

transferInputs in class FixedPointDirector

Parameters:

port - The port to transfer tokens from.

Returns:

False.

Throws:

IllegalActionException - Not thrown in this base class.

transferOutputs

public boolean transferOutputs(IOPort port)
                        throws IllegalActionException

Override the base class to do nothing. The fire() method of this director handles transferring outputs.

Overrides:

transferOutputs in class FixedPointDirector

Parameters:

port - The port to transfer tokens from.

Returns:

False.

Throws:

IllegalActionException - Not thrown in this base class.

_getCurrentStepSize

protected double _getCurrentStepSize()

Return the current step size.

Returns:

The current step size.

_getODESolver

protected final ContinuousODESolver _getODESolver()

Return the ODE solver used to resolve states by the director.

Returns:

The ODE solver used to resolve states by the director.

_initParameters

protected void _initParameters()

Create and initialize all parameters to their default values. This is called by the constructor.

_instantiateODESolver

protected final ContinuousODESolver _instantiateODESolver(java.lang.String className)
                                                   throws IllegalActionException

Instantiate an ODESolver from its classname. Given the solver's full class name, this method will try to instantiate it by looking for the corresponding java class.

Parameters:

className - The solver's full class name.

Returns:

a new ODE solver.

Throws:

IllegalActionException - If the solver can not be created.

_isDebugging

protected final boolean _isDebugging()

Return true if debugging is turned on. This exposes whether debugging is happening to the package.

Returns:

True if debugging is turned on.

_isIntermediateStep

protected boolean _isIntermediateStep()
                               throws IllegalActionException

Return true if the solver is at the first or intermediate steps of a multi-step solver. If there is an enclosing continuous director, this method delegates to that director. Otherwise, it checks the current step of the solver.

Returns:

True if either the solver is not doing a multi-step solution or it is at the last step of the multi-step solution.

Throws:

IllegalActionException - If the Time class throws it.

_reportDebugMessage

protected void _reportDebugMessage(java.lang.String message)

Expose the debug method to the package.

Parameters:

message - The message that is to be reported.

_assertAbsentInside

private void _assertAbsentInside()
                          throws IllegalActionException

Set all receivers on the inside of input ports to absent.

Throws:

IllegalActionException - If the send fails.

_commit

private boolean _commit()
                 throws IllegalActionException

Commit the current state by postfiring the actors under the control of this director. Also, set the current time, index, and step size for the next iteration. If the current step size is 0.0, then this just increments the index. Otherwise, it sets the index to 0.

Returns:

True if it is OK to fire again.

Throws:

IllegalActionException

_enclosingContinuousDirector

private ContinuousDirector _enclosingContinuousDirector()

Return the enclosing continuous director, or null if there is none. The enclosing continuous director is a director above this in the hierarchy, possibly separated by composite actors with actors that implement the QuasiTransparentDirector interface, such as FSMDirector or CaseDirector.

Returns:

The enclosing ContinuousDirector, or null if there is none.

_handleBreakpointsBefore

private void _handleBreakpointsBefore(Time time,
                                      int index)
                               throws IllegalActionException

Throw an exception if there are any breakpoints in the breakpoint table before the specified time.

Parameters:

time - The time.

index - The superdense time index.

Throws:

IllegalActionException - If there are any breakpoints in the breakpoint table earlier than the specified time.

_initializeLocalVariables

private void _initializeLocalVariables()
                                throws IllegalActionException

Initialize the local variables of this ContinuousDirector. Create or clear the breakpoints table. Instantiate an ODE solver. This method is called in the preinitialize method.

Throws:

IllegalActionException

_postfireAtTopLevel

private boolean _postfireAtTopLevel()
                             throws IllegalActionException

Postfire method when this director is at the top level.

Returns:

True if it is OK to fire again.

Throws:

IllegalActionException

_postfireWithEnclosingContinuousDirector

private boolean _postfireWithEnclosingContinuousDirector()
                                                  throws IllegalActionException

Postfire method when the enclosing director is an instance of this same class.

Returns:

True if it is OK to fire again.

Throws:

IllegalActionException

_postfireWithEnclosingNonContinuousDirector

private boolean _postfireWithEnclosingNonContinuousDirector()
                                                     throws IllegalActionException

Postfire method when the enclosing director is not an instance of this same class.

Returns:

True if it is OK to fire again.

Throws:

IllegalActionException

_prefireAtTopLevel

private boolean _prefireAtTopLevel()
                            throws IllegalActionException

Prefire method when this director is at the top level.

Returns:

True if it is OK to fire.

Throws:

IllegalActionException

_prefireWithEnclosingContinuousDirector

private boolean _prefireWithEnclosingContinuousDirector()
                                                 throws IllegalActionException

Prefire method when the enclosing director is an instance of this same class.

Returns:

True if it is OK to fire.

Throws:

IllegalActionException

_prefireWithEnclosingNonContinuousDirector

private boolean _prefireWithEnclosingNonContinuousDirector()
                                                    throws IllegalActionException

Prefire method when the enclosing director is not an instance of this same class.

Returns:

True if it is OK to fire.

Throws:

IllegalActionException

_setCurrentStepSize

private void _setCurrentStepSize(double stepSize)

Set the current step size.

Parameters:

stepSize - The step size to be set.

See Also:

_currentStepSize

_statefulComponents

private java.util.List _statefulComponents()

Return a list of stateful components, which includes actors deeply contained within the container of this director that implement the ContinuousStatefulComponent interface and directors of opaque composite actors within the container of this director that implement the same interface.

Returns:

A list of objects implementing ContinuousStatefulComponent.

_stepSizeControllers

private java.util.List _stepSizeControllers()

Return a list of step-size controllers.

Returns:

A list of step-size control actors.

_transferInputsToInside

private boolean _transferInputsToInside()
                                 throws IllegalActionException

Transfer inputs from the environment to inside.

Returns:

True if at least one token is transferred.

Throws:

IllegalActionException - If the transferInputs(Port) method throws it.

_transferOutputsToEnvironment

private void _transferOutputsToEnvironment()
                                    throws IllegalActionException

Transfer outputs to the environment.

Throws:

IllegalActionException - If the transferOutputs(Port) method throws it.