ptolemy.domains.continuous.lib
Class LinearStateSpace

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.InstantiableNamedObj
          ptolemy.kernel.Entity
              ptolemy.kernel.ComponentEntity
                  ptolemy.kernel.CompositeEntity
                      ptolemy.actor.CompositeActor
                          ptolemy.actor.TypedCompositeActor
                              ptolemy.domains.continuous.lib.LinearStateSpace

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 LinearStateSpace
extends TypedCompositeActor

Linear state space model in the CT domain.

The State-Space model implements a system whose behavior is defined by:

 dx/dt = Ax + Bu
 y = Cx + Du
 x(0) = x0
 

where x is the state vector, u is the input vector, and y is the output vector. 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.
 

The actor accepts m inputs and generates r outputs through a multi-input port and a multi-output port. The widths of the ports must match the number of rows and columns in corresponding matrices, otherwise, an exception will be thrown.

This actor works like a higher-order function. It is opaque after construction or the change of parameters. Upon preinitialization, the actor will create a subsystem using integrators, adders, and scales. After that, the actor becomes transparent, and the director takes over the control of the actors contained by this actor.

This actor is based on the LinearStateSpace actor by Jie Liu.

Since:

Ptolemy II 8.0

Version:

$Id: LinearStateSpace.java 57046 2010-01-27 23:35:53Z cxh $

Author:

Jie Liu

See Also:

CTBaseIntegrator, Serialized Form

Accepted Rating:

Red (cxh)

Proposed Rating:

Red (liuj)

Nested Class Summary

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

CompositeEntity.ContainedObjectsIterator

Field Summary

private boolean	_opaque
private boolean	_requestInitialization
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	input Multi-input port.
TypedIOPort	output Multi-output port.
TypedIOPort	stateOutput State output multiport.

Fields inherited from class ptolemy.actor.CompositeActor

_actorFiringListeners, _causalityInterface, _initializables, _notifyingActorFiring, _publishedPorts, _publisherRelations, _stopRequested

Fields inherited from class ptolemy.kernel.CompositeEntity

_levelCrossingLinks

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

LinearStateSpace(CompositeEntity container, java.lang.String name)
Construct the composite actor with a name and a container.

LinearStateSpace(Workspace workspace)
Construct a LinearStateSpace in the specified workspace with no container and an empty string as a name.

Method Summary

private void	_checkParameters() Check the dimensions of all parameters and ports.
private void	_init() Initialize the class.
private void	_requestInitialization() Set this composite actor to opaque and request for reinitialization from the director if there is one.
void	attributeChanged(Attribute attribute) If the argument is A, B, C, D or initialState parameters, check that they are indeed matrices and vectors, and request for initialization from the director if there is one.
Director	getDirector() Return the executive director, regardless what isOpaque() returns.
boolean	isOpaque() Return the opaqueness of this composite actor.
boolean	postfire() Request the reinitialization.
void	preinitialize() Sanity check the parameters; if the parameters are legal create a continuous-time subsystem that implement the model, preinitialize all the actors in the subsystem, and set the opaqueness of this actor to true.
void	stopFire() Stop the current firing.
void	wrapup() Set the opaqueness back to true and call the wrapup() method of the super class.

Methods inherited from class ptolemy.actor.TypedCompositeActor

_addEntity, _addPort, _addRelation, _checkTypesFromTo, _typeConstraintsFromTo, newPort, newRelation, resolveTypes, typeConstraintList, typeConstraints

Methods inherited from class ptolemy.actor.CompositeActor

_actorFiring, _actorFiring, _finishedAddEntity, _getPublishedPort, _setDirector, addActorFiringListener, addInitializable, addPiggyback, clone, connectionsChanged, createReceivers, createSchedule, fire, getCausalityInterface, getExecutiveDirector, getManager, inferringWidths, inferWidths, initialize, inputPortList, isFireFunctional, isStrict, iterate, linkToPublishedPort, linkToPublishedPort, needsWidthInference, newInsideReceiver, newReceiver, notifyConnectivityChange, outputPortList, prefire, recordFiring, registerPublisherPort, removeActorFiringListener, removeInitializable, removePiggyback, requestChange, setContainer, setDirector, setManager, stop, terminate, unlinkToPublishedPort, unlinkToPublishedPort, unregisterPublisherPort

Methods inherited from class ptolemy.kernel.CompositeEntity

_adjustDeferrals, _deepOpaqueEntityList, _description, _exportMoMLContents, _recordDecoratedAttributes, _removeEntity, _removeRelation, _validateSettables, allAtomicEntityList, allCompositeEntityList, allowLevelCrossingConnect, classDefinitionList, connect, connect, containedObjectsIterator, deepEntityList, deepGetEntities, deepOpaqueEntityList, deepRelationSet, entityList, entityList, exportLinks, exportMoML, getAttribute, getEntities, getEntity, getPort, getRelation, getRelations, isAtomic, lazyAllAtomicEntityList, lazyAllCompositeEntityList, lazyClassDefinitionList, lazyDeepEntityList, lazyEntityList, lazyRelationList, numberOfEntities, numberOfRelations, numEntities, numRelations, relationList, removeAllEntities, removeAllRelations, setClassDefinition, statistics, uniqueName

