ptolemy.domains.sequence.kernel

Class SequencedModelDirector

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.kernel.util.Attribute

ptolemy.actor.Director

ptolemy.domains.sequence.kernel.SequencedModelDirector

All Implemented Interfaces:

java.lang.Cloneable, Executable, Initializable, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

Direct Known Subclasses:

ProcessDirector, SequenceDirector

public abstract class SequencedModelDirector
extends Director

An abstract base class for SequenceDirector and ProcessDirector.

The SequencedModelDirector
- Computes the sequenced actors and passes these in two lists to the SequenceScheduler (one list for independent sequenced actors, and one list for sequenced actors that are dependent on other actors e.g. control actors)

Since:

Ptolemy II 10.0

Version:

$Id$

Author:

Elizabeth Latronico (Bosch), rrs1pal

Pt.AcceptedRating:

Red (beth)

Pt.ProposedRating:

Red (beth)

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.kernel.util.NamedObj

NamedObj.ContainedObjectsIterator

Field Summary

Fields

Modifier and Type	Field and Description
protected int	_iterationCount The iteration count.
protected boolean	_postfireReturns The value that the postfire method will return.
protected SequenceScheduler	_scheduler The scheduler for this director.
protected java.util.List<SequenceAttribute>	_sequencedList The list of sequenced actors in the model.
Parameter	defaultOutputInitialValue If true, enable default output initial values.
Parameter	fireUnexecutedActors If true, fire any unexecuted actors that were not fired during the sequence schedule.
Parameter	iterations A Parameter representing the number of times that postfire may be called before it returns false.
Parameter	userDefinedDefaultOutputInitialValue The user defined default output initial value.
Parameter	userDefinedOutputInitialValue If true, enable user defined output initial values.

Fields inherited from class ptolemy.actor.Director

_actorsFinishedExecution, _aspectForActor, _aspectsPresent, _defaultMicrostep, _executionAspects, _finishRequested, _initializables, _nextScheduleTime, _stopRequested, _tokenSentToCommunicationAspect, _zeroTime, localClock, startTime, stopTime

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _deferChangeRequests, _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

Constructors

Constructor and Description
SequencedModelDirector() Construct a director in the default workspace with an empty string as its name.
SequencedModelDirector(CompositeEntity container, java.lang.String name) Construct a director in the given container with the given name.
SequencedModelDirector(Workspace workspace) Construct a director in the workspace with an empty name.

Method Summary

Modifier and Type	Method and Description
protected static java.lang.String	_getInitialValueParameterName(TypedIOPort port, int channel) Return the initialValueParameter Name for each of the port.
protected void	_init() Initialize the object.
protected void	_setScheduler(SequenceScheduler scheduler) Copied from SDFDirector; also, same as in StaticSchedulingDirector Set the local scheduler for execution of this Director.
void	checkAttributeType(Actor actor, java.util.List sequenceAttributes, java.util.List processAttributes) Check for SequenceAttribute or ProcessAttribute for multiple or wrong occurrence in the model.
java.lang.Object	clone(Workspace workspace) Code copied from StaticSchedulingDirector FIXME: Do we just want a SequencedModelDirector to be a subclass of StaticSchedulingDirector?
protected void	fireSchedule(SequenceSchedule seqSchedule) Fire the given SequenceSchedule.
void	getContainedEntities(CompositeActor compositeActor) The SequencedModelDirector adds all actors with sequence numbers to the _sequencedList, regardless of whether or not the actors have a process attribute.
SequenceScheduler	getScheduler() Return the scheduler that is responsible for scheduling the directed actors.
void	initialize() Initialize the actors associated with this director and then set the iteration count to zero.
void	invalidateSchedule() Indicate that a schedule for the model may no longer be valid.
boolean	isScheduleValid() Return true if the current (cached) schedule is valid.
Receiver	newReceiver() Return a new receiver consistent with the Sequence domain.
boolean	postfire() Return false if the system has finished executing, either by reaching the iteration limit, or having an actor in the system return false in postfire.
void	preinitialize() Preinitialize will be added to in subclasses Preinitialize the actors associated with this director and compute the schedule.
void	setOutputInitialValues(Entity actorEntity) Set the initial values for output ports.
void	setScheduler(SequenceScheduler scheduler) Copied from SDFScheduler; also, same as in StaticSchedulingDirector Set the scheduler for this SequenceDirector.
java.lang.String[]	suggestedModalModelDirectors() Return an array of suggested ModalModel directors to use with SequencedModelDirector.
boolean	supportMultirateFiring() Return true to indicate that a ModalModel under control of this director supports multirate firing.

