ptolemy.actor.lib
Class LinearDifferenceEquationSystem

java.lang.Object
  extended byptolemy.kernel.util.NamedObj
      extended byptolemy.kernel.InstantiableNamedObj
          extended byptolemy.kernel.Entity
              extended byptolemy.kernel.ComponentEntity
                  extended byptolemy.actor.AtomicActor
                      extended byptolemy.actor.TypedAtomicActor
                          extended byptolemy.actor.lib.Transformer
                              extended byptolemy.actor.lib.LinearDifferenceEquationSystem
All Implemented Interfaces:
ptolemy.actor.Actor, ptolemy.kernel.util.Changeable, java.lang.Cloneable, 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 LinearDifferenceEquationSystem
extends Transformer

Linear Difference Equation System.

The linear state-space model implements a system whose behavior is defined by:

   x(k+1) = Ax(k) + Bu(k)
   y(k) = Cx(k) + Du(k)
   x(0) = x0
   
where x is the state vector, u is the input vector, and y is the output vector. (Note that in Ptolemy II, vectors are double matrices with one column or one row.) The matrix coefficients must have the following characteristics:
   A must be an n-by-n matrix, where n is the number of states.
   B must be an n-by-m matrix, where m is the number of inputs.
   C must be an r-by-n matrix, where r is the number of outputs.
   D must be an r-by-m matrix.
   
For each firing, the actor accepts one input DoubleMatrixToken of dimension m x 1, and generates one output DoubleMatrixToken of dimension r x 1.

In addition to producing the output y through port output, the actor also produce the state values x through port state.

Since:
Ptolemy II 2.0
Version:
$Id: LinearDifferenceEquationSystem.java,v 1.21 2004/04/13 19:00:17 cxh Exp $
Author:
Jie Liu and Elaine Cheong
See Also:
Serialized Form
Accepted Rating:
Yellow (celaine)
Proposed Rating:
Yellow (celaine)

Nested Class Summary
 
Nested classes inherited from class ptolemy.kernel.Entity
ptolemy.kernel.Entity.ContainedObjectsIterator
 
Field Summary
 ptolemy.data.expr.Parameter A
          The A matrix in the state-space representation.
 ptolemy.data.expr.Parameter B
          The B matrix in the state-space representation.
 ptolemy.data.expr.Parameter C
          The C matrix in the state-space representation.
 ptolemy.data.expr.Parameter D
          The D matrix in the state-space representation.
 ptolemy.data.expr.Parameter initialStates
          The initial condition for the state variables.
 ptolemy.actor.TypedIOPort state
          Output port that produces DoubleMatrixToken of dimension r x 1 (see class comment).
 
Fields inherited from class ptolemy.actor.lib.Transformer
input, output
 
Fields inherited from class ptolemy.actor.AtomicActor
_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
LinearDifferenceEquationSystem(ptolemy.kernel.CompositeEntity container, java.lang.String name)
          Construct an actor with the given container and name.
 
Method Summary
 void attributeChanged(ptolemy.kernel.util.Attribute attribute)
          If the argument is A, B, C, D or initialStates parameters, check that they are indeed matrices and vectors, and request initialization from the director if there is one.
 void fire()
          Consume the input token, compute the system response, and produce outputs.
 boolean postfire()
          Update the internal state.
 boolean prefire()
          If the parameter initialStates has changed, then update the internal state of this actor to be the value of the initialStates parameter.
 void preinitialize()
          Check the dimension of all parameters.
 
Methods inherited from class ptolemy.actor.TypedAtomicActor
_addPort, attributeTypeChanged, clone, newPort, typeConstraintList
 
Methods inherited from class ptolemy.actor.AtomicActor
_createReceivers, clone, connectionsChanged, getDirector, getExecutiveDirector, getFunctionDependency, getManager, initialize, inputPortList, iterate, newReceiver, outputPortList, pruneDependencies, removeDependency, setContainer, stop, stopFire, terminate, wrapup
 
Methods inherited from class ptolemy.kernel.ComponentEntity
_adjustDeferrals, _checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, isAtomic, isOpaque, propagateExistence, setName
 
