README

-*- coding:utf-8 -*-

Pytave README

For installation instructions specific for Pytave, please see the
INSTALL 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
    Numeric integer, real double (and possibly real float) matrices

  * Architecture independent - no assumption on endian type or integer
    sizes

  * Supports cell <-> list and struct <-> dict conversions.

Project homepage
================

https://launchpad.net/pytave

Using/hacking
=============

You need the Bazaar version control software (bzr).  Branch from trunk
with:

  $ bzr branch lp:pytave

   You will now have a directory called `pytave' with source code for
the module.  Read the INSTALL 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 Numeric 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"]

EOF.