--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README.md	Tue Apr 05 21:00:58 2016 -0700
@@ -0,0 +1,190 @@
+Pytave README
+=============
+
+For installation instructions specific for Pytave, please see the
+[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]()
+
+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]() 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"]