Commit b208440b authored by Christoph Groth's avatar Christoph Groth
Browse files

update installation instructions

parent d1a2e232
......@@ -2,24 +2,42 @@
Downloading and installing Kwant
================================
Overview of available methods
=============================
The quickest and easiest way to install Kwant is using the prepared packages
that are available for GNU/Linux (`Debian <#debian-and-derivatives>`_, `Ubuntu
<#ubuntu-and-derivatives>`_, and their variants, `Arch Linux`_), `Mac OS X`_,
and `Microsoft Windows`_. It is possible to be notified about new releases of
Kwant through an `announcement mailing list
<community.html#announcements-of-new-releases>`_.
and `Microsoft Windows`_.
Like most Python packages, `Kwant can be also installed using pip
<#automatic-installation-using-pip>`_. (Note, however, that this will often
result in a Kwant installation that runs significantly slower.)
If no packages are available for the system you use, or if you would like to
build Kwant from source for another reason (expert users may want to customize
Kwant to use certain optimized versions of libraries), please consult the `full
installation instructions
<doc/1/pre/install.html#building-and-installing-from-source>`_ in the
documentation.
Kwant to use certain optimized versions of libraries), please consult the
documentation on `how to install Kwant from source <doc/1/pre/install.html>`_.
Python 3 or Python 2
====================
Before installing Kwant, one has to decide which Python version to use –
Python 3 or Python 2. `Python 3.0
<https://docs.python.org/3/whatsnew/3.0.html>`_ was the first ever
intentionally backwards incompatible Python release, i.e. scripts that target
Python 2 will typically not run with Python 3 and above unchanged.
Kwant releases up to 1.1 require Python 2. Starting with release 1.2, we have
`switched to Python 3 <http://kwant-project.org/doc/1/pre/whatsnew/1.2>`_. We
recommend to use the latest Kwant with Python 3. Those who are stuck with
Python 2 are invited to continue to use Kwant 1.1 which will be maintained for
several years after 2015.
The source code of released versions of Kwant is available for `download
<http://downloads.kwant-project.org/kwant/>`_. You can follow the development
by browsing or cloning the `Git repository of Kwant
<https://gitlab.kwant-project.org/kwant/kwant>`_.
The instructions below assume Python 3. They should be also valid for Python
2 if all occurrences of ``python3``, ``pip3``, etc. are replaced by
``python``, ``pip``.
Debian and derivatives
......@@ -48,7 +66,7 @@ The lines prefixed with ``sudo`` have to be run as root.
3. Update the package data, and install Kwant::
sudo apt-get update
sudo apt-get install python-kwant python-kwant-doc
sudo apt-get install python3-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``.
......@@ -61,13 +79,13 @@ surprisingly easy::
sudo apt-get build-dep tinyarray
apt-get source --compile tinyarray
sudo dpkg -i python-tinyarray_*.deb
sudo dpkg --install python3-tinyarray_*.deb
sudo apt-get build-dep kwant
apt-get source --compile kwant
sudo dpkg -i python-kwant_*.deb python-kwant-doc_*.deb
sudo dpkg --install python3-kwant_*.deb python-kwant-doc_*.deb
This method should work for virtually all Debian-derived systems, even on exotic
This method should work for all Debian-derived systems, even on exotic
architectures.
......@@ -78,7 +96,7 @@ 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
sudo apt-get install python3-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
......@@ -88,9 +106,12 @@ documentation will be installed locally in the directory
Arch Linux
==========
Arch install scripts for Kwant are kindly provided by Jörg Behrmann (formerly
by Max Schlemmer). To install, follow the `Arch User Repository installation
instructions
*(This section still targets Python 2 and needs to be updated for Python 3.)*
‘Arch install scripts for Kwant
<https://aur.archlinux.org/packages/python2-kwant/>‘_ are kindly provided by
Jörg Behrmann (formerly by Max Schlemmer). To install, follow the `Arch User
Repository installation instructions
<https://wiki.archlinux.org/index.php/Arch_User_Repository#Installing_packages>`_.
Note that for checking the validity of the package you need to add the key
used for signing to your user's keyring via::
......@@ -113,6 +134,8 @@ Kwant and its dependencies both via the `homebrew <http://brew.sh>`_ and the
Mac OS X: homebrew
==================
*(This section needs to be updated for Python 3.)*
homebrew is a recent addition to the package managers on Mac OS X. It is
lightweight, tries to be as minimalistic as possible and give the user
freedom than Macports. We recommend this option if you have no preferences.
......@@ -182,6 +205,8 @@ Notes:
Mac OS X: MacPorts
==================
*(This section needs to be updated for Python 3.)*
MacPorts is a full-fledged package manager that recreates a whole Linux-like
environment on your Mac.
......@@ -268,8 +293,8 @@ provided by Christoph Gohlke. To install Kwant on Windows
5. Reboot your computer.
6. Download the necessary packages (with the ending ``.whl``) for your
operating system (32 or 64 bit) and Python version (e.g. ``cp27`` for Python
2.7) from the website of `Christoph Gohlke
operating system (32 or 64 bit) and Python version (e.g. ``cp34`` for Python
3.4) from the website of `Christoph Gohlke
<http://www.lfd.uci.edu/~gohlke/pythonlibs/>`_. For Kwant, we recommend to download at least `NumPy <http://www.lfd.uci.edu/~gohlke/pythonlibs/#numpy>`_, `SciPy <http://www.lfd.uci.edu/~gohlke/pythonlibs/#scipy>`_, `Matplotlib <http://www.lfd.uci.edu/~gohlke/pythonlibs/#matplotlib>`_, `Nose <http://www.lfd.uci.edu/~gohlke/pythonlibs/#nose>`_, `Tinyarray <http://www.lfd.uci.edu/~gohlke/pythonlibs/#tinyarray>`_, and `Kwant <http://www.lfd.uci.edu/~gohlke/pythonlibs/#kwant>`_ itself.
7. Now open a command prompt with administrator rights, as described in
......@@ -278,13 +303,52 @@ provided by Christoph Gohlke. To install Kwant on Windows
In this new command prompt window, execute ::
pip install <filename>
for each of the downloaded files (replacing ``<filename>`` with it).
pip3 install --no-deps *.whl
(This will install all the wheel-files in the current directory.)
Now you are done, you can ``import kwant`` from within Python scripts.
(Note that many other userful scientific packages are available in Gohlke’s
(Note that many other useful scientific packages are available in Gohlke’s
repository. For example, you might want to install `IPython
<http://www.lfd.uci.edu/~gohlke/pythonlibs/#ipython>`_ and its various
dependencies so that you can use the `IPython notebook <http://ipython.org/notebook.html>`_.)
Automatic installation using ``pip``
====================================
The most recent stable version of Kwant can be downloaded and installed
directly from the `Python package index <https://pypi.python.org/>`_ using
Python’s “pip“ tool::
sudo pip3 install kwant
Pip can be also used to directly install the most recent development version
of Kwant directly from the Git repository::
sudo pip3 install git+https://gitlab.kwant-project.org/kwant/kwant.git
Each of the above commands will perform a system-wide install (to
``/usr/local`` on Unix). Type ``pip3 help install`` for installation options
and see `pip documentation <https://pip.readthedocs.org/>`_ for a detailed
description of ``pip``.
Note that ``pip`` will not install any non-Python dependencies such as `MUMPS
<http://graal.ens-lyon.fr/MUMPS/>`_. These need to be installed in some other
way. As an example, on a Debian or Ubuntu system, the following command will
install the non-Python prerequisites of Kwant::
sudo apt-get install gfortran libopenblas-dev liblapack-dev libmumps-scotch-dev
The Kwant build scripts should find libraries that have been installed in the
above way automatically. This will be signaled at the end of the build
process as follows::
******************************** Build summary ********************************
Default LAPACK and BLAS
Auto-configured MUMPS
*******************************************************************************
On other platforms MUMPS will not be linked against. If prepared packages are
not an option, the build process must be `configured manually
<doc/1/pre/install.html#build-configuration>`_.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment