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
Show latest version
1 file
+ 151
− 124
Compare changes
  • Side-by-side
  • Inline
content/install.rst
+ 151
− 124
@@ -18,8 +18,8 @@ language. If you are using a GNU/Linux operating system this should already be
installed on your computer.
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 "Quick
Install" section of the corresponding platform.
Python distribution yourself. Details of how to do this are in the
installation instructions of the corresponding platform.
**Kwant version 1.2 and newer requires at least Python 3.4**.
@@ -32,113 +32,34 @@ The instructions below assume Python 3. They should be also valid for Python
``python``, ``pip``.
Quick Install
=============
The quickest way to install Kwant is using the prepared packages that are
available for the following platforms:
Choose your plaform
===================
Installation instructions are available for the major operating systems:
+ `Ubuntu <#ubuntu-and-derivatives>`_
+ `Debian <#debian-and-derivatives>`_
+ `Arch Linux`_
+ `GNU/Linux`_
+ `Mac OS X`_
+ `Microsoft Windows`_
GNU/Linux
=========
Pre-built packages exist for the following distributions:
Advanced Install
================
Using ``conda``
---------------
If you are using the `Anaconda <https://www.continuum.io/downloads>`_ Python
distribution then you may readily install the latest stable version of kwant
and all of its depedencies from the ``conda-forge`` channel with by running the
following command in a terminal::
conda install -c conda-forge kwant
Conda packages are available for GNU/Linux and Mac OS X.
Similarly, the latest development build of Kwant may be installed from the
``kwant`` channel::
conda install -c kwant kwant
Using ``pip``
-------------
.. caution::
Installing Kwant with ``pip`` will *not* install any non-Python dependencies
such as `MUMPS <http://graal.ens-lyon.fr/MUMPS/>`_. These will need to be
installed in another way (see `Installing non-Python dependencies`_) prior
to installing Kwant with ``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 build
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``.
Installing non-Python dependencies
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
As mentioned above, ``pip`` will not install any non-Python dependencies. Kwant
has 3 non-Python dependencies:
+ 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` versions of the packages
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
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 may 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>`_ 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
Ubuntu and derivatives
======================
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::
+ `Debian <#debian-and-derivatives>`_
+ `Ubuntu <#ubuntu-and-derivatives>`_
+ `Arch Linux`_
sudo apt-add-repository -s ppa:kwant-project/ppa
sudo apt-get update
sudo apt-get install python3-kwant python-kwant-doc
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).
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``.
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
@@ -185,8 +106,23 @@ This method should work for all Debian-derived systems, even on exotic
architectures.
Ubuntu and derivatives
----------------------
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
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
``/usr/share/doc/python-kwant-doc``.
Arch Linux
==========
----------
`Arch install scripts for Kwant
<https://aur.archlinux.org/packages/python-kwant/>`_ are kindly provided by
@@ -204,54 +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.
Mac OS X packages for Kwant are available for the Conda package manager
that is included with the `Anaconda <https://www.continuum.io/downloads>`_
Python distribution.
1. Download and install the Python 3 version of
`Anaconda for Mac <https://www.continuum.io/downloads#macos>`_
2. Execute the following command in a terminal to install Kwant and all
of its dependencies::
conda install -c conda-forge kwant
If you do not want to install Anaconda (because you are already using another
Python distribution and do not want to change) then you will need to install
Kwant following the instructions in the `Advanced Install <#using-pip>`_ section.
If you do not want to use the ``conda`` packages, you can always install Kwant
using `pip`_. Or by directly `building from source`_.
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.
installation methods. We recommend that people use the ``conda`` packages
whenever possible.
Microsoft 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.
@@ -292,3 +219,103 @@ Now you are done, you can ``import kwant`` from within Python scripts.
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>`_.)
``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::
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
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
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``.
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.
As an example, on a Debian or Ubuntu system, the following
command will install the non-Python dependencies of Kwant::
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 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>`_.