From b7e5bb9f9d80470f0b08206d4e7ee8ceb5a49937 Mon Sep 17 00:00:00 2001
From: Joseph Weston <joseph.weston08@gmail.com>
Date: Tue, 16 May 2017 13:38:08 +0200
Subject: [PATCH] update installation instructions
---
content/install.rst | 337 ++++++++++++++++++--------------------------
1 file changed, 138 insertions(+), 199 deletions(-)
diff --git a/content/install.rst b/content/install.rst
index fa9a5e1..23208a1 100644
--- a/content/install.rst
+++ b/content/install.rst
@@ -11,48 +11,55 @@ If you have used Kwant for work that has lead to a scientific publication,
please `cite the Kwant paper and possibly other relevant publications
</cite>`_.
+Prerequisites
+=============
+In order to use Kwant you will need to install a distribution of the Python
+language. If you are using a GNU/Linux operating system this should already be
+installed on your computer.
-Overview of available installation methods
-==========================================
+If you are using Mac OS X or Microsoft Windows you will need to install a
+Python distribution yourself. Details of how to do this are in the
+installation instructions of the corresponding platform.
-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`_.
+**Kwant version 1.2 and newer requires at least Python 3.4**.
-Like most Python packages, `Kwant can be also installed using pip
-<#automatic-installation-using-pip>`_. (Be sure to follow this link, since
-naive use of pip will likely result in a Kwant installation with significantly
-reduced performance.)
+Those who must use Python 2 can still use Kwant up to version 1.1,
+which will receive bug fixes for several years
+after 2015 (but no new features).
-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
-documentation on `how to install Kwant from source <doc/1/pre/install.html>`_.
+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``.
-Python 3 or Python 2
-====================
+Choose your plaform
+===================
+Installation instructions are available for the major operating systems:
-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.)
++ `GNU/Linux`_
++ `Mac OS X`_
++ `Microsoft Windows`_
-Kwant releases up to 1.1 require Python 2. Starting with release 1.2, Kwant
-development has `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 can continue to
-use Kwant 1.1 which will be maintained for several years after 2015.
+GNU/Linux
+=========
+Pre-built packages exist for the following distributions:
-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 <#debian-and-derivatives>`_
++ `Ubuntu <#ubuntu-and-derivatives>`_
++ `Arch Linux`_
+
+We also provide `conda packages <#conda>`_ for users of the `Anaconda
+<https://www.continuum.io/downloads>`_ Python distribution. *This is a useful
+option if you do not have root privileges* on the machine where you would like
+to install Kwant (e.g. on a computing cluster).
+
+If your distribution is not listed above, and you do not want to use the
+``conda`` packages, you can always install Kwant using `pip`_. Or by directly
+building `from source <#building-from-source>`_.
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 "stable" and
@@ -83,8 +90,7 @@ The lines prefixed with ``sudo`` have to be run as root.
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::
+dependencies, you can try to build and install your own packages::
cd /tmp
@@ -101,9 +107,10 @@ architectures.
Ubuntu and derivatives
-======================
+----------------------
-Execute the following commands::
+The easiest way to install Kwant on a Debian system is using the pre-built
+packages we provide. Execute the following commands in a terminal::
sudo apt-add-repository -s ppa:kwant-project/ppa
sudo apt-get update
@@ -115,7 +122,7 @@ documentation will be installed locally in the directory
Arch Linux
-==========
+----------
`Arch install scripts for Kwant
<https://aur.archlinux.org/packages/python-kwant/>`_ are kindly provided by
@@ -133,173 +140,45 @@ The fingerprint of the key is 5229 9057 FAD7 9965 3C4F 088A C3F1 47F5 980F
Mac OS X
========
+`Pre-built packages <#conda>`_ for Max OS X exist for the ``conda`` package
+manager, which is a part of the ``Anaconda`` Python distribution.
+Using ``conda`` is the recommended way to install Kwant on Mac OS X.
-There is a number of different package managers for bringing software from the
-Unix/Linux world to Mac OS X. Since the community is quite split, we provide
-Kwant and its dependencies both via the `homebrew <http://brew.sh>`_ and the
-`MacPorts <http://www.macports.org>`_ systems.
-
-
-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.
-
-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 OS X) 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 OS X 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 and reopen it again.
-
-4. Install a few prerequisites ::
-
- brew install gcc python
-
-5. Add additional repositories ::
-
- brew tap homebrew/science
- brew tap homebrew/python
- brew tap kwant-project/kwant
-
-6. Install Kwant and its prerequisites ::
-
- pip install nose six
- 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.
-
-
-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.
-
-In order to install Kwant using MacPorts, you have to
-
-1. Install a recent version of MacPorts, as explained in the
- `installation instructions of MacPorts
- <http://www.macports.org/install.php>`_.
- In particular, as explained there, you will have to install also a
- few prerequisites, namely
+If you do not want to use the ``conda`` packages, you can always install Kwant
+using `pip`_. Or by directly `building from source`_.
- * the Xcode developer tools (compiler suite for Mac OS X) 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 Mac OS X 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.
+We previously maintained Homebrew and Macports packages for Kwant, but due to
+effort required to keep them up to date we have dropped support for these
+installation methods. We recommend that people use the ``conda`` packages
+whenever possible.
Microsoft 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
+Windows packages for Kwant are kindly provided by Chrisoph Gohlke.
+The following instructions explain how to install the official version
+of Python 3, Kwant, and its dependencies.
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 for the appropriate architecture (32-bit: “x86†or
+2. Download and install Python 3 for the appropriate architecture (32-bit: “x86†or
64-bit: “x86-64â€) from the official `Python download site for Windows
- <http://www.python.org/download/>`_. We recommend that you install the
- latest stable Python 3 release.
+ <http://www.python.org/download/windows>`_. The current stable version
+ at the time of writing is Python 3.6.
3. Open a command prompt, as described in "How do I get a command prompt" at
the `Microsoft Windows website <http://windows.microsoft.com/en-us/windows/command-prompt-faq>`_.
4. In the command prompt window, execute::
- C:\Python35\python.exe C:\Python35\Tools\Scripts\win_add2path.py
+ C:\Python36\python.exe C:\Python36\Tools\Scripts\win_add2path.py
(Instead of typing this command, you can also just copy it from here and
paste it into the command prompt window). If you did not use the default
- location to install Python in step 2, then replace ``C:\Python35`` by the
+ location to install Python in step 2, then replace ``C:\Python36`` by the
actual location where Python is installed. You may also need to adjust the
- version (“35†signifies Python 3.5).
+ version (“36†signifies Python 3.6).
5. Reboot your computer.
@@ -342,17 +221,52 @@ repository. For example, you might want to install `IPython
dependencies so that you can use the `IPython notebook <http://ipython.org/notebook.html>`_.)
-Automatic installation using ``pip``
-====================================
+``conda``
+=========
+``conda`` is the package manager for the Anaconda Python distribution.
+
+Kwant currently has ``conda`` packages for GNU/Linux and Mac OS X platforms.
+
+1. Download the Python 3.6 verision of `Anaconda <https://www.continuum.io/downloads>`_ for
+ your platform and install it.
+
+2. Execute the following command in a terminal::
+
+ conda install -c conda-forge kwant
+
+ The above command installs Kwant and all of its dependencies from the
+ ``conda-forge`` channel.
+
+
+The latest development build of Kwant can be installed from the ``kwant``
+channel::
-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::
+ conda install -c kwant kwant
+
+
+``pip``
+-------
+.. caution::
+
+ Installing Kwant with ``pip`` is not easy because Kwant has several
+ non-Python dependencies and requires a C compiler. These instructions
+ are provided for advanced users only.
+
+``pip`` is the standard Python package manager that downloads and installs
+packages from the `Python package index <https://pypi.python.org/>`_.
+
+1. Install the non-Python dependencies of Kwant: a C compiler, BLAS, Lapack,
+ and (optionally) MUMPS (see `Installing non-Python dependencies`_).
+
+2. Execure the following command in a terminal::
sudo pip3 install kwant
-Pip can be also used to directly install the most recent development version
-of Kwant directly from the Git repository::
+ The above command installs Kwant and all of its Python dependencies from the
+ Python package index.
+
+The latest development build of Kwant can be installed directly from Kwant's
+Git repository::
sudo pip3 install git+https://gitlab.kwant-project.org/kwant/kwant.git
@@ -361,22 +275,47 @@ Each of the above commands will perform a system-wide install (to
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::
+Installing non-Python dependencies
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As mentioned above, ``pip`` will not install any non-Python dependencies
+required by Kwant. Kwant has several non-Python dependencies:
+
++ a C compiler (e.g. ``gcc``)
++ BLAS
++ Lapack
++ `MUMPS <http://graal.ens-lyon.fr/MUMPS/>`_.
+
+If you using a GNU/Linux system then your distribution probably has packages
+for these libraries; you will need to install the `-dev` or `-devel` versions
+of the packages.
- sudo apt-get install gfortran libopenblas-dev liblapack-dev libmumps-scotch-dev
+As an example, on a Debian or Ubuntu system, the following
+command will install the non-Python dependencies of Kwant::
-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::
+ sudo apt-get install build-essential gfortran libopenblas-dev liblapack-dev libmumps-scotch-dev
+
+On Debian or Ubuntu systems 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>`_.
+On other platforms it is possible that MUMPS is not linked against Kwant during
+installation. If this is the case the build process must be `configured
+manually <doc/1/pre/install.html#build-configuration>`_ by writing a
+``build.conf`` file. You can then tell ``pip`` to use this ``build.conf`` when
+installing kwant::
+
+ sudo pip install --global-option="--configfile=/path/to/build.conf" kwant
+
+
+Building from source
+====================
+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
+documentation on `how to install Kwant from source <doc/1/pre/install.html>`_.
--
GitLab