Package ptolemy.domains.modal.kernel

Class MultirateFSMDirector

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.kernel.util.Attribute

ptolemy.actor.Director

ptolemy.domains.modal.kernel.FSMDirector

ptolemy.domains.modal.kernel.MultirateFSMDirector

All Implemented Interfaces:

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

Direct Known Subclasses:

HDFFSMDirector

public class MultirateFSMDirector
extends FSMDirector

This director extends FSMDirector by supporting production and consumption of multiple tokens on a port in a firing. This director assumes that every state has exactly one refinement, unless the state has an immediate transition whose guard evaluates to true in the iteration in which the state is entered. In addition, preemptive transitions are not allowed. Hence, each time when a modal model is fired, the current state always has a state refinement that is fired and will consume and produce outputs.

The number of tokens to be transferred from an input port of the modal model is at most the token consumption rate inferred by the inside port of the current state refinement. The number of tokens to be transferred from an output port of the state refinement is exactly the token production rate inferred by the state refinement. If there are not enough tokens available from the refinement, an exception is thrown. The default token consumption and production rate of a port is 1.

When a state transition occurs, this director compares the port rates of the destination state refinement with that of the current state refinement. If the rates are different, then it invalidate the schedule of the executive director of the modal model and updates the port rates of the modal model to be the port rates of the destination state refinement.

Since:

Ptolemy II 8.0

Version:

$Id$

Author:

Ye Zhou and Edward A. Lee

See Also:

FSMDirector

Pt.AcceptedRating:

Red (hyzheng)

Pt.ProposedRating:

Red (hyzheng)

Nested Class Summary

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

NamedObj.ContainedObjectsIterator

Field Summary

Fields inherited from class ptolemy.domains.modal.kernel.FSMDirector

_currentLocalReceiverMap, _indexOffset, _localReceiverMaps, controllerName

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	Description
MultirateFSMDirector(CompositeEntity container, java.lang.String name)	Construct a director in the given container with the given name.

Method Summary

Modifier and Type	Method	Description
protected void	_declareDependency(ConstVariableModelAnalysis analysis, IOPort port, java.lang.String name, java.util.List dependents)	Add a DependencyDeclaration (with the name "_MultirateFSMRateDependencyDeclaration") to the variable with the given name in the given port that declares the variable is dependent on the given list of variables.
protected void	_declareReconfigurationDependencyForRefinementRateVariables(ConstVariableModelAnalysis analysis, IOPort port, java.lang.String parameterName)	Declare the reconfiguration dependency in the given analysis associated with the parameter name of the given port.
protected boolean	_doPostfire()	Postfire the modal model and commit the transition.
protected CompositeActor	_getEnclosingDomainActor()	If the container of this director does not have an MultirateFSMDirector as its executive director, then return the container.
protected java.util.List	_getRefinementRateVariables(IOPort port, java.lang.String parameterName)	Return the set of variables with the given parameter name that are contained by ports connected to the given port on the inside.
protected void	_setProductionConsumptionRates()	Set the production and consumption rates based on the refinement of the current state, after descending through a hierarchy of state machines.
protected boolean	_updateInputTokenConsumptionRates(TypedCompositeActor actor)	Extract the token consumption rates from the input ports of the current refinement and update the rates of the input ports of the modal model containing the refinement.
protected boolean	_updateOutputTokenProductionRates(TypedCompositeActor actor)	Extract the token production rates from the output ports of the current refinement and update the production and initial production rates of the output ports of the modal model containing the refinement.
void	fire()	Fire the modal model.
Time	fireAt(Actor actor, Time time)	Override the base class to ignore the fireAt() call if the specified actor is the controller and the time is the current time.
Time	fireAtCurrentTime(Actor actor)	Override the base class to ignore the fireAt() call if the specified actor is the controller.
void	initialize()	Initialize the mode controller and all the refinements.
Receiver	newReceiver()	Return a new receiver of a type compatible with this director.
boolean	postfire()	Postfire the modal model and commit the transition.
void	preinitialize()	Preinitialize all actors deeply contained by the container of this director.
boolean	supportMultirateFiring()	Return a boolean to indicate whether a ModalModel under control of this director supports multirate firing.
boolean	transferInputs(IOPort port)	Transfer data from the input port of the container to the ports connected to the inside of the input port and on the mode controller or the refinement of its current state.
boolean	transferOutputs(IOPort port)	Transfer data from an output port of the current refinement actor to the ports it is connected to on the outside.

Methods inherited from class ptolemy.domains.modal.kernel.FSMDirector

_buildLocalReceiverMaps, _currentLocalReceivers, _getLastChosenTransition, _getStateRefinementsToPostfire, _getTransitionRefinementsToPostfire, _readInputs, _readOutputsFromRefinement, _setCurrentConnectionMap, _setCurrentState, _transferOutputs, attributeChanged, clone, defaultDependency, fireAt, getContext, getController, getIndex, getModelNextIterationTime, getModifiedVariables, getParseTreeEvaluator, handleModelError, implementsStrictActorSemantics, invalidateSchedule, isStrict, prefire, resetOutputReceivers, setContainer, setIndex