Methods inherited from class ptolemy.actor.Director

_actorFinished, _consultTimeRegulators, _description, _isEmbedded, _isTopLevel, _schedule, _transferInputs, _transferOutputs, addInitializable, attributeChanged, createSchedule, defaultDependency, delayDependency, elapsedTimeSinceStart, finish, fire, fireAt, fireAt, fireAt, fireAtCurrentTime, fireContainerAt, fireContainerAt, getCausalityInterface, getCurrentTime, getDeadline, getEnvironmentTime, getExecutionAspect, getGlobalTime, getModelNextIterationTime, getModelStartTime, getModelStopTime, getModelTime, getNextIterationTime, getStartTime, getStopTime, getTimeResolution, implementsStrictActorSemantics, initialize, invalidateResolvedTypes, isEmbedded, isFireFunctional, isStopRequested, isStrict, iterate, mutexLockObject, notifyTokenSentToCommunicationAspect, prefire, preinitialize, removeInitializable, requestInitialization, resume, resumeActor, scheduleContainedActors, setContainer, setCurrentTime, setEmbedded, setModelTime, setTimeResolution, stop, stopFire, suspend, terminate, transferInputs, transferOutputs, transferOutputs, wrapup

Methods inherited from class ptolemy.kernel.util.Attribute

_checkContainer, _getContainedObject, _propagateExistence, getContainer, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, setName, updateContent

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _containedDecorators, _copyChangeRequestList, _debug, _debug, _debug, _debug, _debug, _executeChangeRequests, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _notifyHierarchyListenersAfterChange, _notifyHierarchyListenersBeforeChange, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, addDebugListener, addHierarchyListener, attributeDeleted, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, decorators, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, notifyOfNameChange, propagateExistence, propagateValue, propagateValues, removeAttribute, removeChangeListener, removeDebugListener, removeHierarchyListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, uniqueName, validateSettables, workspace

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

iterations

public Parameter iterations

A Parameter representing the number of times that postfire may be called before it returns false. If the value is less than or equal to zero, then the execution will never return false in postfire, and thus the execution can continue forever. Note that the amount of data processed by the Sequence model is a function of both this parameter and the value of parameter vectorizationFactor, since vectorizationFactor can influence the choice of schedule. The default value is an IntToken with the value zero.

userDefinedOutputInitialValue

public Parameter userDefinedOutputInitialValue

If true, enable user defined output initial values. The default value is a boolean true.

userDefinedDefaultOutputInitialValue

public Parameter userDefinedDefaultOutputInitialValue

The user defined default output initial value. The default type is BaseType.GENERAL.

defaultOutputInitialValue

public Parameter defaultOutputInitialValue

If true, enable default output initial values. The default value is a boolean true.

fireUnexecutedActors

public Parameter fireUnexecutedActors

If true, fire any unexecuted actors that were not fired during the sequence schedule.

_sequencedList

protected java.util.List<SequenceAttribute> _sequencedList

The list of sequenced actors in the model.

_scheduler

protected SequenceScheduler _scheduler

The scheduler for this director.

_postfireReturns

protected boolean _postfireReturns

The value that the postfire method will return.

_iterationCount

protected int _iterationCount

The iteration count.

Constructor Detail

SequencedModelDirector

public SequencedModelDirector()
                       throws IllegalActionException,
                              NameDuplicationException

Construct a director in the default workspace with an empty string as its name. The director is added to the list of objects in the workspace. Increment the version number of the workspace. The SequencedModelDirector will have a default scheduler of type SequenceScheduler.

Throws:

IllegalActionException - If the name has a period in it, or the director is not compatible with the specified container.

NameDuplicationException - If the container already contains an entity with the specified name.

SequencedModelDirector

public SequencedModelDirector(Workspace workspace)
                       throws IllegalActionException,
                              NameDuplicationException

Construct a director in the workspace with an empty name. The director is added to the list of objects in the workspace. Increment the version number of the workspace. The SequencedModelDirector will have a default scheduler of type SequenceScheduler.

Parameters:

workspace - The workspace for this object.

Throws:

IllegalActionException - If the name has a period in it, or the director is not compatible with the specified container.

NameDuplicationException - If the container already contains an entity with the specified name.

