ptolemy.domains.fsm.modal
Class ModalModel

java.lang.Object
  extended byptolemy.kernel.util.NamedObj
      extended byptolemy.kernel.InstantiableNamedObj
          extended byptolemy.kernel.Entity
              extended byptolemy.kernel.ComponentEntity
                  extended byptolemy.kernel.CompositeEntity
                      extended byptolemy.actor.CompositeActor
                          extended byptolemy.actor.TypedCompositeActor
                              extended byptolemy.domains.ct.kernel.CTCompositeActor
                                  extended byptolemy.domains.fsm.modal.ModalModel
All Implemented Interfaces:
ptolemy.actor.Actor, ptolemy.kernel.util.Changeable, java.lang.Cloneable, CTEventGenerator, CTStepSizeControlActor, ptolemy.kernel.util.Debuggable, ptolemy.kernel.util.DebugListener, ptolemy.kernel.util.Derivable, ptolemy.actor.Executable, ptolemy.kernel.util.Instantiable, ptolemy.kernel.util.ModelErrorHandler, ptolemy.kernel.util.MoMLExportable, ptolemy.kernel.util.Nameable, java.io.Serializable, ptolemy.actor.TypedActor

public class ModalModel
extends CTCompositeActor

This is a typed composite actor designed to be a modal model. Inside the modal model is a finite-state machine controller, and inside each state in the FSM is a refinement model. To use this actor, just drag it into a model, and look inside to start constructing the controller. You may add ports to get inputs and outputs, and add states to the controller. You may add one or more refinements to a state (each of these refinements will be executed when this actor is executed). Each refinement is required to have its own director, so you will need to choose a director.

The controller is a finite-state machine (FSM), which consists of states and transitions. One of the states is an initial state. When this actor executes, if the current state has a refinement, then that refinement is executed. Then the guards on all the outgoing transitions of the current state are evaluated, and if one of those guards is true, then the transition is taken. Taking the transition means that the actions associated with the transition are executed (which can result in producing outputs), and the new current state is the state at the destination of the transition. It is an error if more than one of the guards evaluates to true.

To add a state, click on a state button in the toolbar, or drag in a state from the library at the left. To add a transition, position the mouse over the source state, hold the control button, and drag to the destination state. The destination state may be the same state, in which case the transition is used simply to execute its actions.

Adding or removing ports in this actor results in the same ports appearing or disappearing in the FSM controller and in each of the refinements. Similarly, adding or removing ports in the controller or in the refinements results in this actor and the other refinements reflecting the same change to the ports. That is, this actor, the controller, and the refinments all contain the same ports.

There is one subtlety regarding ports however. If you add an output port to a refinement, then the corresponding port in the controller will be both an input and an output. The reason for this is that the controller can access the results of executing a refinement in order to choose a transition.

This class is designed to work closely with ModalController and Refinement, since changes to ports can be initiated in this class or in those. It works with continuous-time as well as discrete-time models.

This class also fulfills the CTEventGenerator interfact so that it can report events generated inside.

Since:
Ptolemy II 2.0
Version:
$Id: ModalModel.java,v 1.14.2.2 2004/06/22 03:53:22 cxh Exp $
Author:
Edward A. Lee
See Also:
ModalController, Refinement, Serialized Form
Accepted Rating:
Red (reviewmoderator)
Proposed Rating:
Red (eal)

Nested Class Summary
 
Nested classes inherited from class ptolemy.kernel.CompositeEntity
ptolemy.kernel.CompositeEntity.ContainedObjectsIterator
 
Field Summary
 ptolemy.kernel.util.StringAttribute directorClass
          A director className string, configured using a ChoiceStyle attribute.
protected  java.lang.String[] modalDirectorClassNames
          Class names of directors compatible with this ModalModel.
 
Fields inherited from class ptolemy.actor.CompositeActor
_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
ModalModel(ptolemy.kernel.CompositeEntity container, java.lang.String name)
          Construct a modal model with a name and a container.
ModalModel(ptolemy.kernel.util.Workspace workspace)
          Construct a modal model in the specified workspace with no container and an empty string as a name.
 
Method Summary
 void attributeChanged(ptolemy.kernel.util.Attribute attribute)
          React to a change of the _director or other property.
 java.lang.Object clone(ptolemy.kernel.util.Workspace workspace)
          Override the base class to ensure that the _controller private variable is reset to the controller of the cloned object.
 FSMActor getController()
          Get the FSM controller.
 ptolemy.actor.util.FunctionDependency getFunctionDependency()
          Return an instance of DirectedGraph, where the nodes are IOPorts, and the edges are the relations between ports.
 FSMDirector newDirector()
          Create a new director for use in this composite.
 ptolemy.kernel.Port newPort(java.lang.String name)
          Create a new port with the specified name in this entity, the controller, and all the refinements.
 void preinitialize()
          Reset internal non-persistent variables and invoke the preinitialize() method of the CompositeActor.
 
Methods inherited from class ptolemy.domains.ct.kernel.CTCompositeActor
hasCurrentEvent, isThisStepAccurate, predictedStepSize, refinedStepSize
 
Methods inherited from class ptolemy.actor.TypedCompositeActor
_addEntity, _addPort, _addRelation, _checkTypesFromTo, _typeConstraintsFromTo, newRelation, resolveTypes, typeConstraintList
 
