install.txt

=======
Install
=======

Kwant can be installed either using prepared packages (Debian and Ubuntu
variants of GNU/Linux, Mac OS X, and Windows), or it can be built and installed
from source.

In general, installation from packages is advisable, especially for novice
users.  Expert users may find it helpful to build Kwant from source, as this
will also allow them to customize Kwant to use certain optimized versions of
libraries.

Ubuntu (and derivatives)
========================

Execute the following commands::

    sudo apt-add-repository ppa:kwant-project/ppa
    sudo apt-get update
    sudo apt-get install python-kwant python-kwant-doc

This should provide Kwant for all versions of Ubuntu >= 12.04.  The HTML
documentation will be installed locally in the directory
``/usr/share/doc/python-kwant-doc``.


Debian (and derivatives)
========================

The easiest way to install Kwant on a Debian system is using the pre-built
packages we provide.  Our packages are known to work with Debian "wheezy" and
Debian "jessie", but they may also work on many other recent Debian-derived
sytems as well.  (For example, the following works with recent Ubuntu versions.)

The lines prefixed with ``sudo`` have to be run as root.

1. Add the following lines to ``/etc/apt/sources.list``::

       deb http://downloads.kwant-project.org/debian/ stable main
       deb-src http://downloads.kwant-project.org/debian/ stable main

2. (Optional) Add the OpenPGP key used to sign the repositories by executing::

       sudo apt-key adv --keyserver pgp.mit.edu --recv-key C3F147F5980F3535

3. Update the package data, and install Kwant::

       sudo apt-get update
       sudo apt-get install python-kwant python-kwant-doc

   The ``python-kwant-doc`` package is optional and installs the HTML
   documentation of Kwant in the directory ``/usr/share/doc/python-kwant-doc``.

Should the last command (``apt-get install``) fail due to unresolved
dependencies, you can try to build and install your own packages, which is
surprisingly easy::

    cd /tmp

    sudo apt-get build-dep tinyarray
    apt-get source --compile tinyarray
    sudo dpkg -i python-tinyarray_*.deb

    sudo apt-get build-dep kwant
    apt-get source --compile kwant
    sudo dpkg -i python-kwant_*.deb python-kwant-doc_*.deb

This method should work for virtually all Debian-derived systems, even on exotic
architectures.


Windows
=======

There are multiple distributions of scientific Python software for Windows that
provide the prerequisites for Kwant.  We recommend to use the packages kindly
provided by Christoph Gohlke.  To install Kwant on Windows

1. Determine whether you have a 32-bit or 64-bit Windows installation by
   following these `instructions <http://support.microsoft.com/kb/827218>`_.

2. Download and install Python 2.7 for the appropriate architecture (32-bit or
   64-bit) from the official `Python download site
   <http://www.python.org/download/>`_.

3. Download and install ``scipy-stack``, ``tinyarray``, and ``kwant`` for Python
   2.7 from `Christoph Gohlke's page
   <http://www.lfd.uci.edu/~gohlke/pythonlibs/>`_.  Once again you should choose
   the architecture that is appropriate for your system.  ("win32" means 32-bit,
   "amd64" means 64-bit -- even if you have a processor from Intel.)  If the
   download from Gohlke's site is slow, try to download from `our mirror
   <http://downloads.kwant-project.org/gohlke-mirror/>`_.

   You may see a warning that says "The publisher could not be verified. Do you
   want to run this software?". Select "Run".


Mac OSX
=======

There is a number of different package managers for bringing software
from the Unix/Linux world to Mac OSX. Since the community is quite
split, we provide Kwant and its dependencies both via the `MacPorts
<http://www.macports.org>`_ and `homebrew <http://brew.sh>`_ systems.
(For non experts MacPorts is perhaps easier to handle).

Mac OSX: MacPorts
=================

MacPorts is a full-fledged package manager that recreates a whole Linux-like
environment on your Mac. Beside Kwant, MacPorts gives you access to a wealth of free softwares which you can install on your computer
easily (using simple command line instructions). It requires little choices to be made by the user,
and allows for the simplest way to install Kwant.

In order to install Kwant, you have to

