Pytave README
=============

For installation instructions specific for Pytave, please see the
[INSTALL.md](INSTALL.md) file.

Contents of this document
-------------------------

  1. What is Pytave?
  2. Gotchas
  3. Pytave and multi-threading
  4. Python/Octave cheat sheet

What is Pytave?
===============

Pytave enables Python scripts to use existing m-files (Octave/Matlab
scripts) for numerical calculations. The Octave language interpreter is
embedded as a module to Python.

Example use
-----------

Calling Octave code in the interactive Python interpreter:

    >>> import pytave
    >>> pytave.feval(1, "cos", 0)
    (1.0,)

Goals
-----

Pytave strives to uphold these points

  * Good out of the box experience
  * Good-natured implicit type conversions, no strange PyApple ->
    octave_orange -> PyBanana chains

Features
--------

A short list of what Pytave is capable of

  * Implicit type conversions between Python and Octave. Supports all
    NumPy integer and floating point matrices
  * Architecture independent - no assumption on endian type or integer
    sizes
  * Supports cell <-> list and struct <-> dict conversions.

Project homepage
----------------

[https://bitbucket.org/mtmiller/pytave](https://bitbucket.org/mtmiller/pytave)

Using/hacking
-------------

You need the Mercurial version control software (hg). Clone the repo
with:

    $ hg clone https://bitbucket.org/mtmiller/pytave

You will now have a directory called `pytave` with source code for the
module. Read the [INSTALL.md](INSTALL.md) file for building instructions.

Gotchas
=======

Unfortunately, the implicit conversion is not bijective (there is not a
one-to-one relation between Octave and Python values). Pytave users
should be aware of the following cases.

Numeric row vectors to Octave matrices
--------------------------------------

Numeric row vectors are converted to Octave 1xN matrices; returned 1xN
matrices will become 1xN numerical arrays, not row vectors. As an
example, a NumPy array with shape == (3,) will become (1, 3) when
converted back and forth.

Octave cells to Python lists
----------------------------

Only row cell arrays can be converted to Python lists.

Python dictionaries to Octave structures
----------------------------------------

Dictionaries converted to structures must only have string keys. This is
because Octave structures only allow string keys. Keys must also be
valid Octave identifiers.

As Octave structures are built using cells, simple variables are
upgraded to cells when a dictionary is converted. A dictionary

    {"name": "Pytave"}

thus will become

    ans =
    {
      name = Pytave
    }

in Octave. In this listing, Octave is hiding the fact that the value is
wrapped in a cell. Converted back, cells are converted to Python lists.
The re-converted Python dictionary will read

    {"name": ["Pytave"]}

which is natural effect because of the way Octave handles structures.

The list values in dictionaries to be converted must be of equal length.
All restrictions demanded by the Octave `struct` built-in applies.

Pytave and multi-threading
==========================

Pytave does not handle reentrant calls. It is not thread-safe, and you
cannot make several Pytave calls in parallel. There are no safety
harnesses in Pytave (unlike e.g. PySqlite), and Pytave will not stop you
if you try to make concurrent calls. The behavior is undefined. It is
not possible to run several calculations in parallel.

That being said, it is possible to do other things while one Pytave call
is running. Pytave is aware of the Global Interpreter Lock. The lock
will be released while the Octave interpreter is running, allowing you
to have other Python threads to run in parallel with the one Octave
call.

Python/Octave cheat sheet
=========================

Octave and Python share some syntax elements, which unfortunately makes
it harder to distinguish between the languages. Here are some examples
in both languages, showing how to build related constructs.

Create a 2x3 matrix
-------------------

    octave:1> [1, 1, 1; 2, 2, 2]
    python>>> array([[1, 1, 1], [2, 2, 2]])

Create a 3x2 matrix
-------------------

    octave:1> [1, 1; 2, 2; 3, 3]
    python>>> array([[1, 1], [2, 2], [3, 3]])

Create a 1x3 matrix
-------------------

    octave:1> [1, 1, 1]
    python>>> array([[1, 1, 1]])

Create a row vector
-------------------

Not applicable to Octave.

    python>>> array([1, 1, 1])

Note: Python row vectors will be converted to Octave 1xN matrices.

Create a 3x1 matrix
-------------------

    octave:1> [1; 2; 3]
    python>>> array([[1], [2], [3]])

Create a 1x1 structure/dictionary
---------------------------------

    octave:1> struct("x", 1, "y", 2)
    python>>> {"x": 1, "y": 2}

Create a 1x2 structure array/dictionary containing lists of length 2
--------------------------------------------------------------------

    octave:1> struct("firstname", {"David", "Håkan"}, ...
                     "lastname", {"Grundberg", "Fors Nilsson"})
    python>>> {"firstname": ["David", "Håkan"], \
               "lastname": ["Grundberg", "Fors Nilsson"]}

Create a 1x3 cell array/list
----------------------------

    octave:1> {"foo", "bar", "baz"}
    python>>> ["foo", "bar", "baz"]