Skip to content
Snippets Groups Projects

update installation instructions

Merged update installation instructions
installation-instructions into master
Merged Joseph Weston requested to merge installation-instructions into master
Compare
and
1 file
+ 138
− 199
Compare changes
  • Side-by-side
  • Inline
content/install.rst
+ 138
− 199
@@ -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>`_.