ptolemy.actor.lib
Class DiscreteClock

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.InstantiableNamedObj
          ptolemy.kernel.Entity
              ptolemy.kernel.ComponentEntity
                  ptolemy.actor.AtomicActor
                      ptolemy.actor.TypedAtomicActor
                          ptolemy.actor.lib.Source
                              ptolemy.actor.lib.TimedSource
                                  ptolemy.actor.lib.DiscreteClock

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Actor, Executable, FiringsRecordable, Initializable, TimedActor, TypedActor, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

Direct Known Subclasses:

DiscreteClock

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.

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

This actor can generate finite sequences by specifying a finite stopTime. Upon reaching that stop time, postfire() returns false, and the actor does not expect to be invoked again.

Alternatively, a token at the start input will start the clock. 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.

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 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: DiscreteClock.java 59167 2010-09-21 17:08:02Z cxh $

Author:

Edward A. Lee

See Also:

Serialized Form

Accepted Rating:

Red (hyzheng)

Proposed Rating:

Yellow (eal)

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.kernel.Entity

Entity.ContainedObjectsIterator

Field Summary

protected int	_cycleCount The count of cycles executed so far, or 0 before the start.
protected Time	_cycleStartTime The most recent cycle start time.
protected boolean	_enabled Indicator of whether the specified number of cycles have been completed.
protected boolean	_firstOutputProduced Indicator of whether the first output has been produced.
protected int	_nextOutputIndex The index of when the output should be emitted.
protected Time	_nextOutputTime The time for the next output.
protected double[]	_offsets Cache of offsets array value.
private boolean	_outputProduced Indicator that an output was produced and hence we should skip to the next phase in postfire.
protected int	_phase The phase of the next output.
private boolean	_triggered Indicator of whether trigger inputs have arrived since the last output.
Parameter	offsets The offsets at which the specified values will be produced.
PortParameter	period The period of the output waveform.
TypedIOPort	start A port that, if connected, is used to specify when the clock starts.
TypedIOPort	stop A port that, if connected, is used to specify when the clock stops.
Parameter	values The values that will be produced at the specified offsets.

Fields inherited from class ptolemy.actor.lib.TimedSource

stopTime, stopTimeIsLocal

Fields inherited from class ptolemy.actor.lib.Source

output, trigger

Fields inherited from class ptolemy.actor.AtomicActor

_actorFiringListeners, _initializables, _notifyingActorFiring, _stopRequested

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

DiscreteClock(CompositeEntity container, java.lang.String name)
Construct an actor in the specified container with the specified name.

Method Summary

protected Token	_getValue(int index) Get the specified output value, checking the form of the values parameter.
private void	_skipToNextPhase() Skip the current firing phase and request a refiring at the time of the next one.
void	attributeChanged(Attribute attribute) 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.
java.lang.Object	clone(Workspace workspace) Clone the actor into the specified workspace.
void	fire() 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.
void	initialize() Override the base class to initialize the index.
boolean	postfire() Update the time and index of the next expected output.
boolean	prefire() Return true if current time has not exceeded the stopTime.

Methods inherited from class ptolemy.actor.lib.TimedSource

getModelStopTime, getStopTime, wrapup

Methods inherited from class ptolemy.actor.TypedAtomicActor

_addPort, _fireAt, _fireAt, attributeTypeChanged, clone, newPort, typeConstraintList, typeConstraints

Methods inherited from class ptolemy.actor.AtomicActor

_actorFiring, _actorFiring, addActorFiringListener, addInitializable, connectionsChanged, createReceivers, declareDelayDependency, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, isFireFunctional, isStrict, iterate, newReceiver, outputPortList, preinitialize, pruneDependencies, recordFiring, removeActorFiringListener, removeDependency, removeInitializable, setContainer, stop, stopFire, terminate

Methods inherited from class ptolemy.kernel.ComponentEntity

_adjustDeferrals, _checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, isAtomic, isOpaque, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, propagateExistence, setName

Methods inherited from class ptolemy.kernel.Entity

_description, _exportMoMLContents, _removePort, _validateSettables, connectedPortList, connectedPorts, containedObjectsIterator, getAttribute, getPort, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts, setClassDefinition, uniqueName

Methods inherited from class ptolemy.kernel.InstantiableNamedObj

_setParent, exportMoML, getChildren, getElementName, getParent, getPrototypeList, isClassDefinition, isWithinClassDefinition

Methods inherited from class ptolemy.kernel.util.NamedObj

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

Methods inherited from class java.lang.Object

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

Methods inherited from interface ptolemy.actor.Actor

createReceivers, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, newReceiver, outputPortList

Methods inherited from interface ptolemy.actor.Executable

isFireFunctional, isStrict, iterate, stop, stopFire, terminate

Methods inherited from interface ptolemy.actor.Initializable

addInitializable, preinitialize, removeInitializable

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getContainer, getDisplayName, getFullName, getName, getName, setName

Methods inherited from interface ptolemy.kernel.util.Derivable

getDerivedLevel, getDerivedList, propagateValue

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.

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.

_outputProduced

private boolean _outputProduced

Indicator that an output was produced and hence we should skip to the next phase in postfire.

_triggered

private transient boolean _triggered

Indicator of whether trigger inputs have arrived since the last 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.

clone

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

Clone the actor into the specified workspace.

Overrides:

clone in class AtomicActor

Parameters:

workspace - The workspace for the new object.

Returns:

A new actor.

Throws:

java.lang.CloneNotSupportedException - If a derived class contains an attribute that cannot be cloned.

See Also:

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

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.

_skipToNextPhase

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