##############################################################################

################## mlabwrap: transparently wraps matlab(tm) ##################

##############################################################################

##

## o author: Alexander Schmolck <a.schmolck@gmx.net>

## o created: 2002-05-29 21:51:59+00:40

## o version: see `__version__`

## o keywords: matlab wrapper

## o license: MIT

## o FIXME:

## - it seems proxies can somehow still 'disappear', maybe in connection

## with exceptions in the matlab workspace?

## - add test that defunct proxy-values are culled from matlab workspace

## (for some reason ipython seems to keep them alive somehwere, even after

## a zaphist, should find out what causes that!)

## - add tests for exception handling!

## - the proxy getitem/setitem only works quite properly for 1D arrays

## (matlab's moronic syntax also means that 'foo(bar)(watz)' is not the

## same as 'tmp = foo(bar); tmp(watz)' -- indeed chances are the former

## will fail (not, apparently however with 'foo{bar}{watz}' (blech)). This

## would make it quite hard to the proxy thing 'properly' for nested

## proxies, so things may break down for complicated cases but can be

## easily fixed manually e.g.: ``mlab._set('tmp', foo(bar));

## mlab._get('tmp',remove=True)[watz]``

## - Guess there should be some in principle avoidable problems with

## assignments to sub-proxies (in addition to the more fundamental,

## unavoidable problem that ``proxy[index].part = foo`` can't work as

## expected if ``proxy[index]`` is a marshallable value that doesn't need

## to be proxied itself; see below for workaround).

## o XXX:

## - better support of string 'arrays'

## - multi-dimensional arrays are unsupported

## - treatment of lists, tuples and arrays with non-numerical values (these

## should presumably be wrapped into wrapper classes MlabCell etc.)

## - should test classes and further improve struct support?

## - should we transform 1D vectors into row vectors when handing them to

## matlab?

## - what should be flattend? Should there be a scalarization opition?

## - ``autosync_dirs`` is a bit of a hack (and maybe``handle_out``, too)...

## - is ``global mlab`` in unpickling of proxies OK?

## - hasattr fun for proxies (__deepcopy__ etc.)

## - check pickling

## o TODO:

## - delattr

## - better error reporting: test for number of input args etc.

## - add cloning of proxies.

## - pickling for nested proxies (and session management for pickling)

## - more tests

## o !!!:

## - matlab complex arrays are intelligently of type 'double'

## - ``class('func')`` but ``class(var)``

