=============================
Building and installing kwant
=============================

Prerequisites
=============

Building kwant requires
 * `Python <http://python.org>`_ 2.6 or newer,
 * `SciPy <http://scipy.org>`_ 0.7.2 or newer,
 * `LAPACK <http://netlib.org/lapack/>`_ and `BLAS <http://netlib.org/blas/>`_,
   (For best performance we recommend the free `OpenBLAS
   <http://xianyi.github.com/OpenBLAS/>`_ or the unfree `MKL
   <http://software.intel.com/en-us/intel-mkl>`_.)
 * tinyarray, a NumPy-like Python package optimized for very small arrays,
 * An environment which allows to compile Python extensions written in C and
   C++.

The following software is highly recommended though not strictly required:
 * `matplotlib <http://matplotlib.sourceforge.net/>`_, for kwant's plotting
   module and the tutorial,
 * `MUMPS <http://graal.ens-lyon.fr/MUMPS/>`_, a sparse linear algebra library
   that will in many cases speed up kwant several times and reduce the memory
   footprint.  (kwant uses only the sequential, single core version
   of MUMPS.  The advantages due to MUMPS as used by kwant are thus independent
   of the number of CPU cores of the machine on which kwant runs.)

In addition, to build a copy of kwant that has been checked-out directly from
version control (git), you will also need `Cython <http://cython.org/>`_ 0.17.1
or newer.  You do not need Cython to build kwant that has been unpacked from a
source .tar.gz-file.

Generic instructions
====================

Please note the `system-specific instructions`_ below.

kwant can be built and installed following the `usual Python conventions
<http://docs.python.org/install/index.html>`_ by running the following commands
in the root directory of the kwant distribution. ::

    python setup.py build
    python setup.py install

Depending on your system, you might have to run the second command with
administrator privileges (e.g. prefixing it with ``sudo``).

To check successful installation try executing some scripts in the ``tutorial``
subdirectory, e.g.::

    cd tutorial
    python 1-quantum_wire_revisited.py


System-specific instructions
============================

Unix-like systems (Linux)
-------------------------

kwant should run on all recent Unix-like systems.  The following instructions
have been verified to work on Debian 6 (Squeeze) or newer, and on Ubuntu 12.04
or newer.  For other systems step 1 will likely have to be adapted.  If
``sudo`` is not available, the respective command must be run as root.

1. Install the required packages by running the command ::

       sudo apt-get install python-dev python-scipy python-matplotlib \
       g++ gfortran libopenblas-dev liblapack-dev libmumps-scotch-dev

2. Unpack tinyarray, enter its directory. To build and install, run ::

       python setup.py build
       sudo python setup.py install

3. Inside the kwant source distribution's root directory run ::

       python setup.py build
       sudo python setup.py install

By default the package will be installed under ``/usr/local``.  You can
change this using the ``--prefix`` option, e.g.::

    sudo 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 root privileges.  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 the file
``.bashrc`` (or equivalent) in your home directory.


Mac OS X
--------

(Please help to improve these instructions.)

These are instructions for installing kwant on Mac computers using the software
MacPorts.  MacPorts allows to download and install a large number of
open-source software packages.  There exist also other ways to install the
required libraries.

Following these instructions will install kwant without `MUMPS
<http://graal.ens-lyon.fr/MUMPS/>`_.  It is well possible to use MUMPS under OS
X - most likely you will have to install it from source.  The section `Build
configuration`_ explains how to tell kwant where to find your self-compiled
MUMPS.

These instructions were verified in November 2011 under Mac OS X 10.6.8.

1. Install a fresh version of Xcode (Apple's development environment).

2. Install `MacPorts <http://www.macports.org/>`_.  After installation, you
   probably want to update its data base with ::

       sudo port selfupdate

3. OPTIONAL: Install a more recent gcc compiler::

       sudo port install mp-gcc44

   (``port search gcc`` will give you the available versions) and set it as
   your default ::

       sudo port select --set gcc mp-gcc44

   (``port select gcc`` will give you the possible choices)

4. Install the required packages::

       sudo port install python27
       sudo port install py27-scipy
       sudo port install py27-matplotlib

5. You might need to modify the matplotlib configuration file::

       > python
       >>> import matplotlib
       >>> matplotlib.matplotlib_fname()
       '/Users/username/.matplotlib/matplotlibrc'

    Edit the corresponding ``matplotlibrc`` configuration file, look for the
    line starting with backend and modify it to::

       backend      : MacOSX

6. Set python 2.7 as your default. ::

       sudo port select --set python python27

7. Unpack tinyarray, enter its directory, build and install. ::

       python setup.py build
       sudo python setup.py install

8. Go to the kwant directory, build and install. ::

       python setup.py build
       sudo python setup.py install


Microsoft Windows
-----------------

It should be possible to run kwant under Microsoft Windows but so far no one
has tried hard enough.  We will happily include Windows-specific installation
instructions in this document once someone contributes them.

A good starting point should be the `free edition of the Enthought Python
Distribution <http://www.enthought.com/products/epd_free.php>`_.


Build configuration
===================

The setup script of kwant has to know how to link against LAPACK & BLAS, and,
optionally, MUMPS.  Be default it will assume that LAPACK and BLAS can be found
under their usual names.  MUMPS will be not linked against by default, except
on Debian-based systems when the package ``libmumps-scotch-dev`` is installed.

All these settings can be configured by creating/editing the file
``build.conf`` in the root directory of the kwant distribution.  This
configuration file consists of sections, one for each dependency, led by a
[dependency-name] header and followed by name = value entries.  Possible names
are keyword arguments for ``distutils.core.Extension`` (For a complete list,
see the third table from top of `this document
<http://docs.python.org/distutils/apiref.html>`_).  The corresponding values
are whitespace-separated lists of strings.

The two currently possible sections are [lapack] and [mumps].  The former
configures the linking against LAPACK _AND_ BLAS, the latter against MUMPS
(without LAPACK and BLAS).

Example ``build.conf`` for linking kwant against a self-compiled MUMPS, `SCOTCH
<http://www.labri.fr/perso/pelegrin/scotch/>`_ and `METIS
<http://glaros.dtc.umn.edu/gkhome/metis/metis/overview>`_::

    [mumps]
    libraries = zmumps mumps_common pord metis esmumps scotch scotcherr mpiseq
        gfortran

Example ``build.conf`` for linking kwant with Intel MKL.::

    [lapack]
    libraries = mkl_intel_lp64 mkl_sequential mkl_core mkl_def
    library_dirs = /opt/intel/mkl/lib/intel64
    extra_link_args = -Wl,-rpath=/opt/intel/mkl/lib/intel64

The detailed syntax of ``build.conf`` is explained in the `documentation of
Python's configparser module
<http://docs.python.org/3/library/configparser.html#supported-ini-file-structure>`_.


Building the documentation
==========================

To build the documentation, kwant has to be installed as described above.
Additionally, 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.


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 if you want to modify them.

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