ptolemy.matlab
Class Engine

java.lang.Object
  extended byptolemy.matlab.Engine

public class Engine
extends java.lang.Object

Provides a java API to the matlab environment. It uses an intermediary C++ language layer (ptmatlab) that converts between the java environment using the Java Native Interface and the matlab environment using the matlab engine API and associated mx-functions.

The intermediary layer is built as a DLL on Windows systems (ptmatlab.dll). This shared library is placed into the $PTII/bin directory (that should be in the user's path) when this package is built. Ptmatlab depends on matlab's engine API shared libraries (libeng and libmx) that should also be installed in the user's path (usually the case when matlab is installed and matlab's bin directory is added to the path).

The bulk of the work done by this class is the conversion between PtolemyII Tokens and matlab variables ("mxArrays").

get(long[] eng, String name) and get(long[], String, Engine.ConversionParameters) convert a matlab engine mxArray (ma) variable to a Ptolemy II Token. Recursion is used if ma is a struct or cell. The type of the Token returned is determined according to the following table:

Conversion from matlab to PtolemyII types (get())
Matlab TypePtolemyII Token
'double' Double, if mxArray dimension is 1x1 and Engine.ConversionParameters.getScalarMatrices is true, DoubleMatrix otherwise. Complex, if mxArray is mxCOMPLEX, 1x1, and Engine.ConversionParameters.getScalarMatrices is true, ComplexMatrix otherwise.
Note: If Engine.ConversionParameters.getIntMatrices is true and all matrix double values can be cast to integers without loss of precision then an IntToken or IntTokenMatrix is returned.
'struct' RecordToken, if mxArray dimension 1x1, ArrayToken of ArrayTokens of RecordTokens {{RecordToken,...}, {...}} ("two-dimensional" ArrayToken) otherwise.
'cell' ArrayToken of whatever Tokens the cell elements resolve to through recursion of _convertMxArrayToToken(). In the special case of a cell array of doubles, an {int} is always returned if all cell double values can be losslessly converted to integers. Note that PtolemyII is more restrictive here in that it requires all array elements to be of the same type (not all matlab cell variables may be converted to PtolemyII ArrayTokens).
'char' StringToken, if the mxArray is 1xn, ArrayToken of StringTokens otherwise.

put(long[] eng, String name, Token t) converts a PtolemyII Token to a matlab engine mxArray. Recursion is used if t is a RecordToken or ArrayToken. The type of mxArray created is determined according to the following table.

Conversion from PtolemyII to matlab types (put())
PtolemyII TokenMatlab type
ArrayToken 'cell', 1xn, elements are determined by recursing this method on ArrayToken elements.
RecordToken 'struct', 1x1, fields are determined by recursing this method on RecordToken fields
StringToken 'char', 1xn
ComplexMatrixToken 'double', mxCOMPLEX, nxm
MatrixToken 'double', mxREAL, nxm
ComplexToken 'double', mxCOMPLEX, 1x1
ScalarToken 'double', mxREAL, 1x1

Debug statements to stdout are enabled by calling setDebugging(byte) with a byte parameter > 0. 1 enables basic tracing, 2 includes traces from the dll as well.

evalString(long[] eng, String) send a string to the matlab engine for evaluation. open() and close(long[]) are used to open / close the connection to the matlab engine.

All callers share the same matlab engine and its workspace. Methods of Engine synchronize on the static semaphore to prevent overlapping calls to the same method from different threads. Use Engine. semaphore to synchronize across multiple method calls if needed.

Since:
Ptolemy II 2.0
Version:
$Id: Engine.java,v 1.31 2004/04/13 03:45:58 cxh Exp $
Author:
Zoltan Kemenczy and Sean Simmons, Research in Motion Limited.
Accepted Rating:
Red (cxh)
Proposed Rating:
Yellow (zkemenczy)

Nested Class Summary
static class Engine.ConversionParameters
          Data conversion parameters used by get(long[], String, Engine.ConversionParameters).
 
Field Summary
static java.lang.Integer semaphore
          Used for Synchronization
 
Constructor Summary
Engine()
          Construct an instance of the matlab engine interface.
 