Methods inherited from class ptolemy.actor.Director

_actorFinished, _consultTimeRegulators, _description, _isEmbedded, _isTopLevel, _schedule, _transferInputs, addInitializable, createSchedule, delayDependency, elapsedTimeSinceStart, finish, fireAt, fireContainerAt, fireContainerAt, getCausalityInterface, getCurrentTime, getDeadline, getEnvironmentTime, getExecutionAspect, getGlobalTime, getModelStartTime, getModelStopTime, getModelTime, getNextIterationTime, getStartTime, getStopTime, getTimeResolution, initialize, invalidateResolvedTypes, isEmbedded, isFireFunctional, isStopRequested, iterate, mutexLockObject, notifyTokenSentToCommunicationAspect, preinitialize, removeInitializable, requestInitialization, resume, resumeActor, scheduleContainedActors, setCurrentTime, setEmbedded, setModelTime, setTimeResolution, stop, stopFire, suggestedModalModelDirectors, suspend, terminate, 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, 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

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getContainer, getDisplayName, getFullName, getName, getName, setName

Constructor Detail

MultirateFSMDirector

public MultirateFSMDirector(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.

Parameters:

container - Container of this director.

name - Name of this director.

Throws:

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

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

Method Detail

fire

public void fire()
          throws IllegalActionException

Fire the modal model. If the refinement of the current state of the mode controller is ready to fire, then fire the current refinement.

Specified by:

fire in interface Executable

Overrides:

fire in class FSMDirector

Throws:

IllegalActionException - If there is no controller or the current state has no or more than one refinement, or if the current state has any preemptive transitions.

fireAt

public Time fireAt(Actor actor,
                   Time time)
            throws IllegalActionException

Override the base class to ignore the fireAt() call if the specified actor is the controller and the time is the current time. The controller calls fireAt() if the destination state is enabled, but this director already handles transient states.

Overrides:

fireAt in class Director

Parameters:

actor - The actor scheduled to be fired.

time - The time at which to fire the actor.

Returns:

If the argument is the controller, then return Time.NEGATIVE_INFINITY, to indicate that the request is being ignored. Otherwise, return what the superclass returns.

Throws:

IllegalActionException - If thrown by the executive director.

See Also:

Director.fireAtCurrentTime(Actor)

fireAtCurrentTime

public Time fireAtCurrentTime(Actor actor)
                       throws IllegalActionException

Override the base class to ignore the fireAt() call if the specified actor is the controller. The controller calls fireAtCurrentTime() if the destination state is enabled, but this director already handles transient states.

Overrides:

fireAtCurrentTime in class Director

Parameters:

actor - The actor scheduled to be fired.

Returns:

If the argument is the controller, then return Time.NEGATIVE_INFINITY, to indicate that the request is being ignored. Otherwise, return what the superclass returns.

Throws:

IllegalActionException - If thrown by the executive director.

See Also:

Director.fireAt(Actor, Time)

initialize

public void initialize()
                throws IllegalActionException

Initialize the mode controller and all the refinements. Notify updates of port rates to the upper level director, and invalidate the upper level schedule.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class FSMDirector

Throws:

IllegalActionException - If the refinement has no or more than one refinement, or the initialize() method of one of the associated actors throws it.

newReceiver

public Receiver newReceiver()

Return a new receiver of a type compatible with this director. This returns an instance of SDFReceiver.

Overrides:

newReceiver in class FSMDirector

Returns:

A new SDFReceiver.

postfire

public boolean postfire()
                 throws IllegalActionException

Postfire the modal model and commit the transition.

Specified by:

postfire in interface Executable

Overrides:

postfire in class FSMDirector

Returns:

True if the postfire() method of current state refinement and that of the controller are both true.

Throws:

IllegalActionException - If a refinement throws it, or if there is no controller.

preinitialize

public void preinitialize()
                   throws IllegalActionException

Preinitialize all actors deeply contained by the container of this director. Find the "non-transient initial state", which is the first non-transient state reached from the initial state. Propagate the consumption and production rates of the non-transient initial state out to corresponding ports of the container of this director.

Specified by:

preinitialize in interface Initializable

Overrides:

preinitialize in class FSMDirector

Throws:

IllegalActionException - If there is no controller, or if the non-transient initial state has no or more than one refinement, or if the preinitialize() method of one of the associated actors throws it.

supportMultirateFiring

public boolean supportMultirateFiring()

Return a boolean to indicate whether 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 does support multirate firing.

transferInputs

public boolean transferInputs(IOPort port)
                       throws IllegalActionException

Transfer data from the input port of the container to the ports connected to the inside of the input port and on the mode controller or the refinement of its current state. This method overrides the base class method by transferring at most the number of tokens specified by the input consumption rate.

Overrides:

transferInputs in class FSMDirector

Parameters:

port - The input port to transfer tokens from.

Returns:

True if data are transferred.

Throws:

IllegalActionException - If the port is not an opaque input port.

transferOutputs

public boolean transferOutputs(IOPort port)
                        throws IllegalActionException

Transfer data from an output port of the current refinement actor to the ports it is connected to on the outside. This method overrides the base class method in that this method will transfer exactly k tokens in the receivers, where k is the port rate if it is declared by the port.

Overrides:

transferOutputs in class Director

Parameters:

port - The port to transfer tokens from.

Returns:

True if data are transferred.

Throws:

IllegalActionException - If the port is not an opaque output port.

_declareDependency

protected void _declareDependency(ConstVariableModelAnalysis analysis,
                                  IOPort port,
                                  java.lang.String name,
                                  java.util.List dependents)
                           throws IllegalActionException

Add a DependencyDeclaration (with the name "_MultirateFSMRateDependencyDeclaration") to the variable with the given name in the given port that declares the variable is dependent on the given list of variables. If a dependency declaration with that name already exists, then simply set its dependents list to the given list.

Parameters:

analysis - The object that contains the dependency declarations.

port - The IOPort to get rate variables from.

name - The name of the IOPort.

dependents - The dependents that the dependency declaration of the given IO port depends on.

Throws:

IllegalActionException - If a valid rate variable from the given port can not be found, or the variable does not contain a DependencyDeclaration attribute, or a new DependencyDeclaration object can not be created, or can not associated with the analysis object the newly created DependencyDeclaration object.

_declareReconfigurationDependencyForRefinementRateVariables

protected void _declareReconfigurationDependencyForRefinementRateVariables(ConstVariableModelAnalysis analysis,
                                                                           IOPort port,
                                                                           java.lang.String parameterName)
                                                                    throws IllegalActionException

Declare the reconfiguration dependency in the given analysis associated with the parameter name of the given port.

Parameters:

analysis - The object that contains the dependency declarations.

port - The IOPort to get refinement rate variables from.

parameterName - The name of the rate variables.

Throws:

IllegalActionException - If can not get the refinement rate variables from the given port, or can not add the dependency declaration of the given port to the analysis object, or a declared constant rate variable does not contain a constant value.

_doPostfire

protected boolean _doPostfire()
                       throws IllegalActionException

Postfire the modal model and commit the transition. If a transition is taken, the update the token production and consumption rates according to the new refinement.

Returns:

True if the super class postfire() method returns true.

Throws:

IllegalActionException - If there is no controller, or if the destination state has no or more than one refinement, or if the state refinement throws it.

_getEnclosingDomainActor

protected CompositeActor _getEnclosingDomainActor()
                                           throws IllegalActionException

If the container of this director does not have an MultirateFSMDirector as its executive director, then return the container. Otherwise, move up the hierarchy until we reach a container actor that does not have a MultirateFSMDirector director for its executive director, and return that container.

Returns:

a composite actor that does not contain a MultirateFSMDirector object.

Throws:

IllegalActionException - If the top-level director is an MultirateFSMDirector. This director is intended for use only inside some other domain.

_getRefinementRateVariables

protected java.util.List _getRefinementRateVariables(IOPort port,
                                                     java.lang.String parameterName)
                                              throws IllegalActionException

Return the set of variables with the given parameter name that are contained by ports connected to the given port on the inside.

Parameters:

port - The given port.

parameterName - The given parameter name.

Returns:

A list of the variables with the given parameter name.

Throws:

IllegalActionException - If can not get a rate variable from the port that is connected to the given port from inside.

_setProductionConsumptionRates

protected void _setProductionConsumptionRates()
                                       throws IllegalActionException

Set the production and consumption rates based on the refinement of the current state, after descending through a hierarchy of state machines.

Throws:

IllegalActionException - If the initial state does not have exactly one refinement.

_updateInputTokenConsumptionRates

protected boolean _updateInputTokenConsumptionRates(TypedCompositeActor actor)
                                             throws IllegalActionException

Extract the token consumption rates from the input ports of the current refinement and update the rates of the input ports of the modal model containing the refinement.

Parameters:

actor - The current refinement.

Returns:

True if any input token consumption rate is changed from its previous value.

Throws:

IllegalActionException - If can not find the controller, or the port connections between controller and refinements are not correct, or can not get valid token consumption rates for input ports.

_updateOutputTokenProductionRates

protected boolean _updateOutputTokenProductionRates(TypedCompositeActor actor)
                                             throws IllegalActionException

Extract the token production rates from the output ports of the current refinement and update the production and initial production rates of the output ports of the modal model containing the refinement.

Parameters:

actor - The current refinement.

Returns:

True if any of the output token production rate is changed from its previous value.

Throws:

IllegalActionException - If we cannot get valid token consumption rates for input ports.