Package ptolemy.matlab

Class 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[], 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$
    Author:
    Zoltan Kemenczy and Sean Simmons, Research in Motion Limited.
    Pt.AcceptedRating:
    Red (cxh)
    Pt.ProposedRating:
    Yellow (zkemenczy)

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.Object semaphore
      Used for synchronization.

    • Constructor Summary

      Constructors 
      Constructor Description
      Engine()
      Construct an instance of the matlab engine interface.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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 final java.lang.Object 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.
        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:
        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.
        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:
        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.
        needOutput - selects whether the output should be buffered or not.
        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()

        Parameters:
        eng - An array of longs with length 2. eng[0] is the real engine handle, eng[1] is a pointer to the engine output buffer.
        Returns:
        The value returned by calling engClose() in the Matlab interface.

      • evalString

        public int evalString​(long[] eng,
                      java.lang.String evalStr)
               throws IllegalActionException
        Send a string for evaluation to the matlab engine.
        Parameters:
        eng - An array of two longs; eng[0] is the real engine handle, eng[1] is a pointer to the engine output buffer.
        evalStr - string to evaluate.
        Returns:
        The value returned by the ptmatlabEngEvalString() native method.
        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:
        eng - An array of longs with length 2. eng[0] is the real engine handle, eng[1] is a pointer to the engine output buffer.
        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:
        eng - An array of longs with length 2. eng[0] is the real engine handle, eng[1] is a pointer to the engine output buffer.
        name - Matlab variable name used to initialize the returned Token
        par - The ConversionParameter to use.
        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.
        Parameters:
        eng - An array of longs with length 2. eng[0] is the real engine handle, eng[1] is a pointer to the engine output buffer.
        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:
        eng - An array of longs with length 2. eng[0] is the real engine handle, eng[1] is a pointer to the engine output buffer.
        name - matlab variable name.
        t - Token to provide value.
        Returns:
        The result of calling engPutArray() in the Matlab C library.
        Throws:
        IllegalActionException - If the engine is not opened.
        See Also:
        Engine