From b208440bc746e560c8ec9ab4c97c35676b1b13d7 Mon Sep 17 00:00:00 2001
From: Christoph Groth <christoph.groth@cea.fr>
Date: Fri, 11 Dec 2015 23:46:04 +0100
Subject: [PATCH] update installation instructions
---
content/install.rst | 114 ++++++++++++++++++++++++++++++++++----------
1 file changed, 89 insertions(+), 25 deletions(-)
diff --git a/content/install.rst b/content/install.rst
index 54bea0a..130bdd1 100644
--- a/content/install.rst
+++ b/content/install.rst
@@ -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>`_.
--
GitLab