Skip to content
Snippets Groups Projects
Commit b208440b authored by Christoph Groth's avatar Christoph Groth
Browse files

update installation instructions

parent d1a2e232
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 89 additions and 25 deletions
content/install.rst
+ 89
− 25
View file @ b208440b
...@@ -2,24 +2,42 @@ ...@@ -2,24 +2,42 @@
Downloading and installing Kwant Downloading and installing Kwant
================================ ================================
Overview of available methods
=============================
The quickest and easiest way to install Kwant is using the prepared packages The quickest and easiest way to install Kwant is using the prepared packages
that are available for GNU/Linux (`Debian <#debian-and-derivatives>`_, `Ubuntu that are available for GNU/Linux (`Debian <#debian-and-derivatives>`_, `Ubuntu
<#ubuntu-and-derivatives>`_, and their variants, `Arch Linux`_), `Mac OS X`_, <#ubuntu-and-derivatives>`_, and their variants, `Arch Linux`_), `Mac OS X`_,
and `Microsoft Windows`_. It is possible to be notified about new releases of and `Microsoft Windows`_.
Kwant through an `announcement mailing list
<community.html#announcements-of-new-releases>`_. 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 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 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 Kwant to use certain optimized versions of libraries), please consult the
installation instructions documentation on `how to install Kwant from source <doc/1/pre/install.html>`_.
<doc/1/pre/install.html#building-and-installing-from-source>`_ in the
documentation.
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 The instructions below assume Python 3. They should be also valid for Python
<http://downloads.kwant-project.org/kwant/>`_. You can follow the development 2 if all occurrences of ``python3``, ``pip3``, etc. are replaced by
by browsing or cloning the `Git repository of Kwant ``python``, ``pip``.
<https://gitlab.kwant-project.org/kwant/kwant>`_.
Debian and derivatives Debian and derivatives
...@@ -48,7 +66,7 @@ The lines prefixed with ``sudo`` have to be run as root. ...@@ -48,7 +66,7 @@ The lines prefixed with ``sudo`` have to be run as root.
3. Update the package data, and install Kwant:: 3. Update the package data, and install Kwant::
sudo apt-get update 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 The ``python-kwant-doc`` package is optional and installs the HTML
documentation of Kwant in the directory ``/usr/share/doc/python-kwant-doc``. documentation of Kwant in the directory ``/usr/share/doc/python-kwant-doc``.
...@@ -61,13 +79,13 @@ surprisingly easy:: ...@@ -61,13 +79,13 @@ surprisingly easy::
sudo apt-get build-dep tinyarray sudo apt-get build-dep tinyarray
apt-get source --compile tinyarray apt-get source --compile tinyarray
sudo dpkg -i python-tinyarray_*.deb sudo dpkg --install python3-tinyarray_*.deb
sudo apt-get build-dep kwant sudo apt-get build-dep kwant
apt-get source --compile 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. architectures.
...@@ -78,7 +96,7 @@ Execute the following commands:: ...@@ -78,7 +96,7 @@ Execute the following commands::
sudo apt-add-repository ppa:kwant-project/ppa sudo apt-add-repository ppa:kwant-project/ppa
sudo apt-get update 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 This should provide Kwant for all versions of Ubuntu >= 12.04. The HTML
documentation will be installed locally in the directory documentation will be installed locally in the directory
...@@ -88,9 +106,12 @@ documentation will be installed locally in the directory ...@@ -88,9 +106,12 @@ documentation will be installed locally in the directory
Arch Linux Arch Linux
========== ==========
Arch install scripts for Kwant are kindly provided by Jörg Behrmann (formerly *(This section still targets Python 2 and needs to be updated for Python 3.)*
by Max Schlemmer). To install, follow the `Arch User Repository installation
instructions ‘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>`_. <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 Note that for checking the validity of the package you need to add the key
used for signing to your user's keyring via:: 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 ...@@ -113,6 +134,8 @@ Kwant and its dependencies both via the `homebrew <http://brew.sh>`_ and the
Mac OS X: homebrew 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 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 lightweight, tries to be as minimalistic as possible and give the user
freedom than Macports. We recommend this option if you have no preferences. freedom than Macports. We recommend this option if you have no preferences.
...@@ -182,6 +205,8 @@ Notes: ...@@ -182,6 +205,8 @@ Notes:
Mac OS X: MacPorts 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 MacPorts is a full-fledged package manager that recreates a whole Linux-like
environment on your Mac. environment on your Mac.
...@@ -268,8 +293,8 @@ provided by Christoph Gohlke. To install Kwant on Windows ...@@ -268,8 +293,8 @@ provided by Christoph Gohlke. To install Kwant on Windows
5. Reboot your computer. 5. Reboot your computer.
6. Download the necessary packages (with the ending ``.whl``) for your 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 operating system (32 or 64 bit) and Python version (e.g. ``cp34`` for Python
2.7) from the website of `Christoph Gohlke 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. <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 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 ...@@ -278,13 +303,52 @@ provided by Christoph Gohlke. To install Kwant on Windows
In this new command prompt window, execute :: In this new command prompt window, execute ::
pip install <filename> pip3 install --no-deps *.whl
for each of the downloaded files (replacing ``<filename>`` with it).
(This will install all the wheel-files in the current directory.)
Now you are done, you can ``import kwant`` from within Python scripts. 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 repository. For example, you might want to install `IPython
<http://www.lfd.uci.edu/~gohlke/pythonlibs/#ipython>`_ and its various <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>`_.) 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>`_.
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