Functions

open([startcmd])

This function starts a MATLAB engine session and returns a handle that is used to identify the session to all other PyMat functions. The handle is of integer type.

On the Win32 platform, the optional parameter startcmd is always ignored. On UNIX platforms, it indicates the method of starting MATLAB. Quoting from the documentation for the engOpen function from the MATLAB API reference manual:

On UNIX systems, if startcmd is NULL or the empty string, engOpen starts MATLAB on the current host using the command matlab. If startcmd is a host-name, engOpen starts MATLAB on the designated host by embedding the specified hostname string into the larger string:

"rsh hostname \"/bin/csh -c 'setenv DISPLAY hostname:0; matlab'\""

If startcmd is any other string (has white space in it, or nonalphanumeric characters), the string is executed literally to start MATLAB.

On UNIX systems, engOpen performs the following steps:

1. Creates two pipes.
2. Forks a new process and sets up the pipes to pass stdin and stdout from MATLAB (parent) to two file descriptors in the engine program (child).
3. Executes a command to run MATLAB (rsh for remote execution).

Under Windows on a PC, engOpen opens an ActiveX channel to MATLAB. This starts the MATLAB that was registered during installation. If you did not register during installation, on the command line you can enter the command:

matlab /regserver

close(handle)

This function closes the MATLAB session represented by handle.

eval(handle, string)

This function evaluates the given string in the MATLAB workspace. Essentially, it is as if you had typed the string directly in MATLAB's command window.

Note that this function always succeeds without any exceptions unless the handle is invalid, even if the evaluation failed in the MATLAB workspace!. You are responsible for verifying successful execution of your code.

get(handle, name)

This function retrieves a matrix from MATLAB's workspace and returns a NumPy array with the same shape and contents. The name parameter specifies the name of the array in MATLAB's workspace.

Currently, only one-dimensional and two-dimensional floating-point arrays (real or complex) are supported. Structures, cell arrays, multi-dimensional arrays, etc. are not yet supported. On UNIX systems, this function can also be used to retrieve character strings, in which case a Python string object is returned. This functionality is not supported on Win32 (due to MATLAB restrictions).

put(handle, name, data)

This function places a Python object into MATLAB's workspace under the given name. The data parameter can be one of three things:

1. A NumPy array -- in this case, an array of the same shape and contents will be placed into the MATLAB workspace. The MATLAB array will be in double-precision format (real or complex), converting from the NumPy array type as necessary. Only one-dimensional or two-dimensional NumPy arrays are supported.
2. A Python list or tuple containing numeric values. In this case, a NumPy object is created from the list or tuple (as if you were using NumPy's array() function) and that object is instantiated in MATLAB's workspace.
3. A Python string object. In this case, a MATLAB character array will be instantiated with the contents of the string.

Limitations

The following limitations apply to the current version of PyMat:

1. Only 1-D and 2-D double-precision (real or complex) MATLAB arrays are supported (and single character strings). Matrices of higher dimension, structure arrays, cell arrays, etc. are not yet supported.
2. The Win32 platform does not support retrieving character strings from the MATLAB workspace.

Examples

Here is a simple example that computes the Discrete Cosine Transform of a short NumPy array using MATLAB's dct function:

>>> import pymat
>>> from Numeric import *
>>> x = array([1, 2, 3, 4, 5, 6])
>>> H = pymat.open()
>>> pymat.put(H, 'x', x)
>>> pymat.eval(H, 'y = dct(x)')
>>> print pymat.get(H, 'y')
[  8.57321410e+00  -4.16256180e+00  -1.55403172e-15  -4.08248290e-01
       -1.88808530e-15  -8.00788912e-02]
>>> pymat.close(H)

Installation

1. Win32

   Simply place the pymat.pyd file somewhere on your Python search path. Also ensure that MATLAB's BIN directory is somewhere on your DOS path, or else that you have copied MATLAB's LIBENG.DLL and LIBMX.DLL files somewhere on this path.

2. Unix

   Add the pymat.cpp file to your Modules source subdirectory. You may need to rename pymat.cpp to pymat.cc so that C++ compilers will recognize the extension.

   You will need to add a line to your Modules/Setup file to indicate the presence of this new module. You will need to specify -I switches on this line to tell the compiler where to look for MATLAB's engine.h include file (usually in the extern/include subdirectory of the MATLAB root installation directory) and NumPy's arrayobject.h include file. You will also need the -L switch to indicate the location of MATLAB's shared libraries, and -l switches to include those libraries. For example, my line in the Modules/Setup file looks like this:

   pymat pymat.cc -I$(prefix)/include -I$(matlab)/extern/include
      -I$(numpy)/Include -L$(matlab)/extern/lib/lnx86 -leng -lmx -lmat -lmi -lut
   

   When recompiling Python you may need to manually specify a C++ compiler. For example, I found that I had to do the following:

   make CCC=g++
   

   Finally, you need to set an environment variable telling MATLAB where it can find its shared libraries. On most systems, this variable is LD_LIBRARY_PATH. On HP700 systems this variable is SHLIB_PATH. On IBM RS/6000 systems this variable is LIBPATH.

Copyright & Disclaimer

To Do

1. Add multidimensional and non-double-precision array support. This will be of no benefit to Win32 users since the MATLAB engine interface only supports MATLAB V4 data types (double-precision floating point 2D arrays and strings).
2. Add support for structures and cell matrices?
3. The pyplot module could be the beginning of a true plotting module using MATLAB as the back end.

History

Version 1.0 -- December 26, 1998

• Initial release