=============================================================
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 from source
========================

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.

 - An environment which allows to compile Python extensions written in C and
   C++.  This includes a C/C++ compiler and Python C headers.  The latter might
   be provided in a separate package like ``python-dev``.

 - Some incarnation of `LAPACK <http://www.netlib.org/lapack/>`_.

optional (needed for plotting and the examples):

 - `pycairo <http://cairographics.org/pycairo/>`_

 - `matplotlib <http://matplotlib.sourceforge.net/>`_

kwant can be built 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 scripts 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 kwant 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:

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

* Please keep the code consistent by adhering to the prevailing naming and
  formatting conventions.  We generally follow the `"Style Guide for Python
  Code" <http://www.python.org/dev/peps/pep-0008/>`_ For docstrings, we follow
  `NumPy's "Docstring Standard"
  <http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_ and
  `Python's "Docstring Conventions"
  <http://www.python.org/dev/peps/pep-0257/>`_.

Several modules are written in `Cython <http://cython.org/>`_ (.pyx file name
extension).  You will need Cython 0.18 if you want to modify them.  (If Cython
0.18 is not released yet, try the bleeding-edge version.)  Turn on
cythonization by passing the option ``--run-cython`` to setup.py.


Tests
=====

kwant includes extensive unit tests which are supposed to cover all of its
functionality.  We use the `nose
<http://somethingaboutorange.com/mrl/projects/nose/>`_ testing framework.  To
run the tests, execute the command ``nosetests`` from the root directory of the
package after it has been built in place.