Methods inherited from class ptolemy.kernel.ComponentEntity

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

Methods inherited from class ptolemy.kernel.Entity

_removePort, connectedPortList, connectedPorts, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts

Methods inherited from class ptolemy.kernel.InstantiableNamedObj

_setParent, 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, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeList, attributeList, attributeTypeChanged, clone, 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, 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, getExecutiveDirector, getManager, inputPortList, newReceiver, outputPortList

Methods inherited from interface ptolemy.actor.Executable

fire, isFireFunctional, isStrict, iterate, prefire, stop, terminate

Methods inherited from interface ptolemy.actor.Initializable

addInitializable, initialize, removeInitializable

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

input

public TypedIOPort input

Multi-input port.

output

public TypedIOPort output

Multi-output port.

stateOutput

public TypedIOPort stateOutput

State output multiport.

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 equal to the number of rows of the A matrix. The number of columns must equal to the width of the input port. The default value is [[1.0]].

C

public Parameter C

The C matrix in the state-space representation. The number of columns must equal to the number of columns of the A matrix. The number of rows must equal to the width of the output port. The default value is [[1.0]].

D

public Parameter D

The D matrix in the state-space representation. The number of columns must equal to the width of the input port. The number of rows must equal to the width of the output port. The default value is [[0.0]].

initialStates

public Parameter initialStates

The initial condition for the state variables. This must be a vector (double matrix with only one row) whose length equals to the number of state variables. The default value is [0.0].

_opaque

private boolean _opaque

_requestInitialization

private boolean _requestInitialization

Constructor Detail

LinearStateSpace

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

Construct the composite actor with a name and a container. This constructor creates the ports, parameters, and the icon.

Parameters:

container - The container.

name - The name.

Throws:

NameDuplicationException - If another entity already had this name.

IllegalActionException - If there was an internal problem.

LinearStateSpace

public LinearStateSpace(Workspace workspace)
                 throws IllegalActionException,
                        NameDuplicationException

Construct a LinearStateSpace 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.

Throws:

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

NameDuplicationException - If the container already contains an entity with the specified name.

Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

If the argument is A, B, C, D or initialState parameters, check that they are indeed matrices and vectors, and request for 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.

getDirector

public Director getDirector()

Return the executive director, regardless what isOpaque() returns. //FIXME: this is not what this method does!!!

Specified by:

getDirector in interface Actor

Overrides:

getDirector in class CompositeActor

Returns:

the executive director.

See Also:

CompositeActor.setDirector(Director)

isOpaque

public boolean isOpaque()

Return the opaqueness of this composite actor. This actor is opaque if it has not been preinitialized after creation or changes of parameters. Otherwise, it is not opaque.

Overrides:

isOpaque in class CompositeActor

Returns:

True if the entity is opaque.

See Also:

CompositeEntity

postfire

public boolean postfire()
                 throws IllegalActionException

Request the reinitialization.

Specified by:

postfire in interface Executable

Overrides:

postfire in class CompositeActor

Returns:

True if the super class returns true.

Throws:

IllegalActionException - If thrown by super class.

preinitialize

public void preinitialize()
                   throws IllegalActionException

Sanity check the parameters; if the parameters are legal create a continuous-time subsystem that implement the model, preinitialize all the actors in the subsystem, and set the opaqueness of this actor to true. This method needs the write access on the workspace.

Specified by:

preinitialize in interface Initializable

Overrides:

preinitialize in class CompositeActor

Throws:

IllegalActionException - If there is no CTDirector, or any contained actors throw it in its preinitialize() method.

stopFire

public void stopFire()

Stop the current firing. This method overrides the stopFire() method in TypedCompositeActor base class, so that it will not invoke the local director (since there is none). This method should not be called after initialization phase, i.e. when the actor is transparent.

Specified by:

stopFire in interface Executable

Overrides:

stopFire in class CompositeActor

wrapup

public void wrapup()
            throws IllegalActionException

Set the opaqueness back to true and call the wrapup() method of the super class.

Specified by:

wrapup in interface Initializable

Overrides:

wrapup in class CompositeActor

Throws:

IllegalActionException - If there is no director.

_checkParameters

private void _checkParameters()
                       throws IllegalActionException

Check the dimensions of all parameters and ports.

Throws:

IllegalActionException - If the dimensions are illegal.

_init

private void _init()
            throws IllegalActionException,
                   NameDuplicationException

Initialize the class.

Throws:

IllegalActionException

NameDuplicationException

_requestInitialization

private void _requestInitialization()

Set this composite actor to opaque and request for reinitialization from the director if there is one.