SequencedModelDirector

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

Construct a director in the given container with the given name. The container argument must not be null, or a NullPointerException will be thrown. If the name argument is null, then the name is set to the empty string. Increment the version number of the workspace. The SequencedModelDirector will have a default scheduler of type SequenceScheduler.

Parameters:

container - Container of the director.

name - Name of this director.

Throws:

IllegalActionException - If the director is not compatible with the specified container. May be thrown in a derived class.

NameDuplicationException - If the container is not a CompositeActor and the name collides with an entity in the container.

Method Detail

clone

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

Code copied from StaticSchedulingDirector FIXME: Do we just want a SequencedModelDirector to be a subclass of StaticSchedulingDirector? But, the complete schedule is not statically computable if control actors are present FIXME: I am not sure if this works correctly in all situations... Clone is needed in the director to clone the scheduler Clone the object into the specified workspace. The new object is not added to the directory of that workspace (you must do this yourself if you want it there).

Overrides:

clone in class Director

Parameters:

workspace - The workspace for the cloned object.

Returns:

The new Attribute.

Throws:

java.lang.CloneNotSupportedException - Not thrown in this base class

See Also:

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

getScheduler

public SequenceScheduler getScheduler()

Return the scheduler that is responsible for scheduling the directed actors. This method is read-synchronized on the workspace.

Returns:

The contained scheduler.

See Also:

setScheduler(SequenceScheduler)

invalidateSchedule

public void invalidateSchedule()

Indicate that a schedule for the model may no longer be valid. This method should be called when topology changes are made, or for that matter when any change that may invalidate the schedule is made. In this base class, this method sets a flag that forces scheduling to be redone at the next opportunity. If there is no scheduler, do nothing.

Overrides:

invalidateSchedule in class Director

isScheduleValid

public boolean isScheduleValid()
                        throws IllegalActionException

Return true if the current (cached) schedule is valid. This calls the valid() method of Scheduler.

Returns:

true if the schedule is valid.

Throws:

IllegalActionException - If there's no scheduler.

initialize

public void initialize()
                throws IllegalActionException

Initialize the actors associated with this director and then set the iteration count to zero. The order in which the actors are initialized is arbitrary. In addition, if actors connected directly to output ports have initial production, then copy that initial production to the outside of the composite actor.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class Director

Throws:

IllegalActionException - If the initialize() method of one of the associated actors throws it, or if there is no scheduler.

setOutputInitialValues

public void setOutputInitialValues(Entity actorEntity)
                            throws IllegalActionException

Set the initial values for output ports. FIXME: There are problems with the current way some of these settings are defined in the director. We discussed a solution but did not have time to implement it yet. Check the open item list for comments about this. Actors with SequenceAttributes/ProcessAttributes are required to have initial values defined for the output ports. This is to ensure that if another actor is executed first which consumes data from a sequenced actor that is fired later in the schedule, then a value will be available for the first actor to use.

Parameters:

actorEntity - The entity

Throws:

IllegalActionException - If thrown while getting the width of a port or getting the value of a parameter.

newReceiver

public Receiver newReceiver()

Return a new receiver consistent with the Sequence domain.

Overrides:

newReceiver in class Director

Returns:

A new SequenceReceiver.

preinitialize

public void preinitialize()
                   throws IllegalActionException

Preinitialize will be added to in subclasses Preinitialize the actors associated with this director and compute the schedule. The schedule is computed during preinitialization so that hierarchical opaque composite actors can be scheduled properly. In addition, performing scheduling during preinitialization enables it to be present during code generation. The order in which the actors are preinitialized is arbitrary.

Specified by:

preinitialize in interface Initializable

Overrides:

preinitialize in class Director

Throws:

IllegalActionException - If the preinitialize() method of one of the associated actors throws it.

getContainedEntities

public void getContainedEntities(CompositeActor compositeActor)
                          throws IllegalActionException

The SequencedModelDirector adds all actors with sequence numbers to the _sequencedList, regardless of whether or not the actors have a process attribute. In some models, actors with sequence numbers, but without process attributes, are in fact dependent actors. The scheduler will later need to ascertain which actors are dependent on control actors, and remove them from the _independentList.

Parameters:

compositeActor - The composite actor to be searched for entities.

Throws:

IllegalActionException - If thrown while checking the attribute type.

checkAttributeType

public void checkAttributeType(Actor actor,
                               java.util.List sequenceAttributes,
                               java.util.List processAttributes)
                        throws IllegalActionException

