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:

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

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.

For this actor to work, Matlab must be installed on your local machine. In addition, your environment must be set properly. The $PTII/bin/vergil script does this for you, below are instructions for users, such as Eclipse users, who are not using $PTII/bin/vergil.

Add the Matlab shared libraries to your the library path. In the examples below $MATLAB should be the location of your Matlab installation. For example, if /usr/bin/matlab is a link:

 bash-3.2$ which matlab
 /usr/bin/matlab
 bash-3.2$ ls -l /usr/bin/matlab
 lrwxr-xr-x  1 root  wheel  42 Jan 15 20:57 /usr/bin/matlab -> /Applications/MATLAB_R2009b.app/bin/matlab
 bash-3.2$
 

Then $MATLAB would be /Applications/MATLAB_R2009b.app

32 Bit Mac (10.5?, Edit ~/.MacOSX/environment.plist)

export DYLD_LIBRARY_PATH=$MATLAB/bin/maci

64 Bit Mac (10.6?, Edit ~/.MacOSX/environment.plist)

export DYLD_LIBRARY_PATH=$MATLAB/bin/maci64

32 Bit Linux (Edit

export LD_LIBRARY_PATH=$MATLAB/bin/gnlx86

64 Bit Linux

export LD_LIBRARY_PATH=$MATLAB/bin/glnxa64

Windows (Start|My Computer|Properties|Advanced Environment Variables| Add the directory that contains matlab.exe to your path)

Be sure that the matlab binary is in your path

Since:

Ptolemy II 2.0

Version:

$Id: Expression.java 59167 2010-09-21 17:08:02Z cxh $

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/interfaces inherited from class ptolemy.kernel.Entity

Entity.ContainedObjectsIterator

Field Summary

private java.lang.String	_addPathCommand
private Engine.ConversionParameters	_dataParameters
private Variable	_iteration
private int	_iterationCount
private Token	_previousPath
(package private) long[]	engine
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.
private Engine	matlabEngine
TypedIOPort	output The output port.

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

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.Set<Inequality>	typeConstraints() 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, _fireAt, _fireAt, attributeTypeChanged, clone, newPort, typeConstraintList

Methods inherited from class ptolemy.actor.AtomicActor

_actorFiring, _actorFiring, addActorFiringListener, addInitializable, clone, connectionsChanged, createReceivers, declareDelayDependency, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, isFireFunctional, isStrict, iterate, newReceiver, outputPortList, pruneDependencies, recordFiring, removeActorFiringListener, removeDependency, removeInitializable, 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, _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, attributeChanged, 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, 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

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.

matlabEngine

private transient Engine matlabEngine

engine

long[] engine

_iteration

private Variable _iteration

_iterationCount

private int _iterationCount

_addPathCommand

private java.lang.String _addPathCommand

_previousPath

private Token _previousPath

_dataParameters

private transient Engine.ConversionParameters _dataParameters

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

typeConstraints

public java.util.Set<Inequality> typeConstraints()

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:

typeConstraints in interface TypedActor

Overrides:

typeConstraints 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 Initializable

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 Initializable

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 Initializable

Overrides:

wrapup in class AtomicActor

Throws:

IllegalActionException - Not thrown in this base class.