Package ptolemy.actor.lib

Class DiscreteClock

  • All Implemented Interfaces:
    java.lang.Cloneable, Actor, Executable, FiringsRecordable, Initializable, TimedActor, TypedActor, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    Direct Known Subclasses:
    DiscreteClock, Waveform
    public class DiscreteClock
extends TimedSource
    This actor produces a periodic signal, a sequence of events at regularly spaced intervals. At the beginning of each time interval of length given by period, starting from the time at which initialize() is invoked, this actor initiates a sequence of output events with values given by values and offset into the period given by offsets. These parameters contain arrays, which are required to have the same length. The offsets array contains doubles, which must be nondecreasing and nonnegative, or an exception will be thrown when it is set. If any entry is greater than the period then the corresponding output will never be produced. To get a finite sequence of events that is not periodic, just set period to Infinity. Alternatively, you can provide a finite stopTime. Upon reaching that stop time, postfire() returns false, which requests that the director not fire this actor again. The clock can also be started and stopped repeatedly during an execution. A token at the start input will start the clock at the beginning of a period. A token at the stop input will stop the clock, if it is still running. If both start and stop are received simultaneously, then the clock will be stopped.

    The values parameter by default contains the array {1}. The default offsets array is {0.0}. The default period is 1.0.

    The type of the output can be any token type. This type is inferred from the element type of the values parameter.

    For example, if values = {1, 2, 3}, offsets = {0.1, 0.2, 0.3}, period = 1.0, and the actor is initialized at time 0.0, then it will produce outputs with value 1 at all times n + 0.1, outputs with value 2 at all times n + 0.2, and outputs with value 3 at all times n + 0.3, for all non-negative integers n.

    If the actor is not fired by the enclosing director at the time of the next expected output, then it will stop producing outputs. This should not occur. If it does, it is a bug in the director.

    If the director that this is used with supports superdense time (like DE, Continuous), then the outputs are normally produced at microstep index 1. The reason for producing outputs at index 1 is to maintain continuity in continuous-time models. Specifically, if the signal is absent prior to an output time, then it should be absent at index 0 of the time at which it will produce the next output. There are two exceptions. If two or more offsets have the same value, then each output at the same time is produced at superdense time index one greater than the previous output. Also, if an expected output has not been produced by the expected index, then it will be produced at the next available index. E.g., the very first output may be produced at a superdense index greater than zero if the director's index is greater than zero when this actor is initialized. This can happen, for example, if this clock is in a refinement in a modal model, and the modal model enters that mode with a reset transition.

    If the period is changed at any time, either by provided by an input or by changing the parameter, then the new period will take effect immediately if the new period is provided at the same time (including the microstep) that the current cycle starts, or after the current cycle completes otherwise.

    If the trigger input is connected, then an output will only be produced if a trigger input has been received since the last output or if the trigger input coincides with the time when an output should be produced. If a trigger input has not been received, then the output will be skipped, moving on to the the next phase. The only exception is the first output, which is produced whether a trigger is provided or not. This is because the trigger input is typically useful in a feedback situation, where the output of the clock eventually results in a trigger input. If the time-stamp of that trigger input is less than the time between clock events, then the clock will behave as if there were no trigger input. Otherwise, it will "skip beats."

    This actor is a timed source; the untimed version is Pulse.

    Since:
    Ptolemy II 8.0
    Version:
    $Id$
    Author:
    Edward A. Lee
    Pt.AcceptedRating:
    Red (hyzheng)
    Pt.ProposedRating:
    Yellow (eal)

    • Field Detail

      • offsets

        public Parameter offsets
        The offsets at which the specified values will be produced. This parameter must contain an array of doubles, and it defaults to {0.0}.

      • period

        public PortParameter period
        The period of the output waveform. This is a double that defaults to 1.0.

      • start

        public TypedIOPort start
        A port that, if connected, is used to specify when the clock starts. This port accepts any type. The arrival of an event is what starts the clock. Upon arrival of such an event, the clock starts as if just initialized. The clock will not start until such an event is provided, unless the port is left unconnected, in which case the actor starts immediately. Note that when the clock starts, the period will be set to its initial value. If an input period arrives before a start input, then that arrived value will be ignored.

      • stop

        public TypedIOPort stop
        A port that, if connected, is used to specify when the clock stops. This port accepts any type. The arrival of an event is what stops the clock.

      • values

        public Parameter values
        The values that will be produced at the specified offsets. This parameter must contain an ArrayToken, and it defaults to {1}

      • _cycleCount

        protected transient int _cycleCount
        The count of cycles executed so far, or 0 before the start.

      • _cycleStartTime

        protected transient Time _cycleStartTime
        The most recent cycle start time.

      • _enabled

        protected transient boolean _enabled
        Indicator of whether the specified number of cycles have been completed. Also used in derived classes to turn on and off the clock.

      • _firstOutputProduced

        protected transient boolean _firstOutputProduced
        Indicator of whether the first output has been produced.

      • _nextOutputTime

        protected transient Time _nextOutputTime
        The time for the next output.

      • _nextOutputIndex

        protected transient int _nextOutputIndex
        The index of when the output should be emitted.

      • _offsets

        protected transient double[] _offsets
        Cache of offsets array value.

      • _phase

        protected transient int _phase
        The phase of the next output.

    • Constructor Detail

      • DiscreteClock

        public DiscreteClock​(CompositeEntity container,
                     java.lang.String name)
              throws IllegalActionException,
                     NameDuplicationException
        Construct an actor in the specified container with the specified name. The name must be unique within the container or an exception is thrown. The container argument must not be null, or a NullPointerException will be thrown.
        Parameters:
        container - The container.
        name - The actor's name
        Throws:
        IllegalActionException - If the entity cannot be contained by the proposed container.
        NameDuplicationException - If name coincides with an entity already in the container.

    • Method Detail

      • attributeChanged

        public void attributeChanged​(Attribute attribute)
                      throws IllegalActionException
        If the argument is the offsets parameter, check that the array is nondecreasing and has the right dimension; if the argument is period, check that it is positive. Other sanity checks with period and values are done in the fire() method.
        Overrides:
        attributeChanged in class TimedSource
        Parameters:
        attribute - The attribute that changed.
        Throws:
        IllegalActionException - If the offsets array is not nondecreasing and nonnegative.

      • fire

        public void fire()
          throws IllegalActionException
        Output the current value of the clock if the clock is currently enabled and, if the trigger input is connected, a trigger has been received. This method is expected to be called only at the right time to produce the next output, since otherwise prefire() will return false.
        Specified by:
        fire in interface Executable
        Overrides:
        fire in class Source
        Throws:
        IllegalActionException - If the value in the offsets parameter is encountered that is greater than the period, or if there is no director.

      • initialize

        public void initialize()
                throws IllegalActionException
        Override the base class to initialize the index.
        Specified by:
        initialize in interface Initializable
        Overrides:
        initialize in class TimedSource
        Throws:
        IllegalActionException - If the parent class throws it, or if the values parameter is not a row vector, or if the fireAt() method of the director throws it, or if the director does not agree to fire the actor at the specified time.

      • postfire

        public boolean postfire()
                 throws IllegalActionException
        Update the time and index of the next expected output.
        Specified by:
        postfire in interface Executable
        Overrides:
        postfire in class TimedSource
        Returns:
        False if the specified number of cycles has been reached, and true otherwise.
        Throws:
        IllegalActionException - If the director throws it when scheduling the next firing, or if an offset value exceeds the period.

      • prefire

        public boolean prefire()
                throws IllegalActionException
        Return true if current time has not exceeded the stopTime. Check that the length of the values and offsets parameters are the same and return true if it is time to produce an output.
        Specified by:
        prefire in interface Executable
        Overrides:
        prefire in class TimedSource
        Returns:
        True if current time is less than or equal to the stop time.
        Throws:
        IllegalActionException - If the values and offsets parameters do not have the same length.

      • _getValue

        protected Token _getValue​(int index)
                   throws IllegalActionException
        Get the specified output value, checking the form of the values parameter.
        Parameters:
        index - The index of the output values.
        Returns:
        A token that contains the output value.
        Throws:
        IllegalActionException - If the index is out of the range of the values parameter.

      • _produceIntermediateOutput

        protected void _produceIntermediateOutput()
                                   throws IllegalActionException
        Produce the output required at times between the specified times. This base class makes the output absent, but subclasses may interpolate the values.
        Throws:
        IllegalActionException - If sending the output fails.

      • _skipToNextPhase

        protected void _skipToNextPhase()
                         throws IllegalActionException
        Skip the current firing phase and request a refiring at the time of the next one.
        Throws:
        IllegalActionException - If the period cannot be evaluated, or if an offset is encountered that is greater than the period.