ptolemy.domains.continuous.lib
Class ContinuousTimeDelay

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.domains.continuous.lib.ContinuousTimeDelay

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 ContinuousTimeDelay
extends Transformer

Delay the input by a specified amount of time.

This actor is designed to be used in timed domains such as DE and Continuous. 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 delay 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.

This actor keeps a local FIFO queue of all input events that may be requested by the director; an event expires and is removed from this queue if its timestamp is older than the current time less the delay. The behavior of this actor on each firing is to read a token from the input port (if present) and generates an output that is either equal to or an approximation of the delayed input signal. Output is absent if and only if no initial value is given and the actor is fired before input is received, or before the transient delay period has passed (i.e. model time is less than delay time).

Output is generated by the fire() method, and inputs are processed in postFire().

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. The continuous domain in Ptolemy II has 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 actor does not generate output in the current time microstep, but rather on a refiring at the the same physical time but incremented timestep.

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: ContinuousTimeDelay.java 59203 2010-09-23 21:41:27Z cxh $

Author:

Edward A. Lee, Jeff C. Jensen

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 TimedEvent	_discarded Holds the most recently discarded event from the input buffer.
protected CalendarQueue	_inputBuffer A local event queue to store input tokens, sorted by input time.
protected Time	_nextFireAt Records the next scheduled fireAt() call, so that we do not request more than one fireAt() call for a given input event.
Parameter	delay The amount of delay.
Parameter	initialOutput Initial output of the delay actor.

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

ContinuousTimeDelay(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() Do nothing.
void	initialize() Initialize the states of this actor.
boolean	isStrict() Override the base class to declare that the actor is nonstrict if it has an initial value token.
protected Token	linearInterpolate(TimedEvent leftEvent, TimedEvent rightEvent) Linear interpolate between previous and current input.
boolean	postfire() Schedule the next output event.
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.

initialOutput

public Parameter initialOutput

Initial output of the delay actor. The default for this parameter is null, indicating no output will be generated until after input has been received.

_currentOutput

protected Token _currentOutput

Current output.

_delay

protected double _delay

The amount of delay.

_inputBuffer

protected CalendarQueue _inputBuffer

A local event queue to store input tokens, sorted by input time.

_discarded

protected TimedEvent _discarded

Holds the most recently discarded event from the input buffer.

_nextFireAt

protected Time _nextFireAt

Records the next scheduled fireAt() call, so that we do not request more than one fireAt() call for a given input event.

_causalityMarker

protected CausalityMarker _causalityMarker

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

Constructor Detail

ContinuousTimeDelay

public ContinuousTimeDelay(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)

initialize

public void initialize()
                throws IllegalActionException

Initialize the states of this actor. Place initial output token on the input buffer.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class AtomicActor

Throws:

IllegalActionException - If a derived class throws it.

fire

public void fire()
          throws IllegalActionException

Description copied from class: AtomicActor

Do nothing. Derived classes override this method to define their primary run-time action.

Specified by:

fire in interface Executable

Overrides:

fire in class AtomicActor

Throws:

IllegalActionException - Not thrown in this base class.

postfire

public boolean postfire()
                 throws IllegalActionException

Schedule the next output event.

Specified by:

postfire in interface Executable

Overrides:

postfire in class AtomicActor

Returns:

True if execution can continue into the next iteration.

Throws:

IllegalActionException

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.

isStrict

public boolean isStrict()

Override the base class to declare that the actor is nonstrict if it has an initial value token.

Specified by:

isStrict in interface Executable

Overrides:

isStrict in class AtomicActor

Returns:

True always in this base class.

Throws:

IllegalActionException - If the superclass throws it.

linearInterpolate

protected Token linearInterpolate(TimedEvent leftEvent,
                                  TimedEvent rightEvent)
                           throws IllegalActionException

Linear interpolate between previous and current input.

To interpolate, we determine the slope between the left and right interpolation points, and multiply this by time gap between the left point and the current time. This estimates the amount by which the input signal has changed between the left and center points. We add this change to the value of the left point to estimate the value of the center point.

Parameters:

leftEvent - The left event.

rightEvent - the right event.

Returns:

The linear interpolation.

Throws:

IllegalActionException - If thrown by arithmetic operations on the events