"""

mlabwrap

========

This module implements a powerful and simple to use wrapper that makes using

matlab(tm) from python almost completely transparent. To use simply do:

>>> from mlabwrap import mlab

and then just use whatever matlab command you like as follows:

>>> mlab.plot(range(10), 'ro:')

You can do more than just plotting:

>>> mlab.sort([3,1,2])

array([[ 1., 2., 3.]])

N.B.: The result here is a 1x3 matrix (and not a flat lenght 3 array) of type

double (and not int), as matlab built around matrices of type double (see

``MlabWrap._flatten_row_vecs``).

Matlab(tm)ab, unlike python has multiple value returns. To emulate calls like

``[a,b] = sort([3,2,1])`` just do:

>>> mlab.sort([3,1,2], nout=2)

(array([[ 1., 2., 3.]]), array([[ 2., 3., 1.]]))

For names that are reserved in python (like print) do:

>>> mlab.print_()

You can look at the documentation of a matlab function just by using help,

as usual:

>>> help(mlab.sort)

In almost all cases that should be enough -- if you need to do trickier

things, then get raw with ``mlab._do``, or build your child class that

handles what you want.

Fine points and limitations

---------------------------

- Only 2D matrices are directly supported as return values of matlab

functions (arbitrary matlab classes are supported via proxy objects --

in most cases this shouldn't make much of a difference (as these proxy

objects can be even pickled) -- still this functionality is yet

experimental).

One potential pitfall with structs (which are currently proxied) is that

setting indices of subarrays ``struct.part[index] = value`` might seem

to have no effect (since ``part`` can be directly represented as a

python array which will be modified without an effect on the proxy

``struct``'s contents); in that case::

some_array[index] = value; struct.part = some_array``

will have the desired effect.

- Matlab doesn't know scalars, or 1D arrays. Consequently all functions

that one might expect to return a scalar or 1D array will return a 1x1

array instead. Also, because matlab(tm) is built around the 'double'

matrix type (which also includes complex matrices), single floats and

integer types will be cast to double. Note that row and column vectors

can be autoconverted automatically to 1D arrays if that is desired (see

``_flatten_row_vecs``).

- for matlab(tm) function names like ``print`` that are reserved words in

python, so you have to add a trailing underscore (e.g. ``mlab.print_``).

- sometimes you will have to specify the number of return arguments of a

function, e.g. ``a,b,c = mlab.foo(nout=3)``. MlabWrap will normally try to

figure out for you whether the function you call returns 0 or more values

(in which case by default only the first value is returned!). For builtins

this might fail (since unfortunately there seems to be no foolproof way to

find out in matlab), but you can always lend a helping hand::

mlab.foo = mlab._make_mlab_command('foo', nout=3, doc=mlab.help('foo'))

Now ``mlab.foo()`` will by default always return 3 values, but you can still

get only one by doing ``mlab.foo(nout=1)``

- by default the working directory of matlab(tm) is kept in synch with that of

python to avoid unpleasant surprises. In case this behavior does instaed

cause you unpleasant surprises, you can turn it off with::

mlab._autosync_dirs = False

- you can customize how matlab is called by setting the environment variable

``MLABRAW_CMD_STR`` (e.g. to add useful opitons like '-nojvm'). For the

rather convoluted semantics see

<http://www.mathworks.com/access/helpdesk/help/techdoc/apiref/engopen.html>.

- if you don't want to use numpy arrays, but something else that's fine

too::

>>> import matrix from numpy.core.defmatrix

>>> mlab._array_cast = matrix

>>> mlab.sqrt([[4.], [1.], [0.]])

matrix([[ 2.],

[ 1.],

[ 0.]])

Credits

-------

This is really a wrapper around a wrapper (mlabraw) which in turn is a

modified and bugfixed version of Andrew Sterian's pymat

(http://claymore.engineer.gvsu.edu/~steriana/Python/pymat.html), so thanks go

to him for releasing his package as open source.

See the docu of ``MlabWrap`` and ``MatlabObjectProxy`` for more information.

"""

__docformat__ = "restructuredtext en"

__version__ = '1.1'

__author__ = "Alexander Schmolck <a.schmolck@gmx.net>"

import warnings

from pickle import PickleError

import operator

import os, sys, re

import weakref

import atexit

try:

import numpy

ndarray = numpy.ndarray

except ImportError:

import Numeric

ndarray = Numeric.ArrayType

from tempfile import gettempdir

import mlabraw

from awmstools import update, gensym, slurp, spitOut, isString, escape, strToTempfile, __saveVarsHelper

#XXX: nested access

def _flush_write_stdout(s):

"""Writes `s` to stdout and flushes. Default value for ``handle_out``."""

sys.stdout.write(s); sys.stdout.flush()

# XXX I changed this to no longer use weakrefs because it didn't seem 100%

# reliable on second thought; need to check if we need to do something to

# speed up proxy reclamation on the matlab side.

class CurlyIndexer(object):

self.proxy.__setitem__(index, value, '{}')

class MlabObjectProxy(object):

value)

class MlabConversionError(Exception):

"""Raised when a mlab type can't be converted to a python primitive."""

pass

class MlabWrap(object):

return mlab_command

mlab = MlabWrap()

MlabError = mlabraw.error

def saveVarsInMat(filename, varNamesStr, outOf=None, **opts):

mlab._do("clear('%s')" % "', '".join(varnames), nout=0)

__all__ = ['mlab', 'saveVarsInMat', 'MlabWrap', 'MlabError']

# Uncomment the following line to make the `mlab` object a library so that

# e.g. ``from mlabwrap.mlab import plot`` will work

## if not sys.modules.get('mlabwrap.mlab'): sys.modules['mlabwrap.mlab'] = mlab