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.io.Serializable, java.lang.Cloneable, Executable, Initializable, QuasiTransparentDirector, SuperdenseTimeDirector, ExplicitChangeContext, Changeable, Debuggable, DebugListener, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

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, with one exception. A state may have no refinement if upon being entered, it has an outgoing transition with a guard that is true. This will be treated as a "transient state." Transient states can have preemptive and non-preemptive transitions, while non-transient states are assumed to have only non-preemptive transitions. When a modal model reaches a transient state, it will progress through that state to the next state until it encounters a state with a refinement. This procedure is done in the preinitialize() method and the postfire() method. Hence each time when a modal model is fired, the current state always has a state refinement.

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 invalidate the schedule of the executive director of the modal model. Update the port rates of the modal model to be the port rates of the destination state refinement.

This director does not support transition refinements.

Since:

Ptolemy II 8.0

Version:

$Id: MultirateFSMDirector.java 57340 2010-02-26 02:00:31Z cxh $

Author:

Ye Zhou

See Also:

FSMDirector, Serialized Form

Accepted Rating:

Red (hyzheng)

Proposed Rating:

Red (hyzheng)

Nested Class Summary

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

NamedObj.ContainedObjectsIterator

Field Summary

protected boolean	_refinementPostfire The returned value of the postfire() method of the currentRefinement.
protected boolean	_reinitialize A flag indicating whether the initialize method is called due to reinitialization.

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

_currentLocalReceiverMap, _disabledActors, _enabledRefinements, _indexOffset, _localReceiverMaps, _stateRefinementsToPostfire, _transitionRefinementsToPostfire, controllerName

Fields inherited from class ptolemy.actor.Director

_actorsFinishedExecution, _currentTime, _finishRequested, _initializables, _stopRequested, timeResolution

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

MultirateFSMDirector(CompositeEntity container, java.lang.String name)
Construct a director in the given container with the given name.

Method Summary

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 CompositeActor	_getEnclosingDomainActor() If the container of this director does not have an MultirateFSMDirector as its executive director, then return the container.
private State	_getNonTransientState() Return the current state if it has a refinement.
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 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	chooseNextNonTransientState(State currentState) Choose the next non-transient state given the current state.
State	chooseTransition(State state) Choose an enabled transition leaving the given state.
void	fire() Fire the modal model.
Time	fireAtCurrentTime(Actor actor) Override the base class to ignore the fireAt() call if the specified actor is the controller.
void	initialize() Initialize the modal model.
boolean	makeStateTransition() Commit transition and set up new state and connection map if exactly one transition is enabled.
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, _chooseTransition, _currentLocalReceivers, _enableActor, _getLastChosenTransition, _readInputs, _readOutputsFromRefinement, _setCurrentConnectionMap, _setCurrentState, _transferOutputs, attributeChanged, clone, defaultDependency, fireAt, getContext, getController, getIndex, getModelNextIterationTime, getModifiedVariables, getParseTreeEvaluator, handleModelError, implementsStrictActorSemantics, invalidateSchedule, isStrict, prefire, setContainer, setIndex, setModelTime

Methods inherited from class ptolemy.actor.Director

_description, _fireContainerAt, _isEmbedded, _isTopLevel, _transferInputs, addInitializable, createSchedule, finish, fireAt, getCausalityInterface, getCurrentTime, getErrorTolerance, getGlobalTime, getModelStartTime, getModelStopTime, getModelTime, getNextIterationTime, getStartTime, getStopTime, getTimeResolution, initialize, invalidateResolvedTypes, isFireFunctional, isStopRequested, iterate, preinitialize, removeInitializable, requestInitialization, setCurrentTime, stop, stopFire, suggestedModalModelDirectors, terminate, 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, _debug, _debug, _debug, _debug, _debug, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _recordDecoratedAttributes, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, addDebugListener, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, 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, propagateExistence, propagateValue, propagateValues, removeChangeListener, removeDebugListener, 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

Field Detail

_reinitialize

protected boolean _reinitialize

A flag indicating whether the initialize method is called due to reinitialization.

_refinementPostfire

protected boolean _refinementPostfire

The returned value of the postfire() method of the currentRefinement.

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

chooseNextNonTransientState

public void chooseNextNonTransientState(State currentState)
                                 throws IllegalActionException

Choose the next non-transient state given the current state.

Parameters:

currentState - The current state.

Throws:

IllegalActionException - If a transient state is reached but no further transition is enabled.

chooseTransition

public State chooseTransition(State state)
                       throws IllegalActionException

Choose an enabled transition leaving the given state. If the transition refinement is null, then first evaluate preemptive transitions. If no preemptive transition is enabled or the transition refinement is not null, then evaluate nonpreemptive transitions. If more than one transition is enabled, an exception is thrown. If there is exactly one transition enabled, then it is chosen and the choice actions contained by that transition are executed. The destination state is returned. If no transition is enabled, the current state is returned.

Parameters:

state - The given state.

Returns:

The destination state, or the current state if no transition is enabled.

Throws:

IllegalActionException - If a non-transient state has preemptive transitions, or if a transition has refinement.

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. Choose the next non-transient state.

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.

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 modal model. If this method is called immediately after preinitialize(), initialize the mode controller and all the refinements. If this is a reinitialization, it typically means this is a sub-layer MultirateFSMDirector and a "reset" has been called at the upper-level MultirateFSMDirector. This method will then reinitialize all the refinements in the sub-layer. 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.

makeStateTransition

public boolean makeStateTransition()
                            throws IllegalActionException

Commit transition and set up new state and connection map if exactly one transition is enabled. Get the schedule of the current refinement and propagate its port rates to the outside.

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.

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 Director

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.

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

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

_getNonTransientState

private State _getNonTransientState()
                             throws IllegalActionException

Return the current state if it has a refinement. Otherwise, make state transitions until a state with a refinement is found. Set that non-transient state to be the current state and return it.

Returns:

The non-transient state.

Throws:

IllegalActionException - If a transient state is reached while no further transition is enabled.