Check for SequenceAttribute or ProcessAttribute for multiple or wrong occurrence in the model.

Parameters:

actor - The actor to be checked.

sequenceAttributes - The list of sequence attributes to be checked.

processAttributes - The list of process attributes to be checked

Throws:

IllegalActionException - If sequenceAttributes has a length greater than one or if actor is not an instance of ControlActor.

postfire

public boolean postfire()
                 throws IllegalActionException

Return false if the system has finished executing, either by reaching the iteration limit, or having an actor in the system return false in postfire. Increment the number of iterations. If the "iterations" parameter is greater than zero, then see if the limit has been reached. If so, return false. Otherwise return true if all of the fired actors since the last call to prefire returned true. If the period parameter is greater than 0.0, then if this director is at the top level, then increment time by the specified period, and otherwise request a refiring at the current time plus the period.

Specified by:

postfire in interface Executable

Overrides:

postfire in class Director

Returns:

True if the Director wants to be fired again in the future.

Throws:

IllegalActionException - If the iterations parameter does not contain a legal value.

suggestedModalModelDirectors

public java.lang.String[] suggestedModalModelDirectors()

Return an array of suggested ModalModel directors to use with SequencedModelDirector. The default director is HDFFSMDirector, which supports multirate actors and only allows state transitions on each iteration. This is the most safe director to use with Sequence models. MultirateFSMDirector supports multirate actors and allows state transitions on each firing of the modal model. MultirateFSMDirector can be used with Sequence if rate signatures for all the states in the modal model are same. If rate signatures change during an iteration, the SequenceDirector will throw an exception. FSMDirector can be used with SequenceDirector only when rate signatures for modal model are all 1.

Overrides:

suggestedModalModelDirectors in class Director

Returns:

An array of suggested directors to be used with ModalModel.

See Also:

Director.suggestedModalModelDirectors()

supportMultirateFiring

public boolean supportMultirateFiring()

Return true to indicate that a ModalModel under control of this director supports multirate firing.

Overrides:

supportMultirateFiring in class Director

Returns:

True indicating a ModalModel under control of this director supports multirate firing.

setScheduler

public void setScheduler(SequenceScheduler scheduler)
                  throws IllegalActionException,
                         NameDuplicationException

Copied from SDFScheduler; also, same as in StaticSchedulingDirector Set the scheduler for this SequenceDirector. The container of the specified scheduler is set to this director. If there was a previous scheduler, the container of that scheduler is set to null. This method is write-synchronized on the workspace. If the scheduler is not compatible with the director, an IllegalActionException is thrown.

Parameters:

scheduler - The scheduler that this director will use.

Throws:

IllegalActionException - Not thrown in this base class, but derived classes may throw it if the scheduler is not compatible.

NameDuplicationException - Not thrown in this base class, but derived classes may throw it if the scheduler is not compatible.

See Also:

getScheduler()

_setScheduler

protected void _setScheduler(SequenceScheduler scheduler)

Copied from SDFDirector; also, same as in StaticSchedulingDirector Set the local scheduler for execution of this Director. This should not be called be directly. Instead, call setContainer() on the scheduler. This method removes any previous scheduler from this container, and caches a local reference to the scheduler so that this composite does not need to search its attributes each time the scheduler is accessed.

Parameters:

scheduler - The Scheduler responsible for execution.

fireSchedule

protected void fireSchedule(SequenceSchedule seqSchedule)
                     throws IllegalActionException

Fire the given SequenceSchedule. This is the same for the ProcessDirector and SequenceDirector (although how the schedule is determined is different)

Parameters:

seqSchedule - The SequenceSchedule to fire

Throws:

IllegalActionException - From actor.iterate()

_init

protected void _init()
              throws IllegalActionException,
                     NameDuplicationException

Initialize the object. In this case, we give the SequencedModelDirector a default scheduler of the class SequenceScheduler, an iterations parameter and a vectorizationFactor parameter.

Throws:

IllegalActionException - If there is a problem instantiating the director's parameters.

NameDuplicationException - If there is a problem instantiating the director's parameters.

_getInitialValueParameterName

protected static java.lang.String _getInitialValueParameterName(TypedIOPort port,
                                                                int channel)

Return the initialValueParameter Name for each of the port.

Parameters:

port - The port to be analyzed.

channel - The channel of the port to be analyzed.

Returns:

The initial value parameter name.