.. -- mode: rst; coding: utf-8; --

================= mlab

Mlab is a high-level python to Matlab® bridge that lets Matlab look like a normal python library.

This python library is based on the work of original mlabwrap project

http://mlabwrap.sourceforge.net/

and Dani Valevski (from Dana Pe'er's lab):

http://code.google.com/p/danapeerlab/source/browse/trunk/freecell/depends/common/python/matlabpipe.py

Primer

Quick installation::

pip install mlab

Start working with the library by picking a MATLAB release that you have locally installed::

from mlab.releases import latest_release as matlab from matlab import matlabroot

print matlabroot()

where latest_release is a MlabWrap instance, matlabroot is wrapper around MATLAB function. Please note that matlab module is dynamically created instance, which is in this case referencing latest_release object.

MATLAB installation discovery mechanism is implemented by mlab.releases module in such a way, that you have to specify the release version you want to use first, by importing it. Only then you can import from matlab module::

from mlab.releases import R2010b as matlab from matlab import matlabroot

Also see mlab.releases.get_available_releases().

Original README

NOTE Below is the original README from the mlabwrap project. Most of it still applies, but the underlying implementation is different (COM/Pipes replaced the use of the MATLAB Engine API). The code samples have been updated for use with this project.

.. contents::

Description

Mlabwrap is a high-level python to Matlab®_ bridge that lets Matlab look like a normal python library.

Thanks for your terrific work on this very-useful Python tool!

-- George A. Blaha, Senior Systems Engineer,
   Raytheon Integrated Defense Systems

mlab is a repackaging effort to make things up-to-date.

.. _Matlab®: http://www.mathworks.com

