ptolemy.domains.ct.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.domains.ct.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:

ContinuousClock

public class DiscreteClock
extends TimedSource

NOTE: This actor used to be ptolemy.actor.lib.Clock. But a major rework of actor.lib.Clock made it difficult to maintain backward compatibility, so the old Clock was moved here to serve as a base class for ContinuousClock.

This actor produces a periodic signal, a sequence of events at regularly spaced intervals. It can generate finite pulses by specifying a finite numberOfCycles. The numberOfCycles has a default value as -1, indicating infinite length of executions. If numberOfCycles is a positive number, once the specified number of cycles has been completed, then this actor returns false from the postfire method.

At the beginning of each time interval of length given by period, 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. Moreover, its largest entry must be smaller than period or an exception will be thrown by the fire() method.

The values parameter by default contains an array of IntTokens with values 1 and 0. The default offsets array is {0.0, 1.0}. Thus, the default output will be alternating 1 and 0 with 50% duty cycle. The default period is 2.0.

The actor uses the fireAt() method of the director to request firing at the beginning of each period plus each of the offsets.

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

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

There is another kind of clock called ContinuousClock, which produces a square wave instead of a sequence of events. The ContinuousClock is a special actor for continuous-time domain. One of their key differences is that a DiscreteClock outputs a DISCRETE signal while a ContinuousClock outputs a CONTINUOUS signal.

Since:

Ptolemy II 6.1

Version:

$Id: DiscreteClock.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Edward A. Lee, Haiyang Zheng

See Also:

ContinuousClock, Serialized Form

Accepted Rating:

Yellow (yuhong)

Proposed Rating:

Yellow (eal)

Nested Class Summary

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

Entity.ContainedObjectsIterator

Field Summary

protected Token	_currentValue The current value of the clock output.
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	_done Indicator of whether the specified number of cycles have been completed.
protected double[]	_offsets Cache of offsets array value.
protected int	_phase The phase of the next output.
protected Time	_startTime The time at which output starts.
protected Token	_tentativeCurrentValue The tentative current value of the clock output.
protected int	_tentativeCycleCount The tentative count of cycles executed so far.
protected int	_tentativeCycleCountIncrement The tentative increment for cycle count increment.
protected Time	_tentativeCycleStartTime The tentative start time of the most recent cycle.
protected boolean	_tentativeDone The indicator of whether the specified number of cycles have been completed.
protected Time	_tentativeNextFiringTime The tentative time for next firing.
protected int	_tentativePhase The tentative phase of the next output.
protected Time	_tentativeStartTime The tentative start time for the clock to produce output.
Parameter	numberOfCycles The number of cycles to produce, or -1 to specify no limit.
Parameter	offsets The offsets at which the specified values will be produced.
Parameter	period The period of the output waveform.
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 with the specified container and name.

Method Summary

protected Token	_getValue(int index) Get the specified output value, checking the form of the values parameter.
protected void	_initializeCycleCount() Initialize the cycle count and done flag.
protected void	_updateStates() Update the states and request refiring if necessary.
protected void	_updateTentativeValues() Copy values committed in initialize() or in the last postfire() into the corresponding tentative variables.
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.
void	initialize() Schedule the first firing and initialize local variables.
boolean	postfire() Update the state of the actor and schedule the next firing, if appropriate.
boolean	prefire() Check that the length of the values and offsets parameters are the same.

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

numberOfCycles

public Parameter numberOfCycles

The number of cycles to produce, or -1 to specify no limit. This is an integer with default -1.

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, 1.0}.

period

public Parameter period

The period of the output waveform. This parameter must contain a DoubleToken, and it defaults to 2.0.

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, 0}

_currentValue

protected transient Token _currentValue

The current value of the clock output.

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

_done

protected transient boolean _done

Indicator of whether the specified number of cycles have been completed.

_offsets

protected transient double[] _offsets

Cache of offsets array value.

_phase

protected transient int _phase

The phase of the next output.

_startTime

protected transient Time _startTime

The time at which output starts.

_tentativeCurrentValue

protected transient Token _tentativeCurrentValue

The tentative current value of the clock output.

_tentativeCycleCount

protected transient int _tentativeCycleCount

The tentative count of cycles executed so far.

_tentativeCycleCountIncrement

protected transient int _tentativeCycleCountIncrement

The tentative increment for cycle count increment.

_tentativeCycleStartTime

protected transient Time _tentativeCycleStartTime

The tentative start time of the most recent cycle.

_tentativeDone

protected transient boolean _tentativeDone

The indicator of whether the specified number of cycles have been completed.

_tentativeNextFiringTime

protected transient Time _tentativeNextFiringTime

The tentative time for next firing.

_tentativePhase

protected transient int _tentativePhase

The tentative phase of the next output.

_tentativeStartTime

protected transient Time _tentativeStartTime

The tentative start time for the clock to produce output.

Constructor Detail

DiscreteClock

public DiscreteClock(CompositeEntity container,
                     java.lang.String name)
              throws NameDuplicationException,
                     IllegalActionException

Construct an actor with the specified container and name.

Parameters:

container - The container.

name - The name of this actor.

Throws:

IllegalActionException - If the entity cannot be contained by the proposed container.

NameDuplicationException - If the container already has an actor with this name.

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. This calls the base class and then sets the parameter public members to refer to the parameters of the new actor.

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.

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

Schedule the first firing and initialize local variables.

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.

postfire

public boolean postfire()
                 throws IllegalActionException

Update the state of the actor and schedule the next firing, if appropriate.

Specified by:

postfire in interface Executable

Overrides:

postfire in class TimedSource

Returns:

True if execution can continue into the next iteration.

Throws:

IllegalActionException - If the director throws it when scheduling the next firing.

prefire

public boolean prefire()
                throws IllegalActionException

Check that the length of the values and offsets parameters are the same.

Specified by:

prefire in interface Executable

Overrides:

prefire in class TimedSource

Returns:

True, unless the trigger input is connected and has no input.

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.

_initializeCycleCount

protected void _initializeCycleCount()

Initialize the cycle count and done flag. These are done in a protected method so that derived classes can do something different here.

_updateTentativeValues

protected void _updateTentativeValues()
                               throws IllegalActionException

Copy values committed in initialize() or in the last postfire() into the corresponding tentative variables. In effect, this loads the last known good value for these variables, which is particularly important if time has gone backwards. This is done in a protected method because derived classes may want to override it.

Throws:

IllegalActionException - Not thrown in this base class.

_updateStates

protected void _updateStates()
                      throws IllegalActionException

Update the states and request refiring if necessary.

Throws:

IllegalActionException - If the numberOfCycles parameter does not contain a valid parameter or can not request refiring.