1. Install a recent version of MacPorts. In order to do that, you first have to install 
   the prerequisites described below. When this is done, you can proceed with the installation of
   MacPorts itself, as explained in the `installation instructions of MacPorts
   <http://www.macports.org/install.php>`_. The prerequisites are,

  * the Xcode developer tools (compiler suite for Mac OSX) from
    `<http://developer.apple.com/downloads>`_. You will need an Apple ID to
    download. Note that if you have one already from using the App store
    on the Mac/Ipad/Iphone/... you can use that one. You will also need the
    command line tools: Within Xcode 4, you have to download them by going to
    `Xcode->Preferences`, click on `Download`, go to `Components`,
    select `Command Line Tools` and click on `Install`. Alternatively, you can
    also directly download the command line tools from the
    Apple developer website.
  * if you have MacOSX 10.8 or higher, the X11 server from the
    `XQuartz project <http://xquartz.macosforge.org>`_.

2. After the installation, open a terminal and execute ::

       echo http://downloads.kwant-project.org/macports/ports.tar |\
       sudo tee -a /opt/local/etc/macports/sources.conf >/dev/null

   (this adds the Kwant MacPorts download link
   `<http://downloads.kwant-project.org/macports/ports.tar>`_ at the end of the
   ``sources.conf`` file.)

3. Execute ::

       sudo port selfupdate

4. Now, install Kwant and its prerequisites ::

       sudo port install py27-kwant

5. Finally, we choose python 2.7 to be the default python ::

       sudo port select --set python python27

   After that, you will need to close and reopen the terminal to
   have all changes in effect.

Notes:

* If you have problems with macports because your institution's firewall
  blocks macports (more precisely, the `rsync` port), resulting in
  errors from ``sudo port selfupdate``, follow
  `these instructions <https://trac.macports.org/wiki/howto/PortTreeTarball>`_.
* Of course, if you already have macports installed, you can skip step 1
  and continue with step 2.


Mac OS X: homebrew
==================

homebrew is a recent addition to the package managers on Mac OSX. It is
more lightweight, tries to be as minimalistic as possible and give the user
more freedom. Because of that, it requires a little more experience on
the user side compared to MacPorts. The requirements are moderate though,
if you know how to add directories to the ``$PATH`` variable for your shell,
you are safe.

1. Open a terminal and install homebrew as described on the `homebrew
   homepage <http://brew.sh>`_ (instructions are towards the end of
   the page)

2. Run ::

       brew doctor

   and follow its directions. It will ask for a few prerequisites to be
   installed, in particular

  * the Xcode developer tools (compiler suite for Mac OSX) from
    `<http://developer.apple.com/downloads>`_. You will need an Apple ID to
    download. Note that if you have one already from using the App store on the
    Mac/Ipad/Iphone/... you can use that one. Downloading the command line
    tools (not the full Xcode suite) is sufficient. If you have the full Xcode
    suite installed, you might need to download the command line tools manually
    if you have version 4 or higher. In this case go to `Xcode->Preferences`,
    click on `Download`, go to `Components`, select `Command Line Tools` and
    click on `Install`.
  * although `brew doctor` might not complain about it right away, while we're
    at it, you should also install the X11 server from the `XQuartz project
    <http://xquartz.macosforge.org>`_ if you have Mac OSX 10.8 or higher.

3. Add permanently ``/usr/local/bin`` before ``/usr/bin/`` in the ``$PATH$``
   environment variable of your shell, for example by adding ::

       export PATH=/usr/local/bin:$PATH

   at the end of your ``.bash_profile`` or ``.profile``. Then close
   the terminal Terminal and reopen it again.

4. Install a few prerequisites ::

       brew install gfortran python

5. Add additional repositories ::

       brew tap homebrew/science
       brew tap samueljohn/python
       brew tap michaelwimmer/kwant

6. Install Kwant and its prerequisites ::

       pip install nose
       brew install numpy scipy matplotlib
       brew install kwant

Notes:

- If something does not work as expected, use ``brew doctor`` for
  instructions (it will find conflicts and things like that).
- As mentioned, homebrew allows for quite some freedom. In particular,
  if you are an expert, you don't need necessarily to install
  numpy/scipy/matplotlib from homebrew, but can use your own installation.
  The only prerequisite is that they are importable from python. (the
  Kwant installation will in any case complain if they are not)
- In principle, you need not install the homebrew python, but could use
  Apple's already installed python. Homebrew's python is more up-to-date,
  though.


Building and installing from source
===================================

See complete `build instructions
</docs/pre/install.html#building-and-installing-from-source>`_.