Method Summary
 int close(long[] eng)
          Close a connection to a matlab engine.
 int evalString(long[] eng, java.lang.String evalStr)
          Send a string for evaluation to the matlab engine.
 Token get(long[] eng, java.lang.String name)
          Return a Token from the matlab engine using default Engine.ConversionParameters values.
 Token get(long[] eng, java.lang.String name, Engine.ConversionParameters par)
          Return a Token from the matlab engine using specified Engine.ConversionParameters values.
 StringToken getOutput(long[] eng)
          Get last matlab stdout.
 long[] open()
          Open a connection to the default matlab engine installed on this host with its output buffered.
 long[] open(boolean needOutput)
          Open a connection to the default matlab engine installed on this host with specified output buffering.
 long[] open(java.lang.String startCmd, boolean needOutput)
          Open a connection to a matlab engine.
 int put(long[] eng, java.lang.String name, Token t)
          Create a matlab variable using name and a Token.
 void setDebugging(byte d)
          Enable/disable debug statements to stdout.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

semaphore

public static java.lang.Integer semaphore
Used for Synchronization

Constructor Detail

Engine

public Engine()
Construct an instance of the matlab engine interface. The matlab engine is not activated at this time.

Ptmatlab.dll is loaded by the system library loader the first time this class is loaded.

See Also:
open()
Method Detail

setDebugging

public void setDebugging(byte d)
Enable/disable debug statements to stdout.

Parameters:
d - Non-zero to enable debug statements, zero to disable.

open

public long[] open()
            throws IllegalActionException
Open a connection to the default matlab engine installed on this host with its output buffered.

Throws:
IllegalActionException
See Also:
open(String, boolean)

open

public long[] open(boolean needOutput)
            throws IllegalActionException
Open a connection to the default matlab engine installed on this host with specified output buffering.

Parameters:
needOutput - selects whether the output should be buffered or not.
Throws:
IllegalActionException
See Also:
open(String, boolean)

open

public long[] open(java.lang.String startCmd,
                   boolean needOutput)
            throws IllegalActionException
Open a connection to a matlab engine.

For more information, see the matlab engine API reference engOpen()

Parameters:
startCmd - hostname or command to use to start the engine.
Returns:
long[2] retval engine handle; retval[0] is the real engine handle, retval[1] is a pointer to the engine output buffer; both should be preserved and passed to subsequent engine calls.
Throws:
IllegalActionException - If the matlab engine open is unsuccessful. This will typically occur if ptmatlab (.dll) cannot be located or if the matlab bin directory is not in the path.
See Also:
getOutput(long[])

close

public int close(long[] eng)
Close a connection to a matlab engine. This will also close the matlab engine if this instance was the last user of the matlab engine.

For more information, see matlab engine API reference engClose()


evalString

public int evalString(long[] eng,
                      java.lang.String evalStr)
               throws IllegalActionException
Send a string for evaluation to the matlab engine.

Parameters:
evalStr - string to evaluate.
Throws:
IllegalActionException - If the matlab engine is not opened.

get

public Token get(long[] eng,
                 java.lang.String name)
          throws IllegalActionException
Return a Token from the matlab engine using default Engine.ConversionParameters values.

Parameters:
name - Matlab variable name used to initialize the returned Token
Returns:
PtolemyII Token.
Throws:
IllegalActionException - If the matlab engine is not opened, or if the matlab variable was not found in the engine. In this case, the matlab engine's stdout is included in the exception message.
See Also:
Expression

get

public Token get(long[] eng,
                 java.lang.String name,
                 Engine.ConversionParameters par)
          throws IllegalActionException
Return a Token from the matlab engine using specified Engine.ConversionParameters values.

Parameters:
name - Matlab variable name used to initialize the returned Token
Returns:
PtolemyII Token.
Throws:
IllegalActionException - If the matlab engine is not opened, or if the matlab variable was not found in the engine. In this case, the matlab engine's stdout is included in the exception message.
See Also:
Expression

getOutput

public StringToken getOutput(long[] eng)
Get last matlab stdout.

Returns:
PtolemyII StringToken

put

public int put(long[] eng,
               java.lang.String name,
               Token t)
        throws IllegalActionException
Create a matlab variable using name and a Token.

Parameters:
name - matlab variable name.
t - Token to provide value.
Throws:
IllegalActionException
See Also:
Engine