Package ptolemy.domains.continuous.kernel

Class ContinuousDirector

  • All Implemented Interfaces:
    java.lang.Cloneable, ContinuousStatefulComponent, ContinuousStatefulDirector, ContinuousStepSizeController, Executable, Initializable, SuperdenseTimeDirector, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    public class ContinuousDirector
extends FixedPointDirector
implements ContinuousStatefulDirector, ContinuousStepSizeController
    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:

    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.
    • 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$
    Author:
    Haiyang Zheng and Edward A. Lee, based on CTDirector by Jie Liu and Haiyang Zheng
    Pt.AcceptedRating:
    Red (hyzheng)
    Pt.ProposedRating:
    Yellow (hyzheng)

    • 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.

      • _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.

    • 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

      • 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.

      • 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,
                   int index)
            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. If the requested time is in the future, then use the requested index.
        Overrides:
        fireAt in class Director
        Parameters:
        actor - The actor that requests the firing.
        time - The requested firing time.
        index - The microstep.
        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), Director.fireContainerAt(Time)

      • getCurrentStepSize

        public final double getCurrentStepSize()
        Return the current integration step size.
        Specified by:
        getCurrentStepSize in interface ContinuousStatefulDirector
        Returns:
        The current integration step size.

      • getErrorTolerance

        public final double getErrorTolerance()
        Return the local truncation error tolerance.
        Specified by:
        getErrorTolerance in interface ContinuousStatefulDirector
        Returns:
        The local truncation error tolerance.

      • initialize

        public void initialize()
                throws IllegalActionException
        Initialize model after type resolution. If a start time has been explicitly set, then set the start time to that value. Otherwise, inherit if from the environment, if there is one, and set it to 0.0 otherwise. 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.

      • 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()
            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.
        Overrides:
        resume in class Director
        Throws:
        IllegalActionException - If the fireAt() request throws it.

      • 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.

      • _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.