PyMat - An interface between Python and MATLAB

Introduction

NumPy is a set of numerical extensions for Python that introduces a multidimensional array type and a rich set of matrix operations and mathematical functions. Users who have MATLAB 5 installed, however, may wish to take advantage of some of MATLAB's additional functions, including the plotting interface. The PyMat module acts as an interface between NumPy arrays in Python and a MATLAB engine session, allowing arrays to be passed back and forth and arbitrary commands to be executed in the MATLAB workspace.

PyMat is usable on both UNIX and Win32 platforms, although there are some slight differences between the two (mainly due to MATLAB's limitations).

You can download the latest version of PyMat from:

http://claymore.engineer.gvsu.edu/~steriana/Python

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.

   Note that some makefiles are included in the PyMat distribution that may simplify this process.

Copyright & Disclaimer

Copyright © 1998,1999 Andrew Sterian. All Rights Reserved. mailto: steriana@gvsu.edu

Copyright © 1998,1999 THE REGENTS OF THE UNIVERSITY OF MICHIGAN. ALL RIGHTS RESERVED

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notices appear in all copies and that both these copyright notices and this permission notice appear in supporting documentation, and that the name of The University of Michigan not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission.

THIS SOFTWARE IS PROVIDED AS IS, WITHOUT REPRESENTATION AS TO ITS FITNESS FOR ANY PURPOSE, AND WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE REGENTS OF THE UNIVERSITY OF MICHIGAN SHALL NOT BE LIABLE FOR ANY DAMAGES, INCLUDING SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, WITH RESPECT TO ANY CLAIM ARISING OUT OF OR IN CONNECTION WITH THE USE OF THE SOFTWARE, EVEN IF IT HAS BEEN OR IS HEREAFTER ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

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.02 -- July 9, 1999

• Added makefile.sol2 file for compilation on Solaris 2. Thanks to Jeffrey Chang for this contribution.
• Added more functionality to the pyplot.py file.

Version 1.01 -- March 2, 1999

• Added pymat-test.py as a basic test.
• Added makefile.libc5 file to aid compilation on Linux with glibc (since MATLAB's shared libraries were compiled with libc5). Thanks to Les Schaffer for both of the above contributions.

Version 1.0 -- December 26, 1998

• Initial release