README.txt

=============================================================
kwant, a package for numerical quantum transport calculations
=============================================================

Licence
=======

This software is NOT TO BE DISTRIBUTED, neither in part nor as a whole.

The only exception to this is the ``doc/sphinxext`` subdirectory, which is free
software.  (See the file ``LICENSE.txt`` in that subdirectory.)


Installation
============

The prerequisites are

 - More or less current versions of `Python <http://python.org>`_ and `SciPy
   <http://scipy.org>`_.  Python 2.6 and scipy 0.7.2 should be enough.

 - `Cython <http://cython.org/>`_ -- Version 0.13 works for us.

optional:

 - `pycairo <http://cairographics.org/pycairo/>`_ (for plotting)

 - `matplotlib <http://matplotlib.sourceforge.net/>`_ (for some of the
   examples)

kwant can be build and installed using distutils, following standard python
conventions.  To build and install, run the following commands in the root
directory of the package. ::

    python setup.py build
    python setup.py install

The second command has to be run as root (e.g. prefixing it with ``sudo``).  By
default the package will be installed under ``/usr/local``.  You can change
this using the ``--prefix`` option, e.g.::

    python setup.py install --prefix=/opt

If you would like to install kwant into your home directory only you can use ::

    python setup.py install --home=~

This does not require superuser priviledges.  If you install kwant in this way
be sure to tell python where to find it.  This can be done by setting the
``PYTHONPATH`` environment variable::

    export PYTHONPATH=$HOME/lib/python

You can make this setting permanent by adding this line to your the file
``.bashrc`` in your home directory.

To check successful installation try executing some examples in the
``examples`` subdirectory.


Documentation
=============

To build the documentation, kwant has to be installed as described in the
previous section.  The `sphinx documentation generator
<http://sphinx.pocoo.org/>`_ is required.

HTML documentation can be built by entering the ``doc`` subdirectory of the
kwant package and executing ``make html``.  PDF documentation is generated by
executing ``make latex`` followed by a ``make all-pdf`` in ``doc/build/latex``.

Because of some quirks of how sphinx works, it might be necessary to execute
``make clean`` between building HTML and PDF documentation.  If this is not
done, sphinx might mistakenly use PNG files for PDF output.

Please consult the documentation for further information on how to use kwant.


Hacking
=======

To work on the library itself it is useful to build it in-place.  This can be
done with the following command ::

    python setup.py build_ext -i

The ``kwant`` subdirectory of the source distribution will be thus turned into
a proper python package which can be imported.  To be able to import kwant from
within python, one can either work in the root directory of the distribution
(where the subdirectory ``kwant`` is located), or make a (symbolic) link from
somewhere in the Python search path to the the package subdirectory.

Some conventions to keep in mind:

* Please keep the code consistent by adhering to the already used naming and
  formatting conventions.  We generally follow the `"Style Guide for Python
  Code" <http://www.python.org/dev/peps/pep-0008/>`_ and the `"Docstring
  Conventions" <http://www.python.org/dev/peps/pep-0257/>`_.

* Write tests for all the important functionality you add.  Be sure not to
  break existing tests.


Tests
=====

We use the `nose testing framework
<http://somethingaboutorange.com/mrl/projects/nose/>`_.  To run the tests,
execute the command ``nosetests`` from the root directory of the package after
it has been built in place.