ptolemy.actor.lib
Class RandomSource

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

All Implemented Interfaces:

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

Direct Known Subclasses:

Bernoulli, ColtRandomSource, DiscreteRandomSource, Gaussian, PoissonClock, Rician, Triangular, Uniform

public abstract class RandomSource
extends Source

A base class for sources of random numbers. It uses the class java.util.Random. This base class manages the seed. Specifically, the seed is a shared parameter, so setting the seed in any one instance of a RandomSource results in setting the seed in all instances. If the seed is set to value 0L, the default, then this is interpreted as not specifying a seed, and the random number generators are set to use a seed that depends on the current time in milliseconds. If the seed is set to any value other than 0L, then a seed is computed for the random number generator by adding that specified seed to the hashcode for the full name of the actor. This ensures that with high probability, multiple instances of RandomSource (and derived classes) will have distinct seeds, but that the executions are deterministically repeatable.

If the resetOnEachRun parameter is true (it is false by default), then each run resets the random number generator. If the seed is non-zero, then this makes each run identical. This is useful for constructing tests. If the seed is zero, then a new seed is generated on each run using the same technique described above (combining current time and the hash code).

Since:

Ptolemy II 0.3

Version:

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

Author:

Edward A. Lee, Steve Neuendorffer, Elaine Cheong

See Also:

Serialized Form

Accepted Rating:

Green (bilung)

Proposed Rating:

Green (eal)

Nested Class Summary

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

Entity.ContainedObjectsIterator

Field Summary

protected long	_generatorSeed The current value of the seed parameter.
protected boolean	_needNew Indicator that a new random number is needed.
protected boolean	_needNewGenerator Indicator that a new generator is needed.
protected java.util.Random	_random The Random object.
SharedParameter	resetOnEachRun If true, this parameter specifies that the random number generator should be reset on each run of the model (in the initialize() method).
SharedParameter	seed The seed that controls the random number generation.

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

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

Method Summary

protected void	_createGenerator() Create the random number generator using current parameter values.
protected abstract void	_generateRandomNumber() Generate a new random number.
void	attributeChanged(Attribute attribute) If the attribute is seed then create the base random number generator.
java.lang.Object	clone(Workspace workspace) Clone the actor into the specified workspace.
void	fire() Generate a new random number if this is the first firing of the iteration.
void	initialize() Initialize the random number generator with the seed, if it has been given.
boolean	postfire() Calculate the next random number.

Methods inherited from class ptolemy.actor.lib.Source

prefire

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

Methods inherited from interface ptolemy.actor.Initializable

addInitializable, preinitialize, 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

resetOnEachRun

public SharedParameter resetOnEachRun

If true, this parameter specifies that the random number generator should be reset on each run of the model (in the initialize() method). It is a boolean that defaults to false. This is a shared parameter, meaning that changing it somewhere in the model causes it to be changed everywhere in the model.

seed

public SharedParameter seed

The seed that controls the random number generation. This is a shared parameter, meaning that all instances of RandomSource or derived classes in the same model share the same value. A seed of zero is interpreted to mean that no seed is specified, which means that each execution of the model could result in distinct data. For the value 0, the seed is set to System.currentTimeMillis() + hashCode(), which means that with extremely high probability, two distinct actors will have distinct seeds. However, current time may not have enough resolution to ensure that two subsequent executions of the same model have distinct seeds. For a value other than zero, the seed is set to that value plus the hashCode() of the full name of the actor. This means that with high probability, two distinct actors will have distinct, but repeatable seeds. This parameter contains a LongToken, initially with value 0.

_generatorSeed

protected long _generatorSeed

The current value of the seed parameter.

_needNew

protected boolean _needNew

Indicator that a new random number is needed.

_needNewGenerator

protected boolean _needNewGenerator

Indicator that a new generator is needed.

_random

protected java.util.Random _random

The Random object.

Constructor Detail

RandomSource

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

Construct an actor with the given container and name.

Parameters:

container - The container.

name - The name of this actor.

Throws:

IllegalActionException - If the actor 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 seed then create the base random number generator.

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If the change is not acceptable to this container (not thrown in this base class).

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 creates new ports and parameters.

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

Generate a new random number if this is the first firing of the iteration.

Specified by:

fire in interface Executable

Overrides:

fire in class Source

Throws:

IllegalActionException - If there is no director.

initialize

public void initialize()
                throws IllegalActionException

Initialize the random number generator with the seed, if it has been given. A seed of zero is interpreted to mean that no seed is specified. In such cases, a seed based on the current time and this instance of a RandomSource is used to be fairly sure that two identical sequences will not be returned.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class AtomicActor

Throws:

IllegalActionException - If the parent class throws it.

postfire

public boolean postfire()
                 throws IllegalActionException

Calculate the next random number.

Specified by:

postfire in interface Executable

Overrides:

postfire in class AtomicActor

Returns:

True if it is ok to continue.

Throws:

IllegalActionException - If the base class throws it.

_createGenerator

protected void _createGenerator()
                         throws IllegalActionException

Create the random number generator using current parameter values.

Throws:

IllegalActionException - If thrown while reading the seed Token.

_generateRandomNumber

protected abstract void _generateRandomNumber()
                                       throws IllegalActionException

Generate a new random number.

Throws:

IllegalActionException - Not thrown in this base class. Derived classes may throw it if there are problems getting parameter values.