ptolemy.domains.ct.kernel
Class CTDirector

java.lang.Object
  extended byptolemy.kernel.util.NamedObj
      extended byptolemy.kernel.util.Attribute
          extended byptolemy.actor.Director
              extended byptolemy.actor.sched.StaticSchedulingDirector
                  extended byptolemy.domains.ct.kernel.CTDirector
All Implemented Interfaces:
Changeable, java.lang.Cloneable, Debuggable, DebugListener, Derivable, Executable, ModelErrorHandler, MoMLExportable, Nameable, java.io.Serializable
Direct Known Subclasses:
CTMultiSolverDirector

public abstract class CTDirector
extends StaticSchedulingDirector

This is the abstract base class for directors in the CT domain.

A CTDirector has a CTScheduler which provides the schedules for firing the actors in different phases of execution.

A CTDirector may have more than one ODE solvers. In each iteration, one of the ODE solvers is taking charge of solving the ODEs. This solver is called the current ODE solver.

The continuous time (CT) domain is a timed domain. There is a global notion of time that all the actors are aware of. Time is maintained by the director. The method getCurrentTime() returns the current notion of time. Time can be set by the setCurrentTime() method, but this method should not the called by the actors. Time can only be set by directors or their ODE solvers.

This base class maintains a list of parameters that may be used by ODE solvers and actors. These parameters are:

  • startTime: The start time of the simulation. This parameter is effective only if the director is at the top level. Default value is 0.0.
  • stopTime: The stop time of the simulation. This parameter is effective only if the director is at the top level. Default value is Double.MAX_VALUE.
  • initStepSize: The suggested integration step size by the user. This will be the step size for fixed step size ODE solvers if there is no breakpoint. However, it is just a hint otherwise. Default value is 0.1
  • minStepSize: The minimum step size that the user wants to use in the simulation. Default value is 1e-5.
  • maxStepSize: The maximum step size the user wants to use in the simulation. Usually used to control the simulation speed. Default value is 1.0.
  • maxIterations: Used only in implicit ODE solvers. This is the maximum number of iterations for finding the fixed point at one time point. Default value is 20.
  • errorTolerance: This is the local truncation error tolerance, used for controlling the integration accuracy in variable step size ODE solvers. If the local truncation error at some step size control actors are greater than this tolerance, then the integration step is considered to have failed, and should be restarted with a reduced step size. Default value 1e-4.
  • valueResolution: This is used to control the convergence of fixed point iterations. If in two successive iterations the differences of the state variables is less than this resolution, then the fixed point is considered to have reached. Default value is 1e-6.
  • timeResolution: The minimum resolution of time. If two time values differ less than this value, they are considered equivalent. Default value is 1e-10.

    This director also maintains a breakpoint table to record all predictable breakpoints that are greater than the current time. The breakpoints are sorted in their chronological order in the table. Breakpoints at the same time (controlled by the time resolution parameter) are considered to be one. 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 start time and stop time of the execution. In this case, the first parameter actor is null. The fireAt method may also be requested by the actors and the requests are handled differently depending on the second parameter time. If the time is the current time, and if the actors are discrete actors, the actors are added into a refireActor list and will be fired in the current iteration. Otherwise, the time will be inserted into the breakpoint table.

    Since:
    Ptolemy II 0.2
    Version:
    $Id: CTDirector.java,v 1.133.2.1 2004/07/31 01:09:45 cxh Exp $
    Author:
    Jie Liu
    See Also:
    Director, Serialized Form
    Accepted Rating:
    Green (chf)
    Proposed Rating:
    Green (liuj)

    Nested Class Summary
     
    Nested classes inherited from class ptolemy.kernel.util.NamedObj
    NamedObj.ContainedObjectsIterator
     
    Field Summary
    protected  boolean _postfireReturns
              This flag will be set to false if any actor returns false to postfire() during the fire() phase of the director.
    protected  java.util.LinkedList _refireActors
              A list of actors that requested to refire at the current time.
     Parameter errorTolerance
              ODE solving error tolerance, only effective in variable step size methods.
     Parameter initStepSize
              User's hint for the initial integration step size.
     Parameter maxIterations
              The maximum number of iterations in looking for a fixed-point.
     Parameter maxStepSize
              User's guide for the maximum integration step size.
     Parameter minStepSize
              User's guide for the minimum integration step size.
     Parameter startTime
              Starting time of the simulation.
     Parameter stopTime
              Stop time of the simulation.
     Parameter synchronizeToRealTime
              Indicate whether the execution will synchronize to real time.
     Parameter timeResolution
              The resolution in comparing time.
     Parameter valueResolution
              Value resolution in looking for a fixed-point.
     
    Fields inherited from class ptolemy.actor.Director
    _currentTime, _stopRequested
     
    Fields inherited from class ptolemy.kernel.util.NamedObj
    _changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS
     
    Fields inherited from interface ptolemy.actor.Executable
    COMPLETED, NOT_READY, STOP_ITERATING
     
    Constructor Summary
    CTDirector()
              Construct a director in the default workspace with an empty string as its name.
    CTDirector(CompositeEntity container, java.lang.String name)
              Construct a director in the given container with the given name.
    CTDirector(Workspace workspace)
              Construct a director in the workspace with an empty name.
     
    Method Summary
    protected  boolean _areTimesCloseEnough(double firstTime, double secondTime)
              Return true if the difference of the two given times is less than the time resolution of the director.
    protected  void _initParameters()
              Create and initialize all parameters to their default values.
    protected  ODESolver _instantiateODESolver(java.lang.String className)
              Instantiate an ODESolver from its classname.
    protected  void _setBreakpointIteration(boolean breakpoint)
              Set to indicate that this is an iteration just after a breakpoint.
    protected  void _setCurrentODESolver(ODESolver solver)
              Set the current ODE Solver to be the argument.
    protected  void _setDiscretePhase(boolean discrete)
              Set the current phase of execution as a discrete phase.
    protected  void _setIterationBeginTime(double time)
              Set the iteration begin time.
    protected  boolean _writeAccessRequired()
              Returns false always, indicating that this director does not need to modify the topology during one iteration.
     void attributeChanged(Attribute attribute)
              React to a change in an attribute.
    abstract  boolean canBeInsideDirector()
              Return true if the director can be an inside director, i.e.
    abstract  boolean canBeTopLevelDirector()
              Return true if the director can be a top-level director.
     void fireAt(Actor actor, double time)
              Handle the firing request from the containing actors.
     TotallyOrderedSet getBreakPoints()
              Return the breakpoint table.
     ODESolver getCurrentODESolver()
              Return the current ODE solver.
     double getCurrentStepSize()
              Return the current integration step size.
     double getErrorTolerance()
              Return the local truncation error tolerance, used by variable step size solvers.
     double getInitialStepSize()
              Return the initial step size.
     double getIterationBeginTime()
              Return the begin time of the current iteration.
     int getMaxIterations()
              Return the maximum number of iterations in fixed point calculation.
     double getMaxStepSize()
              Return the maximum step size used in variable step size ODE solvers.
     double getMinStepSize()
              Return the minimum step size used in variable step size ODE solvers.
     double getNextIterationTime()
              Return the current iteration begin time plus the current step size.
     double getStartTime()
              Return the start time parameter value.
     double getStopTime()
              Return the stop time.
     double getSuggestedNextStepSize()
              Return the suggested next step size.
     double getValueResolution()
              Return the value resolution, used for testing if an implicit method has reached the fixed point.
     void initialize()
              Initialization after type resolution.
     boolean isBreakpointIteration()
              Return true if this is the first iteration after a breakpoint.
     boolean isDiscretePhase()
              Return true if this is the discrete phase execution.
     boolean isPrefireComplete(Actor actor)
              Return true if the actor has been prefired in the current iteration.
     Receiver newReceiver()
              Return a new CTReceiver.
     void prefireClear()
              Clear the set of actors that have been prefired.
     void preinitialize()
              Prepare for an execution.
     void produceOutput()
              Fire all the actors in the output schedule.
     void setCurrentStepSize(double stepsize)
              Set the current step size.
     void setCurrentTime(double newTime)
              Set a new value to the current time of the model, where the new time can be earlier than the current time to support rollback.
     void setPrefireComplete(Actor actor)
              Mark the specified actor as having been prefired in the current iteration.
     void setSuggestedNextStepSize(double stepsize)
              Set the suggested next step size.
     void updateContinuousStates()
              Call postfire() on all actors in the continuous part of the model.
     
    Methods inherited from class ptolemy.actor.sched.StaticSchedulingDirector
    _setScheduler, addDebugListener, fire, getScheduler, invalidateSchedule, isScheduleValid, postfire, prefire, removeDebugListener, setScheduler, setScheduleValid
     
    Methods inherited from class ptolemy.actor.Director
    _description, _isEmbedded, _isTopLevel, domainPolymorphicTransferInputs, domainPolymorphicTransferOutputs, fireAtCurrentTime, getCurrentTime, getTimeResolution, initialize, invalidateResolvedTypes, iterate, needWriteAccess, requestInitialization, setContainer, setTimeResolution, stop, stopFire, terminate, transferInputs, transferOutputs, wrapup
     
    Methods inherited from class ptolemy.kernel.util.Attribute
    _getContainedObject, _propagateExistence, clone, getContainer, setName
     
    Methods inherited from class ptolemy.kernel.util.NamedObj
    _addAttribute, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoML, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getDerivedLevel, getDerivedList, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, message, propagateExistence, propagateValue, propagateValues, removeChangeListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setModelErrorHandler, setPersistent, setSource, toplevel, toString, uniqueName, validateSettables, workspace
     
    Methods inherited from class java.lang.Object
    equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
     

    Field Detail

    errorTolerance

    public Parameter errorTolerance
    ODE solving error tolerance, only effective in variable step size methods. The default value is 1e-4, of type DoubleToken.


    initStepSize

    public Parameter initStepSize
    User's hint for the initial integration step size. The default value is 0.1, of type DoubleToken.


    maxIterations

    public Parameter maxIterations
    The maximum number of iterations in looking for a fixed-point. The default value is 20, of type IntToken.


    maxStepSize

    public Parameter maxStepSize
    User's guide for the maximum integration step size. The default value is 1.0, of type DoubleToken.


    minStepSize

    public Parameter minStepSize
    User's guide for the minimum integration step size. The default value is 1e-5, of type DoubleToken.


    startTime

    public Parameter startTime
    Starting time of the simulation. The default value is 0.0, of type DoubleToken.


    stopTime

    public Parameter stopTime
    Stop time of the simulation. The default value is Double.MAX_VALUE, of type DoubleToken.


    synchronizeToRealTime

    public Parameter synchronizeToRealTime
    Indicate whether the execution will synchronize to real time. The default value is false.


    timeResolution

    public Parameter timeResolution
    The resolution in comparing time. The default value is 1e-10, of type DoubleToken.


    valueResolution

    public Parameter valueResolution
    Value resolution in looking for a fixed-point. The default value is 1e-6, of type DoubleToken.


    _postfireReturns

    protected boolean _postfireReturns
    This flag will be set to false if any actor returns false to postfire() during the fire() phase of the director.


    _refireActors

    protected java.util.LinkedList _refireActors
    A list of actors that requested to refire at the current time.

    Constructor Detail

    CTDirector

    public CTDirector()
    Construct a director in the default workspace with an empty string as its name. The director is added to the list of objects in the workspace. Increment the version number of the workspace. All the parameters take their default values. A CTScheduler is created.


    CTDirector

    public CTDirector(Workspace workspace)
    Construct a director in the workspace with an empty name. If the argument is null, then the default workspace will be used. The director is added to the list of objects in the workspace. Increment the version number of the workspace. All the parameters take their default values. A CTScheduler is created.

    Parameters:
    workspace - The workspace of this object.

    CTDirector

    public CTDirector(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. A CTScheduler is created.

    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

    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 NamedObj
    Parameters:
    attribute - The changed parameter.
    Throws:
    IllegalActionException - If the parameter set is not valid.

    canBeInsideDirector

    public abstract boolean canBeInsideDirector()
    Return true if the director can be an inside director, i.e. a director of an opaque composite actor not at the top level. Derived class should override this to show whether it can serve as an inside director.


    canBeTopLevelDirector

    public abstract boolean canBeTopLevelDirector()
    Return true if the director can be a top-level director. Derived class should override this to show whether it can serve as a top-level director.


    fireAt

    public void fireAt(Actor actor,
                       double time)
                throws IllegalActionException
    Handle the firing request from the containing actors. If the specified time is the current time (within the timeResolution of this director), and the actor is not null nor a step size control actor, then the actor will be added into a refiredActors list and fired as part of the current execution phase. If the specified time is in the future, or the actor is null, or the actor is a step size control actor, this director will register a breakpoint at the specified time.

    From this director's point of view, it is irrelevant which actor requests the breakpoint. All actors will be executed at every breakpoint.

    If the actor is null, it indicates the time for the start or the stop of an execution. Otherwise, it is the actor that requests the firing.

    In CT domain, the signals may be piecewise continuous. They may generate discontinuities at some time points. In order to generate the discontinuities, the actors request to be fired at some time as many times as necessary, and each time they produce some outputs. The CT director does not deal with discontinuity but only handle the requests from the actors it contains. For example, the ContinuousClock actor fires twice at each offset.

    Overrides:
    fireAt in class Director
    Parameters:
    actor - The actor that requested the firing or null that indicates the time of the start or stop of an execution.
    time - The requested firing time.
    Throws:
    IllegalActionException - If the time is earlier than the current time.

    getBreakPoints

    public final TotallyOrderedSet getBreakPoints()
    Return the breakpoint table. If the breakpoint table has never been created, then return null. This method is final for performance reason.

    Returns:
    The breakpoint table.

    getCurrentODESolver

    public final ODESolver getCurrentODESolver()
    Return the current ODE solver. This method is final for performance reason.

    Returns:
    The current ODE solver.

    getCurrentStepSize

    public final double getCurrentStepSize()
    Return the current integration step size. This method is final for performance reason.

    Returns:
    The current step size.

    getErrorTolerance

    public final double getErrorTolerance()
    Return the local truncation error tolerance, used by variable step size solvers. This method is final for performance reason.

    Returns:
    The local truncation error tolerance.

    getInitialStepSize

    public final double getInitialStepSize()
    Return the initial step size. This method is final for performance reason.

    Returns:
    The initial step size.

    getIterationBeginTime

    public final double getIterationBeginTime()
    Return the begin time of the current iteration. This method is final for performance reason.

    Returns:
    The begin time of the current iteration.

    getMaxIterations

    public final int getMaxIterations()
    Return the maximum number of iterations in fixed point calculation. If the iteration has exceeded this number and the fixed point is still not found, then the algorithm is considered to have failed. This method is final for performance reason.

    Returns:
    The maximum number of iterations when calculating fixed points.

    getMaxStepSize

    public final double getMaxStepSize()
    Return the maximum step size used in variable step size ODE solvers. This method is final for performance reason.

    Returns:
    The maximum step size.

    getMinStepSize

    public final double getMinStepSize()
    Return the minimum step size used in variable step size ODE solvers. This method is final for performance reason.

    Returns:
    The minimum step size.

    getNextIterationTime

    public double getNextIterationTime()
    Return the current iteration begin time plus the current step size.

    Overrides:
    getNextIterationTime in class Director
    Returns:
    The iteration begin time plus the current step size.

    getStartTime

    public final double getStartTime()
    Return the start time parameter value. This method is final for performance reason.

    Returns:
    the start time.

    getStopTime

    public final double getStopTime()
    Return the stop time. This method is final for performance reason.

    Returns:
    the stop time.

    getSuggestedNextStepSize

    public final double getSuggestedNextStepSize()
    Return the suggested next step size. The suggested step size is the minimum step size that the step-size-control actors suggested at the end of last integration step. It is the prediction of the new step size. This method is final for performance reason.

    Returns:
    The suggested next step size.

    getValueResolution

    public final double getValueResolution()
    Return the value resolution, used for testing if an implicit method has reached the fixed point. Two values that are differed less than this accuracy are considered identical in the fixed point calculation. This method is final for performance reason.

    Returns:
    The value resolution for finding fixed point.

    initialize

    public void initialize()
                    throws IllegalActionException
    Initialization after type resolution. In addition to calling the initialize() method of its 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 Executable
    Overrides:
    initialize in class Director
    Throws:
    IllegalActionException - If the super class throws it.

    isBreakpointIteration

    public final boolean isBreakpointIteration()
    Return true if this is the first iteration after a breakpoint. In a breakpoint iteration, the ODE solver is the breakpoint ODE solver, and the step size is zero or the minimum step size. This method is final for performance reason.

    Returns:
    True if this is a breakpoint iteration.

    isDiscretePhase

    public final boolean isDiscretePhase()
    Return true if this is the discrete phase execution.

    Returns:
    True if this is the discrete phase execution.

    isPrefireComplete

    public boolean isPrefireComplete(Actor actor)
    Return true if the actor has been prefired in the current iteration.

    Parameters:
    actor - The actor about which we are asking.
    Returns:
    True if the actor has been prefired.
    See Also:
    setPrefireComplete(Actor)

    newReceiver

    public Receiver newReceiver()
    Return a new CTReceiver.

    Overrides:
    newReceiver in class Director
    Returns:
    A new CTReceiver.

    prefireClear

    public void prefireClear()
    Clear the set of actors that have been prefired.


    preinitialize

    public void preinitialize()
                       throws IllegalActionException
    Prepare for an execution. If this director does not have a container and a scheduler, or the director does not fit this level of hierarchy, an IllegalActionException will be thrown. Invalidate the schedule. Clear statistical variables. Clear the break point table. Preinitialize all the directed actors. Time does not have a meaning yet. So actors should not use a notion of time at the preinitialize stage.

    Specified by:
    preinitialize in interface Executable
    Overrides:
    preinitialize in class Director
    Throws:
    IllegalActionException - If the director has no container, the director does not fit this level of hierarchy, or there is no scheduler.

    produceOutput

    public void produceOutput()
                       throws IllegalActionException
    Fire all the actors in the output schedule. If they have not had prefire() called in the current simulation cycle, then first call prefire(). The abstract semantics of Ptolemy II require that prefire() be called exactly once in an iteration. This is important because, for example, time can only be tested reliably in prefire(). It indicates the starting point of an integration step. During the multiple iterations of fires, time may progress in micro steps, depending on the ODE solver used. Hierarchies in CT and hybrid systems cases actually rely on this fact to control internal step sizes.

    Throws:
    IllegalActionException - If an actor in the output schedule throws it.

    setCurrentStepSize

    public void setCurrentStepSize(double stepsize)
    Set the current step size. The current step size is very import during the simulation and should NOT be changed in the middle of an iteration.

    Parameters:
    stepsize - The step size to be set.

    setCurrentTime

    public void setCurrentTime(double newTime)
    Set a new value to the current time of the model, where the new time can be earlier than the current time to support rollback. This overrides the setCurrentTime() in the Director base class. It is OK that the new time is less than the current time in the director, since CT sometimes needs roll-back. This is a critical parameter in an execution, and the actors are not supposed to call it.

    Overrides:
    setCurrentTime in class Director
    Parameters:
    newTime - The new current simulation time.

    setPrefireComplete

    public void setPrefireComplete(Actor actor)
    Mark the specified actor as having been prefired in the current iteration.

    Parameters:
    actor - The actor about which we are asking.
    See Also:
    isPrefireComplete(Actor)

    setSuggestedNextStepSize

    public void setSuggestedNextStepSize(double stepsize)
    Set the suggested next step size. If the argument is large than the maximum step size, then set the suggested next step size to the maximum step size.

    Parameters:
    stepsize - The suggested next step size.

    updateContinuousStates

    public void updateContinuousStates()
                                throws IllegalActionException
    Call postfire() on all actors in the continuous part of the model. For a correct CT simulation, the state of an actor can only change at this stage of an iteration. If the synchronizeToRealTime parameter is true, then this method will block until the real time catches up to current modeling time.

    Throws:
    IllegalActionException - If any of the actors throws it.

    _areTimesCloseEnough

    protected boolean _areTimesCloseEnough(double firstTime,
                                           double secondTime)
    Return true if the difference of the two given times is less than the time resolution of the director. In this case, these two times are regarded to be same.

    Parameters:
    firstTime - The first time.
    secondTime - The second time.
    Returns:
    True If the difference of these two times is less than the time resolution.

    _initParameters

    protected void _initParameters()
    Create and initialize all parameters to their default values.


    _instantiateODESolver

    protected ODESolver _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 java class.

    Parameters:
    className - The solver's full class name.
    Throws:
    IllegalActionException - If the solver is unable to be created.

    _setBreakpointIteration

    protected void _setBreakpointIteration(boolean breakpoint)
    Set to indicate that this is an iteration just after a breakpoint. A CTDirector, after finding out that a breakpoint has happened at the current time, should call this method with a true argument. In the next iteration, the solver may be changed to handle the breakpoint.

    Parameters:
    breakpoint - True if this is a breakpoint iteration.

    _setCurrentODESolver

    protected void _setCurrentODESolver(ODESolver solver)
                                 throws IllegalActionException
    Set the current ODE Solver to be the argument. Derived class may throw an exception if the argument cannot serve as the current ODE solver

    Parameters:
    solver - The solver to set.
    Throws:
    IllegalActionException - Not thrown in this base class. It may be thrown by the derived classes if the solver is not appropriate.

    _setDiscretePhase

    protected void _setDiscretePhase(boolean discrete)
    Set the current phase of execution as a discrete phase. The value set will be returned by the isDiscretePhase() method.

    Parameters:
    discrete - True if this is the discrete phase.

    _setIterationBeginTime

    protected void _setIterationBeginTime(double time)
    Set the iteration begin time. The iteration begin time is the start time for one integration step. This variable is used when the integration step is failed, and need to be restarted with another step size.

    Parameters:
    time - The iteration begin time.

    _writeAccessRequired

    protected boolean _writeAccessRequired()
    Returns false always, indicating that this director does not need to modify the topology during one iteration.

    Overrides:
    _writeAccessRequired in class Director
    Returns:
    False.