ptolemy.matlab
Class Expression

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.InstantiableNamedObj
          ptolemy.kernel.Entity
              ptolemy.kernel.ComponentEntity
                  ptolemy.actor.AtomicActor
                      ptolemy.actor.TypedAtomicActor
                          ptolemy.matlab.Expression

All Implemented Interfaces:

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

public class Expression

extends TypedAtomicActor

On each firing send an expression for evaluation to a matlab Engine. The expression is any valid matlab expression, e.g.:

   [out1, out2, ... ] = SomeMatlabFunctionOrExpression( in1, in2, ... );...
   

The expression may include references to the input port names, current time (time), and a count of the firing (iteration). This is similar to Expression. To refer to parameters in scope, use $name or ${name} within the expression.

The matlab engine is opened (started) during prefire() by the first matlab Expression actor. Subsequent open()s simply increment a use count.

At the start of fire(), clear variables;clear globals commands are sent to matlab to clear its workspace. This helps detect errors where the matlab expression refers to a matlab variable not initialized from the input ports of this actor instance.

After the evaluation of the matlab expression is complete, the fire() method iterates through names of output ports and converts matlab variables with corresponding names to Tokens that are sent to the corresponding output ports. Incorrect expressions are usually first detected at this point by not finding the expected variables. If an output port variable is not found in the matlab Engine, an exception is thrown. The exception description string contains the last stdout of the matlab engine that usually describes the error.

The get1x1asScalars and getIntegerMatrices control data conversion (see Engine and Engine.ConversionParameters).

A Parameter named packageDirectories may be added to this actor to augment the search path of the matlab engine during the firing of this actor. The value of this parameter should evaluate to a StringToken, e.g.:

   "path1, path2, ..."
   

containing a comma-separated list of paths to be prepended to the matlab engine search path before expression is evaluated. The list may contain paths relative to the directory in which ptolemy was started, or any directory listed in the current classpath (in that order, first match wins). See UtilityFunctions.findFile(String). After evaluation, the previous search path is restored.

A Parameter named _debugging may be used to turn on debug print statements to stdout from Engine and the ptmatlab JNI. An IntToken with a value of 1 turns on Engine debug statements, a value of 2 adds ptmatlab debug statements as well. A value of 0 or the absence of the _debugging parameter yields normal operation.

Since:

Ptolemy II 2.0

Version:

$Id: Expression.java,v 1.50 2005/04/29 20:05:49 cxh Exp $

Author:

Zoltan Kemenczy and Sean Simmons, Research in Motion Limited

See Also:

Serialized Form

Accepted Rating:

Red (cxh)

Proposed Rating:

Yellow (zkemenczy)

Nested Class Summary

Nested classes inherited from class ptolemy.kernel.Entity

Entity.ContainedObjectsIterator

Field Summary

StringParameter	expression The parameter that is evaluated to produce the output.
Parameter	get1x1asScalars If true (checked), 1x1 matrix results are converted to ScalarTokens instead of a 1x1 MatrixToken, default is true.
Parameter	getIntegerMatrices If true, all double-valued matrix results are checked to see if all elements represent integers, and if so, an IntMatrixToken is returned, default is false for performance reasons.
TypedIOPort	output The output port.

Fields inherited from class ptolemy.actor.AtomicActor

_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

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

Method Summary

void	fire() Evaluate the expression and send its result to the output.
void	initialize() Initialize the iteration count to 1.
boolean	postfire() Increment the iteration count.
boolean	prefire() Return true if all input ports have at least one token.
void	preinitialize() Open a matlab engine.
java.util.List	typeConstraintList() Must specify port types using moml (TypeAttribute) - the default TypedAtomicActor type constraints do not apply in this case, since the input type may be totally unrelated to the output type and cannot be inferred; return an empty list.
void	wrapup() Close matlab engine if it was open.

Methods inherited from class ptolemy.actor.TypedAtomicActor

_addPort, attributeTypeChanged, clone, newPort

Methods inherited from class ptolemy.actor.AtomicActor

_createReceivers, clone, connectionsChanged, getDirector, getExecutiveDirector, getFunctionDependency, getManager, inputPortList, iterate, newReceiver, outputPortList, pruneDependencies, removeDependency, setContainer, stop, stopFire, terminate

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, 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, attributeChanged, 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, setNormalDebugging, setPersistent, setSource, setVerboseDebugging, sortContainedObjects, 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

iterate, stop, stopFire, terminate

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getContainer, getFullName, getName, getName, setName

Methods inherited from interface ptolemy.kernel.util.Derivable

getDerivedLevel, getDerivedList, propagateValue

Field Detail

output

public TypedIOPort output

The output port.

expression

public StringParameter expression

The parameter that is evaluated to produce the output. Typically, this parameter evaluates an expression involving the inputs. To refer to parameters in scope within the expression, use $name or ${name}, where "name" is the name of the parameter.

get1x1asScalars

public Parameter get1x1asScalars

If true (checked), 1x1 matrix results are converted to ScalarTokens instead of a 1x1 MatrixToken, default is true.

getIntegerMatrices

public Parameter getIntegerMatrices

If true, all double-valued matrix results are checked to see if all elements represent integers, and if so, an IntMatrixToken is returned, default is false for performance reasons.

Constructor Detail

Expression

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

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

typeConstraintList

public java.util.List typeConstraintList()

Must specify port types using moml (TypeAttribute) - the default TypedAtomicActor type constraints do not apply in this case, since the input type may be totally unrelated to the output type and cannot be inferred; return an empty list.

Specified by:

typeConstraintList in interface TypedActor

Overrides:

typeConstraintList in class TypedAtomicActor

Returns:

A list of instances of Inequality.

See Also:

Inequality

preinitialize

public void preinitialize()
                   throws IllegalActionException

Open a matlab engine.

Specified by:

preinitialize in interface Executable

Overrides:

preinitialize in class AtomicActor

Throws:

IllegalActionException - If matlab engine not found.

initialize

public void initialize()
                throws IllegalActionException

Initialize the iteration count to 1.

Specified by:

initialize in interface Executable

Overrides:

initialize in class AtomicActor

Throws:

IllegalActionException - If the parent class throws it.

prefire

public boolean prefire()
                throws IllegalActionException

Return true if all input ports have at least one token.

Specified by:

prefire in interface Executable

Overrides:

prefire in class AtomicActor

Returns:

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

Throws:

IllegalActionException - Not thrown in this base class.

fire

public void fire()
          throws IllegalActionException

Evaluate the expression and send its result to the output.

Specified by:

fire in interface Executable

Overrides:

fire in class AtomicActor

Throws:

IllegalActionException - If the evaluation of the expression triggers it, or the evaluation yields a null result, or the evaluation yields an incompatible type, or if there is no director.

postfire

public boolean postfire()
                 throws IllegalActionException

Increment the iteration count.

Specified by:

postfire in interface Executable

Overrides:

postfire in class AtomicActor

Returns:

True if execution can continue into the next iteration.

Throws:

IllegalActionException - If the superclass throws it.

wrapup

public void wrapup()
            throws IllegalActionException

Close matlab engine if it was open.

Specified by:

wrapup in interface Executable

Overrides:

wrapup in class AtomicActor

Throws:

IllegalActionException - Not thrown in this base class.