# PyMat 1.0.4

PyMat is an interface between NumPy and a MATLAB engine session.

- LICENSE TYPE:
- GPL (GNU General Public License)
- USER RATING:
- DEVELOPED BY:
**Andrew Sterian**- HOMEPAGE:
- claymore.engineer.gvsu.edu
- CATEGORY:
- ROOT \ Science and Engineering \ Mathematics

PyMat is an interface between NumPy and a MATLAB engine session. PyMat software can be used to support NumPy's functionality with the features of MATLAB. An example module is included that presents a very simple interface to MATLAB's plotting functions. This allows you to, for example, plot NumPy arrays in a MATLAB plot window.

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).

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:

Creates two pipes.

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).

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:

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.

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.

A Python string object. In this case, a MATLAB character array will be instantiated with the contents of the string.

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)

· Python 2.2

· NumPy

· MATLAB V5

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. Also note that Matlab version 6.1 seems to no longer have the "libmi.so" library so you should remove "-lmi" from the compilation options.

· 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.

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).

**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:

Creates two pipes.

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).

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:

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.

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.

A Python string object. In this case, a MATLAB character array will be instantiated with the contents of the string.

**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)

**Requirements:**· Python 2.2

· NumPy

· MATLAB V5

**Installation:**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. Also note that Matlab version 6.1 seems to no longer have the "libmi.so" library so you should remove "-lmi" from the compilation options.

**Limitations:**· 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.

Last updated on November 22nd, 2007

#### Add your review!

SUBMIT