ptolemy.actor.lib
Class LinearDifferenceEquationSystem

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.InstantiableNamedObj
          ptolemy.kernel.Entity
              ptolemy.kernel.ComponentEntity
                  ptolemy.actor.AtomicActor
                      ptolemy.actor.TypedAtomicActor
                          ptolemy.actor.lib.Transformer
                              ptolemy.actor.lib.LinearDifferenceEquationSystem

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Actor, Executable, FiringsRecordable, Initializable, TypedActor, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

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 57040 2010-01-27 20:52:32Z cxh $

Author:

Jie Liu and Elaine Cheong

See Also:

Serialized Form

Accepted Rating:

Yellow (celaine)

Proposed Rating:

Yellow (celaine)

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.kernel.Entity

Entity.ContainedObjectsIterator

Field Summary

private boolean	_initialStateChanged
private boolean	_singleOutput
private boolean	_singleState
private Token	_x
private Token	_xPrime
Parameter	A The A matrix in the state-space representation.
Parameter	B The B matrix in the state-space representation.
Parameter	C The C matrix in the state-space representation.
Parameter	D The D matrix in the state-space representation.
Parameter	initialStates The initial condition for the state variables.
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

_actorFiringListeners, _initializables, _notifyingActorFiring, _stopRequested

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

LinearDifferenceEquationSystem(CompositeEntity container, java.lang.String name)
Construct an actor with the given container and name.

Method Summary

void	attributeChanged(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, _fireAt, _fireAt, attributeTypeChanged, clone, newPort, typeConstraintList, typeConstraints

Methods inherited from class ptolemy.actor.AtomicActor

_actorFiring, _actorFiring, addActorFiringListener, addInitializable, clone, connectionsChanged, createReceivers, declareDelayDependency, getCausalityInterface, getDirector, getExecutiveDirector, getManager, initialize, inputPortList, isFireFunctional, isStrict, iterate, newReceiver, outputPortList, pruneDependencies, recordFiring, removeActorFiringListener, removeDependency, removeInitializable, setContainer, stop, stopFire, terminate, wrapup

Methods inherited from class ptolemy.kernel.ComponentEntity

_adjustDeferrals, _checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, isAtomic, isOpaque, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, propagateExistence, setName

Methods inherited from class ptolemy.kernel.Entity

_description, _exportMoMLContents, _removePort, _validateSettables, connectedPortList, connectedPorts, containedObjectsIterator, getAttribute, getPort, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts, setClassDefinition, uniqueName

Methods inherited from class ptolemy.kernel.InstantiableNamedObj

_setParent, exportMoML, getChildren, getElementName, getParent, getPrototypeList, isClassDefinition, isWithinClassDefinition

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _recordDecoratedAttributes, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeList, attributeList, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getFullName, getModelErrorHandler, getName, getName, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, validateSettables, workspace

Methods inherited from class java.lang.Object

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

Methods inherited from interface ptolemy.actor.Actor

createReceivers, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, newReceiver, outputPortList

Methods inherited from interface ptolemy.actor.Executable

isFireFunctional, isStrict, iterate, stop, stopFire, terminate

Methods inherited from interface ptolemy.actor.Initializable

addInitializable, initialize, removeInitializable, wrapup

Methods inherited from interface ptolemy.kernel.util.Nameable

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

Methods inherited from interface ptolemy.kernel.util.Derivable

getDerivedLevel, getDerivedList, propagateValue

Field Detail

state

public TypedIOPort state

Output port that produces DoubleMatrixToken of dimension r x 1 (see class comment).

A

public Parameter A

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

B

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

_x

private Token _x

_xPrime

private Token _xPrime

_initialStateChanged

private boolean _initialStateChanged

_singleOutput

private boolean _singleOutput

_singleState

private boolean _singleState

Constructor Detail

LinearDifferenceEquationSystem

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

Construct an actor with the given container and name.

Parameters:

container - The container.

name - The name of this actor.

Throws:

IllegalActionException - If the actor cannot be contained by the proposed container.

NameDuplicationException - If the container already has an actor with this name.

Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws 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.

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If the numerator and the denominator matrix is not a row vector.

fire

public void fire()
          throws 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.

Specified by:

fire in interface Executable

Overrides:

fire in class AtomicActor

Throws:

IllegalActionException - If the get() or send() methods of the ports throw this exception.

postfire

public boolean postfire()
                 throws IllegalActionException

Update the internal state.

Specified by:

postfire in interface Executable

Overrides:

postfire in class AtomicActor

Returns:

True if execution can continue into the next iteration.

Throws:

IllegalActionException - If thrown by the super class.

prefire

public boolean prefire()
                throws IllegalActionException

If the parameter initialStates has changed, then update the internal state of this actor to be the value of the initialStates parameter.

Specified by:

prefire in interface Executable

Overrides:

prefire in class AtomicActor

Returns:

True if this actor is ready for firing, false otherwise.

Throws:

IllegalActionException - If initialStates parameter is invalid, or if the base class throws it.

preinitialize

public void preinitialize()
                   throws 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.

Specified by:

preinitialize in interface Initializable

Overrides:

preinitialize in class AtomicActor

Throws:

IllegalActionException - If the dimensions do not match.