Thereis is a copy of mlabwrap v1.1-pre (http://mlabwrap.sourceforge.net/) patched as described here: http://sourceforge.net/mailarchive/message.php?msg_id=27312822

with a patch fixing the error::

mlabraw.cpp:225: error: invalid conversion from ‘const mwSize*’ to ‘const int*’

Also note that in Ubuntu you need to sudo apt-get install csh

For details see http://github.com/aweinstein/mlabwrap

News

2014-08-26 1.1.3 Applying patch to add support for Windows via COM. Credits to Sergey Matyunin, Amro@stackoverflow

2013-07-26 1.1.1 Repacking a library as mlab project. Including code for Windows (matlabraw.cpp is off for now).

2009-10-26 1.1 fixes an incorrect declaration in mlabraw.cpp that caused compilation problems for some users and incorporates a setup.py fix for windows suggested by Alan Brooks. More significantly there is a new spiffy logo!

2009-09-14 1.1-pre finally brings N-D array support, thanks to Vivek Rathod who joined the project! Also fixed a missing import for saveVarsInMat (thanks to Nicolas Pinto).

Since a few people have run into problems that appear to relate to compiling Matlab® C-extensions in general and aren't mlabwrap-specific, I should probably stress that in case of any problems that look C-related, verifying whether engdemo.c works is a great litmus test (see Troubleshooting_ ).

2009-03-23 1.0.1 is finally out. This is a minor release that fixes some annoying but mostly minor bugs in mlabwrap (it also slightly improves the indexing support for proxy-objects, but the exact semantics are still subject to change.)

installation is now easier, in particularly LD_LIBRARY_PATH no longer needs to be set and some quoting issues with the matlab call during installation have been addressed.
sparse Matlab® matrices are now handled correctly (mlab.sparse([0,0,0,0]) will now return a proxy for a sparse double matrix, rather than incorrectly treat at as plain double array and return junk or crash).
replaced the (optional) use of the outdated netcdf package for the unit-tests with homegrown matlab helper class.
several bugs squashed (length of mlabraw.eval'ed strings is checked, better error-messages etc.) and some small documentation improvements and quite a few code clean-ups.

Many thanks to Iain Murray at Toronto and Nicolas Pinto at MIT for letting themselves be roped into helping me test my stupidly broken release candidates.

License

mlab (and mlabwrap) is under MIT license, see LICENSE.txt. mlabraw is under a BSD-style license, see the mlabraw.cpp.

Download

http://github.com/ewiger/mlab

Installation

mlab should work with python>=2.7 (downto python 2.2, with minor coaxing) and either numpy_ (recommended) or Numeric (obsolete) installed and Matlab 6, 6.5, 7.x and 8.x under Linux, OS X® and Windows® (see OS X_) on 32- or 64-bit machines.

Linux ''''' If you're lucky (linux, Matlab binary in PATH)::

python setup.py install

(As usual, if you want to install just in your homedir add --prefix=$HOME; and make sure your PYTHONPATH is set accordingly.)

If things do go awry, see Troubleshooting_.

Windows '''''''

Assuming you have python 2.7.5 (e.g. C:\Python27) and setuptools ("easy_install.exe") installed and on your PATH.

Download and install numpy package. You can use packages provided by Christoph Gohlke: http://www.lfd.uci.edu/~gohlke/pythonlibs/ Also see official SciPy website for latest status, it might that::

easy_install.exe numpy

would do the trick.

You would also need The PyWin32 module by Mark Hammond::

easy_install.exe pywin32

also see Windows in Troubleshooting_.

Documentation

for lazy people

from mlab.releases import latest_release as matlab matlab.plot([1,2,3],'-o')

.. image:: ugly-plot.png :alt: ugly-plot
a slightly prettier example

from mlab.releases import latest_release as matlab from numpy import * xx = arange(-2pi, 2pi, 0.2) matlab.surf(subtract.outer(sin(xx),cos(xx)))

.. image:: surface-plot.png :alt: surface-plot
for a complete description: Just run pydoc mlab.
for people who like tutorials: see below

Tutorial ''''''''

[This is adapted from an email I wrote someone who asked me about mlabwrap. Compatibility Note: Since matlab is becoming increasingly less double-centric, the default conversion rules might change in post 1.0 mlabwrap; so whilst using mlab.plot([1,2,3]) rather than mlab.plot(array([1.,2.,3.])) is fine for interactive use as in the tutorial below, the latter is recommended for production code.]

Legend: [...] = omitted output

Let's say you want to do use Matlab® to calculate the singular value decomposition of a matrix. So first you import the mlab pseudo-module and numpy:

from mlab.releases import latest_release as matlab import numpy

Now you want to find out what the right function is, so you simply do:

matlab.lookfor('singular value') GSVD Generalized Singular Value Decompostion. SVD Singular value decomposition. [...]

Then you look up what svd actually does, just as you'd look up the docstring of a python function:

help(matlab.svd) mlab_command(*args, **kwargs) SVD Singular value decomposition. [U,S,V] = SVD(X) produces a diagonal matrix S, of the same dimension as X and with nonnegative diagonal elements in [...]

Then you try it out:

matlab.svd(array([[1,2], [1,3]])) array([[ 3.86432845], [ 0.25877718]])

Notice that we only got 'U' back -- that's because python hasn't got something like Matlab's multiple value return. Since Matlab functions can have completely different behavior depending on how many output parameters are requested, you have to specify explicitly if you want more than 1. So to get 'U' and also 'S' and 'V' you'd do:

U, S, V = matlab.svd([[1,2],[1,3]], nout=3)

The only other possible catch is that Matlab (to a good approximation) basically represents everything as a double matrix. So there are no scalars, or 'flat' vectors. They correspond to 1x1 and 1xN matrices respectively. So, when you pass a flat vector or a scalar to a mlab-function, it is autoconverted. Also, integer values are automatically converted to double floats. Here is an example:

matlab.abs(-1) array([ [ 1.]])

Strings also work as expected:

matlab.upper('abcde') 'ABCDE'

However, although matrices and strings should cover most needs and can be directly converted, Matlab functions can also return structs or indeed classes and other types that cannot be converted into python equivalents. However, rather than just giving up, mlabwrap just hides this fact from the user by using proxies: E.g. to create a netlab_ neural net with 2 input, 3 hidden and 1 output node:

net = matlab.mlp(2,3,1,'logistic')

Looking at net reveals that is a proxy:

net <MLabObjectProxy of matlab-class: 'struct'; internal name: 'PROXY_VAL0__'; has parent: no> type: 'mlp' nin: 3 nhidden: 3 nout: 3 nwts: 24 outfn: 'linear' w1: [3x3 double] b1: [0.0873 -0.0934 0.3629] w2: [3x3 double] b2: [-0.6681 0.3572 0.8118]

When net or other proxy objects a passed to mlab functions, they are automatically converted into the corresponding Matlab-objects. So to obtain a trained network on the 'xor'-problem, one can simply do:

net = matlab.mlptrain(net, [[1,1], [0,0], [1,0], [0,1]], [0,0,1,1], 1000)

And test with:

matlab.mlpfwd(net2, [[1,0]]) array([ [ 1.]]) matlab.mlpfwd(net2, [[1,1]]) array([ [ 7.53175454e-09]])

As previously mentioned, normally you shouldn't notice at all when you are working with proxy objects; they can even be pickled (!), although that is still somewhat experimental.

mlabwrap also offers proper error handling and exceptions! So trying to pass only one input to a net with 2 input nodes raises an Exception:

Mlab

Install / Use

README