ptolemy.actor.lib
Class TimeDelay

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.Transformer
                              ptolemy.actor.lib.TimeDelay

All Implemented Interfaces:

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

public class TimeDelay
extends Transformer

This actor delays the input by a specified amount of time. It is designed to be used in timed domains such as DE. It can also be used in other domains, such as SR and SDF, but this will only be useful if the delay value is a multiple of the period of those directors. The amount of the time is required to be non-negative and has a default value 1.0. The input and output types are unconstrained, except that the output type must be the same as that of the input. It can be used in the Continuous domain, but it is really only useful to delay purely discrete signals. Because of the way variable-step-size ODE solvers work, the TimeDelay actor has the side effect of forcing the solver to use very small step sizes, which slows down a simulation.

This actor keeps a local FIFO queue to store all received but not processed inputs. The behavior of this actor on each firing is to read a token from the input, if there is one, store it into the local queue. It will also output any previously received token that is scheduled to be produced at the current time. If there is no previously received token scheduled to be produced, then the output will (implicitly) be absent.

If an input is read during the fire() method, then during the postfire() method, this actor schedules itself to fire again to produce the just received token on the corresponding output channel after the appropriate time delay. Note that if the value of delay is 0.0, the actor schedules itself to fire at the current model time.

This actor can be used to delay either discrete signals or continuous-time signals. However, in the latter case, some odd artifacts will inevitably appear if a variable step-size solver is being used. In particular, the output will be absent on any firing where there was no input at exactly time t - d, where t is the time of the firing and d is the value of the delay parameter.

Occasionally, this actor is useful with the delay parameter set to 0.0. The time stamp of the output will equal that of the input, but there is a "microstep" delay. Several Ptolemy II domains use a "super dense" model of time, meaning that a signal from one actor to another can contain multiple events with the same time stamp. These events are "simultaneous," but nonetheless have a well-defined sequential ordering determined by the order in which they are produced. If \textit{delay} is 0.0, then the fire() method of this actor always produces on its output port the event consumed in the \textit{previous iteration} with the same time stamp, if there was one. If there wasn't such a previous iteration, then it produces no output. Its postfire() method consumes and records the input for use in the next iteration, if there is such an input, and also requests a refiring at the current time. This refire request triggers the next iteration (at the same time stamp), on which the output is produced.

A consequence of this strategy is that this actor is able to produce an output (or assert that there is no output) before the input with the same time is known. Hence, it can be used to break causality loops in feedback systems. The Continuous director will leverage this when determining the fixed point behavior. It is sometimes useful to think of this zero-valued delay as an infinitesimal delay.

Since:

Ptolemy II 8.0

Version:

$Id: TimeDelay.java 57046 2010-01-27 23:35:53Z cxh $

Author:

Edward A. Lee

See Also:

Serialized Form

Accepted Rating:

Red (eal)

Proposed Rating:

Yellow (eal)

Nested Class Summary

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

Entity.ContainedObjectsIterator

Field Summary

protected CausalityMarker	_causalityMarker A causality marker to store information about how pure events are causally related to trigger events.
protected Token	_currentOutput Current output.
protected double	_delay The amount of delay.
protected CalendarQueue	_delayedOutputTokens A local event queue to store the delayed output tokens.
Parameter	delay The amount of delay.

Fields inherited from class ptolemy.actor.lib.Transformer

input, output

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

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

Method Summary

void	attributeChanged(Attribute attribute) If the attribute is delay, then ensure that the value is non-negative.
java.lang.Object	clone(Workspace workspace) Clone the actor into the specified workspace.
void	fire() Read one token from the input.
void	initialize() Initialize the states of this actor.
boolean	isStrict() Return false indicating that this actor can be fired even if the inputs are unknown.
boolean	postfire() Process the current input if it has not been processed.
void	preinitialize() Override the base class to declare that the output does not depend on the input in a firing.

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, iterate, newReceiver, outputPortList, prefire, pruneDependencies, recordFiring, removeActorFiringListener, removeDependency, removeInitializable, setContainer, stop, stopFire, terminate, wrapup

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, iterate, prefire, stop, stopFire, terminate

Methods inherited from interface ptolemy.actor.Initializable

addInitializable, removeInitializable, wrapup

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

delay

public Parameter delay

The amount of delay. The default for this parameter is 1.0. This parameter must contain a DoubleToken with a non-negative value, or an exception will be thrown when it is set.

_currentOutput

protected Token _currentOutput

Current output.

_delay

protected double _delay

The amount of delay.

_delayedOutputTokens

protected CalendarQueue _delayedOutputTokens

A local event queue to store the delayed output tokens.

_causalityMarker

protected CausalityMarker _causalityMarker

A causality marker to store information about how pure events are causally related to trigger events.

Constructor Detail

TimeDelay

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

Construct an actor with the specified container and name. Constrain that the output type to be the same as the input type.

Parameters:

container - The composite entity to contain this one.

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 attribute is delay, then ensure that the value is non-negative.

NOTE: the newDelay may be 0.0, which may change the causality property of the model. We leave the model designers to decide whether the zero delay is really what they want.

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If the delay is negative.

clone

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

Clone the actor into the specified workspace. Set a type constraint that the output type is the same as the that of input.

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 has has an attribute that cannot be cloned.

See Also:

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

fire

public void fire()
          throws IllegalActionException

Read one token from the input. Send out a token that is scheduled to produce at the current time to the output.

Specified by:

fire in interface Executable

Overrides:

fire in class AtomicActor

Throws:

IllegalActionException - If there is no director, or the input can not be read, or the output can not be sent.

initialize

public void initialize()
                throws IllegalActionException

Initialize the states of this actor.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class AtomicActor

Throws:

IllegalActionException - If a derived class throws it.

isStrict

public boolean isStrict()

Return false indicating that this actor can be fired even if the inputs are unknown.

Specified by:

isStrict in interface Executable

Overrides:

isStrict in class AtomicActor

Returns:

False.

postfire

public boolean postfire()
                 throws IllegalActionException

Process the current input if it has not been processed. Schedule a firing to produce the earliest output token.

Specified by:

postfire in interface Executable

Overrides:

postfire in class AtomicActor

Returns:

True if execution can continue into the next iteration.

Throws:

IllegalActionException - If scheduling to refire cannot be performed or the superclass throws it.

preinitialize

public void preinitialize()
                   throws IllegalActionException

Override the base class to declare that the output does not depend on the input in a firing.

Specified by:

preinitialize in interface Initializable

Overrides:

preinitialize in class AtomicActor

Throws:

IllegalActionException - If the superclass throws it.