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").
{@link #get(long[] eng,String name)} and{@link ptolemy.matlab.Engine#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:
Matlab Type | PtolemyII Token |
---|---|
'double' | Double, if mxArray dimension is 1x1 and {@link Engine.ConversionParameters#getScalarMatrices} is true,DoubleMatrix otherwise. Complex, if mxArray is mxCOMPLEX, 1x1, and {@link Engine.ConversionParameters#getScalarMatrices} is true,ComplexMatrix otherwise. Note: If {@link Engine.ConversionParameters#getIntMatrices} is true andall 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. |
{@link #put(long[] eng,String name,Token t)} converts a PtolemyIIToken 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.
PtolemyII Token | Matlab 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 {@link #setDebugging} with a byte parameter > 0. 1 enables basic tracing,2 includes traces from the dll as well.
{@link #evalString(long[] eng, String)} send a string to the matlabengine for evaluation. {@link #open} and {@link #close} are used to open / close theconnection to the matlab engine.
All callers share the same matlab engine and its workspace. Methods of Engine synchronize on the static {@link #semaphore} toprevent overlapping calls to the same method from different threads. Use Engine. {@link #semaphore} to synchronize across multiple methodcalls if needed.
@author Zoltan Kemenczy and Sean Simmons, Research in Motion Limited. @version $Id: Engine.java,v 1.45 2007/12/06 18:23:36 cxh Exp $ @since Ptolemy II 2.0 @Pt.ProposedRating Yellow (zkemenczy) @Pt.AcceptedRating Red (cxh)
|
|