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 <i>period</i>,
starting from the time at which initialize() is invoked,
this actor initiates a sequence of output events with values given by
<i>values</i> and offset into the period given by <i>offsets</i>.
These parameters contain arrays, which are required to have the same length.
The <i>offsets</i> 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 <i>period</i>
then the corresponding output will never be produced.
To get a finite sequence of events that is not periodic,
just set <i>period</i> to Infinity.
Alternatively, you can provide
a finite <i>stopTime</i>. 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 <i>start</i> input will start the clock
at the beginning of a period. A token
at the <i>stop</i> input will stop the clock, if it is still running.
If both <i>start</i> and <i>stop</i> are received simultaneously, then
the clock will be stopped.
<p>
The <i>values</i> parameter by default
contains the array {1}. The default
<i>offsets</i> array is {0.0}.
The default period is 1.0.
<p>
The type of the output can be any token type. This type is inferred
from the element type of the <i>values</i> parameter.
<p>
For example, if <i>values</i> = {1, 2, 3},
<i>offsets</i> = {0.1, 0.2, 0.3},
<i>period</i> = 1.0,
and the actor is initialized at time 0.0, then
it will produce outputs with value 1 at all times
<i>n</i> + 0.1, outputs with value 2 at all times
<i>n</i> + 0.2, and outputs with value 3 at all times
<i>n</i> + 0.3, for all non-negative integers <i>n</i>.
<p>
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.
<p>
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.
<p>
If the <i>period</i> 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.
<p>
If the <i>trigger</i> 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."
<p>
This actor is a timed source; the untimed version is Pulse.
Edward A. Lee
$Id: DiscreteClock.java 70402 2014-10-23 00:52:20Z cxh $
Ptolemy II 8.0
Yellow (eal)
Red (hyzheng)
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.
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.
The offsets at which the specified values will be produced.
This parameter must contain an array of doubles, and it defaults
to {0.0}.
The period of the output waveform.
This is a double that defaults to 1.0.
The values that will be produced at the specified offsets.
This parameter must contain an ArrayToken, and it defaults to
{1}