Methods inherited from class ptolemy.actor.CompositeActor
_finishedAddEntity, _setDirector, connectionsChanged, fire, getDirector, getExecutiveDirector, getManager, initialize, inputPortList, isOpaque, iterate, newInsideReceiver, newReceiver, outputPortList, postfire, prefire, requestChange, setContainer, setDirector, setManager, stop, stopFire, terminate, wrapup
 
Methods inherited from class ptolemy.kernel.CompositeEntity
_adjustDeferrals, _description, _exportMoMLContents, _removeEntity, _removeRelation, allAtomicEntityList, allowLevelCrossingConnect, classDefinitionList, connect, connect, containedObjectsIterator, deepEntityList, deepGetEntities, entityList, entityList, exportLinks, getAttribute, getEntities, getEntity, getPort, getRelation, getRelations, isAtomic, numberOfClassDefinitions, numberOfEntities, numberOfRelations, numEntities, numRelations, relationList, removeAllEntities, removeAllRelations, uniqueName, validateSettables
 
Methods inherited from class ptolemy.kernel.ComponentEntity
_checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, propagateExistence, setName
 
Methods inherited from class ptolemy.kernel.Entity
_removePort, connectedPortList, connectedPorts, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts, setClassDefinition
 
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, attributeTypeChanged, clone, 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, 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, getManager, inputPortList, newReceiver, outputPortList
 
Methods inherited from interface ptolemy.actor.Executable
fire, initialize, iterate, postfire, prefire, stop, stopFire, terminate, wrapup
 
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

directorClass

public ptolemy.kernel.util.StringAttribute directorClass
A director className string, configured using a ChoiceStyle attribute.


modalDirectorClassNames

protected java.lang.String[] modalDirectorClassNames
Class names of directors compatible with this ModalModel. Derived classes should override this if they desire additional or different directors.

Constructor Detail

ModalModel

public ModalModel(ptolemy.kernel.util.Workspace workspace)
           throws ptolemy.kernel.util.IllegalActionException,
                  ptolemy.kernel.util.NameDuplicationException
Construct a modal model in the specified workspace with no container and an empty string as a name. You can then change the name with setName(). If the workspace argument is null, then use the default workspace.

Parameters:
workspace - The workspace that will list the actor.

ModalModel

public ModalModel(ptolemy.kernel.CompositeEntity container,
                  java.lang.String name)
           throws ptolemy.kernel.util.IllegalActionException,
                  ptolemy.kernel.util.NameDuplicationException
Construct a modal model with a name and a container. The container argument must not be null, or a NullPointerException will be thrown.

Parameters:
container - The container.
name - The name of this actor.
Throws:
ptolemy.kernel.util.IllegalActionException - If the container is incompatible with this actor.
ptolemy.kernel.util.NameDuplicationException - If the name coincides with an actor already in the container.
Method Detail

attributeChanged

public void attributeChanged(ptolemy.kernel.util.Attribute attribute)
                      throws ptolemy.kernel.util.IllegalActionException
React to a change of the _director or other property.

Throws:
ptolemy.kernel.util.IllegalActionException

clone

public java.lang.Object clone(ptolemy.kernel.util.Workspace workspace)
                       throws java.lang.CloneNotSupportedException
Override the base class to ensure that the _controller private variable is reset to the controller of the cloned object.

Parameters:
workspace - The workspace for the cloned object.
Returns:
The new Entity.
Throws:
java.lang.CloneNotSupportedException - If cloned ports cannot have as their container the cloned entity (this should not occur), or if one of the attributes cannot be cloned.

getFunctionDependency

public ptolemy.actor.util.FunctionDependency getFunctionDependency()
Return an instance of DirectedGraph, where the nodes are IOPorts, and the edges are the relations between ports. The graph shows the dependencies between the input and output ports. If there is a path between a pair, input and output, they are dependent. Otherwise, they are independent.


getController

public FSMActor getController()
Get the FSM controller.


newDirector

public FSMDirector newDirector()
                        throws ptolemy.kernel.util.IllegalActionException,
                               ptolemy.kernel.util.NameDuplicationException
Create a new director for use in this composite. This base class returns an instance of FSMDirector, but derived classes may return a subclass. Note that this method is called in the constructor, so derived classes will not have been fully constructed when it is called.

Returns:
A new director.
Throws:
ptolemy.kernel.util.IllegalActionException - If constructing the director triggers an exception.
ptolemy.kernel.util.NameDuplicationException - If there is already a director with name "_Director".

newPort

public ptolemy.kernel.Port newPort(java.lang.String name)
                            throws ptolemy.kernel.util.NameDuplicationException
Create a new port with the specified name in this entity, the controller, and all the refinements. Link these ports so that if the new port is set to be an input, output, or multiport, then the change is mirrored in the other ports. The new port will be an instance of ModalPort, which extends TypedIOPort. This method is write-synchronized on the workspace, and increments its version number.

Parameters:
name - The name to assign to the newly created port.
Returns:
The new port.
Throws:
ptolemy.kernel.util.NameDuplicationException - If the entity already has a port with the specified name.

preinitialize

public void preinitialize()
                   throws ptolemy.kernel.util.IllegalActionException
Reset internal non-persistent variables and invoke the preinitialize() method of the CompositeActor.

Throws:
ptolemy.kernel.util.IllegalActionException - If the preinitialize() method of the CompositeActor throws a IllegalActionException.