README
==========

Pymothoa extends the Python language by adding JIT compilation without any
modification of the interpreter source code. Pymothoa lives at the application
level. It uses the AST generated by Python. Therefore, users write in the 
original Python syntax but with a new contextual meaning in some cases using
the new dialect provided by Pymothoa.

User uses the decorators provided to mark Python functions for JIT compilation.
Pymothoa uses LLVM for the JIT ability. (LLVM is amazing!)

-----------
  License
-----------

Pymothoa is released under the "Simplified BSD License." See the "LICENSE" file
in the same directory of this file.

LLVM is released under the "University of Illinois/NCSA Open Source License."
For detail, visit http://llvm.org/docs/DeveloperPolicy.html

--------
  Why?
--------

I uses Python for a lot of prototyping and experimenting. But occasionally, 
I needed some better performance. One may write a C-extension but that is a
lot of effort. To enable faster code and faster programming, I developed 
Pymothoa. Now, I can simply add a decorator to a function and magically JIT
compiles it to native code.

There are other ways to create C-extensions rather easily. But C-extensions
mean making your Python package less portable and more cumbersome to use.
On the other hand, JIT compiling your compute-intensive function at runtime
means better utilization of resources as LLVM can select the best instructions 
to do the job.

For instance, Pymothoa has vector types so that one can write portable
vectorized algorithms. LLVM will automatically revert to the scalar equivalence
if the running system does not support vector instructions. Imagine doing
that portability in your Python C-extension.
(See LLVM documentation for detail about vector support on various CPUs.)

--------
  Demo
--------

There are a few demo code in the demo directory. Take a look and try running
them. There all contain benchmark of the performance against raw Python code
and Numpy (if applicable).

-----------
  Install
-----------

You will need to have 'llvm-config' in your path either by installing from
your software package manager or built from the source code.

For Linux, download the latest LLVM release from http://llvm.org and extract
the archive. Then, in the extracted archive:

$ ./configure --enable-optimized
$ make all

You do not need to 'make install' if you are doing per-user installation. Just
make sure 'llvm-config' is in your PATH.

For other platforms, ... (TODO)

To build:
$ python setup.py build

To install (system-wide):
$ python setup.py install

To install (per-user):
$ python setup.py install --user

On Linux, this puts Pymothoa in the "~/.local/lib/pythonX.X/site-packages" 
directory. (Replace "X.X" with your Python version.)

-------------
  Platforms
-------------

CPython only.
Only tested on Ubuntu 10.04 and 12.04 (32/64-bit x86).
It should probably work on other OS and CPU that are supported by LLVM.

----------------
  LLVM Version
----------------

Tested with 3.1 release. Should work with other versions as well.

--------------------
  Future Work/Plan
--------------------

* Parallel programming with OpenCL, CUDA