Methods inherited from class ptolemy.kernel.Entity
_description, _exportMoMLContents, _removePort, connectedPortList, connectedPorts, containedObjectsIterator, getAttribute, getPort, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts, setClassDefinition, uniqueName, validateSettables
 
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, 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, requestChange, 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, getFunctionDependency, getManager, inputPortList, newReceiver, outputPortList
 
Methods inherited from interface ptolemy.actor.Executable
initialize, iterate, 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

state

public ptolemy.actor.TypedIOPort state
Output port that produces DoubleMatrixToken of dimension r x 1 (see class comment).


A

public ptolemy.data.expr.Parameter A
The A matrix in the state-space representation. It must be a square matrix. The default value is [[1.0]].


B

public ptolemy.data.expr.Parameter B
The B matrix in the state-space representation. The number of rows must be equal to the number of rows of the A matrix. The number of columns must be equal to the number of rows in the input token. The default value is [[1.0]].


C

public ptolemy.data.expr.Parameter C
The C matrix in the state-space representation. The number of columns must be equal to the number of columns of the A matrix. The number of rows must be equal to the number of columns in the output token. The default value is [[0.0]].


D

public ptolemy.data.expr.Parameter D
The D matrix in the state-space representation. The number of columns must be equal to the number of rows in the input token (a DoubleMatrixToken of dimension m x 1. The number of rows must be equal to the number of columns in the output token (a DoubleMatrixToken of dimension r x 1. The default value is [[0.0]].


initialStates

public ptolemy.data.expr.Parameter initialStates
The initial condition for the state variables. This must be a column vector (double matrix with only one column) whose length is equal to the number of state variables. The default value is [0.0]. NOTE: Changes to this parameter will be * applied at the next time when fire() is called.

Constructor Detail

LinearDifferenceEquationSystem

public LinearDifferenceEquationSystem(ptolemy.kernel.CompositeEntity container,
                                      java.lang.String name)
                               throws ptolemy.kernel.util.IllegalActionException,
                                      ptolemy.kernel.util.NameDuplicationException
Construct an actor with the given container and name.

Parameters:
container - The container.
name - The name of this actor.
Throws:
ptolemy.kernel.util.IllegalActionException - If the actor cannot be contained by the proposed container.
ptolemy.kernel.util.NameDuplicationException - If the container already has an actor with this name.
Method Detail

attributeChanged

public void attributeChanged(ptolemy.kernel.util.Attribute attribute)
                      throws ptolemy.kernel.util.IllegalActionException
If the argument is A, B, C, D or initialStates parameters, check that they are indeed matrices and vectors, and request initialization from the director if there is one. Other sanity checks like the dimensions of the matrices will be done in the preinitialize() method.

Parameters:
attribute - The attribute that changed.
Throws:
ptolemy.kernel.util.IllegalActionException - If the numerator and the denominator matrix is not a row vector.

fire

public void fire()
          throws ptolemy.kernel.util.IllegalActionException
Consume the input token, compute the system response, and produce outputs. Notice that the state is updated in postfire. That is, if fire() is called multiple times before postfire() is called, this actor will use the same internal state to compute the outputs.

Throws:
ptolemy.kernel.util.IllegalActionException - If the get() or send() methods of the ports throw this exception.

postfire

public boolean postfire()
                 throws ptolemy.kernel.util.IllegalActionException
Update the internal state.

Throws:
ptolemy.kernel.util.IllegalActionException - If thrown by the super class.

prefire

public boolean prefire()
                throws ptolemy.kernel.util.IllegalActionException
If the parameter initialStates has changed, then update the internal state of this actor to be the value of the initialStates parameter.

Throws:
ptolemy.kernel.util.IllegalActionException - If initialStates parameter is invalid, or if the base class throws it.

preinitialize

public void preinitialize()
                   throws ptolemy.kernel.util.IllegalActionException
Check the dimension of all parameters. If the system needs multiple inputs, then set the type of the input port to be DoubleMatrix; otherwise set the type to Double. Similarly, for the output ports output and state, if the system needs multiple outputs, then set the type of the port to be DoubleMatrix; otherwise set the type to Double.

Throws:
ptolemy.kernel.util.IllegalActionException - If the dimensions do not match.