ptolemy.actor.lib
Class PoissonClock

java.lang.Object
  extended byptolemy.kernel.util.NamedObj
      extended byptolemy.kernel.InstantiableNamedObj
          extended byptolemy.kernel.Entity
              extended byptolemy.kernel.ComponentEntity
                  extended byptolemy.actor.AtomicActor
                      extended byptolemy.actor.TypedAtomicActor
                          extended byptolemy.actor.lib.Source
                              extended byptolemy.actor.lib.TimedSource
                                  extended byptolemy.actor.lib.PoissonClock
All Implemented Interfaces:
Actor, Changeable, java.lang.Cloneable, Debuggable, DebugListener, Derivable, Executable, Instantiable, ModelErrorHandler, MoMLExportable, Nameable, java.io.Serializable, TimedActor, TypedActor

public class PoissonClock
extends TimedSource

This actor produces a signal that is piecewise constant, with transitions between levels taken at times given by a Poisson process. It has various uses. Its simplest use in the DE domain is to generate a sequence of events at intervals that are spaced randomly, according to an exponential distribution. In CT, it can be used to generate a piecewise constant waveform with randomly spaced transition times. In both domains, the output value can cycle through a set of values.

The mean time between events is given by the meanTime parameter. An event is defined to be the transition to a new output value. The default mean time is 1.0.

The values parameter must contain an ArrayToken, or an exception will be thrown when it is set. By default the elements of the array are IntTokens with values 1 and 0, Thus, the default output value is always 1 or 0.

In the initialize() method and in each invocation of the fire() method, the actor uses the fireAt() method of the director to request the next firing. The first firing is always at the start time, unless the parameter fireAtStart is changed to false. It may in addition fire at any time in response to a trigger input. On such firings, it simply repeats the most recent output (or generate a new output if the time is suitable.) Thus, the trigger, in effect, asks the actor what its current output value is. Some directors, such as those in CT, may also fire the actor at other times, without requiring a trigger input. Again, the actor simply repeats the previous output. Thus, the output can be viewed as samples of the piecewise constant waveform, where the time of each sample is the time of the firing that produced it.

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

Since:
Ptolemy II 1.0
Version:
$Id: PoissonClock.java,v 1.17.2.1 2004/07/31 02:15:06 cxh Exp $
Author:
Edward A. Lee
See Also:
Serialized Form
Accepted Rating:
Yellow (yuhong)
Proposed Rating:
Yellow (eal)

Nested Class Summary
 
Nested classes inherited from class ptolemy.kernel.Entity
Entity.ContainedObjectsIterator
 
Field Summary
 Parameter fireAtStart
          If true, then this actor will request a firing at the start time.
 Parameter meanTime
          The mean time between events, where the output value transitions.
 Parameter values
          The values that will be produced at the output.
 
Fields inherited from class ptolemy.actor.lib.TimedSource
stopTime
 
Fields inherited from class ptolemy.actor.lib.Source
output, trigger
 
Fields inherited from class ptolemy.actor.AtomicActor
_stopRequested
 
Fields inherited from class ptolemy.kernel.util.NamedObj
_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS
 
Fields inherited from interface ptolemy.actor.Executable
COMPLETED, NOT_READY, STOP_ITERATING
 
Constructor Summary
PoissonClock(CompositeEntity container, java.lang.String name)
          Construct an actor with the specified container and name.
 
Method Summary
 void attributeChanged(Attribute attribute)
          If the argument is the meanTime parameter, check that it is positive.
 java.lang.Object clone(Workspace workspace)
          Clone the actor into the specified workspace.
 void fire()
          Output the current value.
 void initialize()
          Schedule the first firing at time zero and initialize local variables.
 boolean postfire()
          Update the state of the actor and schedule the next firing, if appropriate.
 
Methods inherited from class ptolemy.actor.lib.TimedSource
wrapup
 
Methods inherited from class ptolemy.actor.TypedAtomicActor
_addPort, attributeTypeChanged, clone, newPort, typeConstraintList
 
Methods inherited from class ptolemy.actor.AtomicActor
_createReceivers, connectionsChanged, getDirector, getExecutiveDirector, getFunctionDependency, getManager, inputPortList, iterate, newReceiver, outputPortList, prefire, preinitialize, pruneDependencies, removeDependency, setContainer, stop, stopFire, terminate
 
Methods inherited from class ptolemy.kernel.ComponentEntity
_adjustDeferrals, _checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, isAtomic, isOpaque, propagateExistence, setName
 
Methods inherited from class ptolemy.kernel.Entity
_description, _exportMoMLContents, _removePort, connectedPortList, connectedPorts, containedObjectsIterator, getAttribute, getPort, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts, setClassDefinition, uniqueName, validateSettables
 
Methods inherited from class ptolemy.kernel.InstantiableNamedObj
_setParent, exportMoML, getChildren, getElementName, getParent, getPrototypeList, isClassDefinition
 
Methods inherited from class ptolemy.kernel.util.NamedObj
_addAttribute, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeList, attributeList, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, getAttribute, getAttributes, getChangeListeners, getClassName, getDerivedLevel, getDerivedList, getFullName, getModelErrorHandler, getName, getName, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, message, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setModelErrorHandler, setPersistent, setSource, toplevel, toString, workspace
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface ptolemy.actor.Actor
getDirector, getExecutiveDirector, getFunctionDependency, getManager, inputPortList, newReceiver, outputPortList
 
Methods inherited from interface ptolemy.actor.Executable
iterate, prefire, preinitialize, stop, stopFire, terminate
 
Methods inherited from interface ptolemy.kernel.util.Derivable
getDerivedLevel, getDerivedList, propagateValue
 
Methods inherited from interface ptolemy.kernel.util.Nameable
description, getFullName, getName, getName
 

Field Detail

fireAtStart

public Parameter fireAtStart
If true, then this actor will request a firing at the start time. Otherwise, the first firing will be requested at the first random time. This is a boolean-valued parameter that defaults to true.


meanTime

public Parameter meanTime
The mean time between events, where the output value transitions. This parameter must contain a DoubleToken.


values

public Parameter values
The values that will be produced at the output. This parameter can contain any ArrayToken, and it defaults to {1, 0}.

Constructor Detail

PoissonClock

public PoissonClock(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 meanTime parameter, check that it is positive.

Overrides:
attributeChanged in class TimedSource
Throws:
IllegalActionException - If the meanTime value is not positive.

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.

fire

public void fire()
          throws IllegalActionException
Output the current value.

Specified by:
fire in interface Executable
Overrides:
fire in class Source
Throws:
IllegalActionException - If there is no director.

initialize

public void initialize()
                throws IllegalActionException
Schedule the first firing at time zero and initialize local variables.

Specified by:
initialize in interface Executable
Overrides:
initialize in class TimedSource
Throws:
IllegalActionException - 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
Throws:
IllegalActionException - If the director throws it when scheduling the next firing.