Kwant can be installed either using prepared packages (Debian, Ubuntu, and Arch variants of GNU/Linux, Mac OS X, Microsoft Windows), or it can be built and installed from source.
In general, installation from packages is advisable, especially for novice users. Expert users may find it helpful to build Kwant from source, as this will also allow them to customize Kwant to use certain optimized versions of libraries.
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 “wheezy” and Debian “jessie”, but they may also work on many other recent Debian-derived sytems as well. (For example, the following works with recent Ubuntu versions.)
The lines prefixed with sudo have to be run as root.
Add the following lines to /etc/apt/sources.list:
deb http://downloads.kwant-project.org/debian/ stable main
deb-src http://downloads.kwant-project.org/debian/ stable main
(Optional) Add the OpenPGP key used to sign the repositories by executing:
sudo apt-key adv --keyserver pool.sks-keyservers.net --recv-key C3F147F5980F3535
The fingerprint of the key is 5229 9057 FAD7 9965 3C4F 088A C3F1 47F5 980F 3535.
Update the package data, and install Kwant:
sudo apt-get update
sudo apt-get install python-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.
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:
cd /tmp
sudo apt-get build-dep tinyarray
apt-get source --compile tinyarray
sudo dpkg -i python-tinyarray_*.deb
sudo apt-get build-dep kwant
apt-get source --compile kwant
sudo dpkg -i python-kwant_*.deb python-kwant-doc_*.deb
This method should work for virtually all Debian-derived systems, even on exotic architectures.
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
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 install scripts for Kwant are kindly provided by Jörg Behrmann (formerly by Max Schlemmer). To install, follow the Arch User Repository installation instructions. Note that for checking the validity of the package you need to add the key used for signing to your user’s keyring via:
gpg --keyserver pool.sks-keyservers.net --recv-key C3F147F5980F3535
The fingerprint of the key is 5229 9057 FAD7 9965 3C4F 088A C3F1 47F5 980F 3535.
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 and the MacPorts systems.
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.
Open a terminal and install homebrew as described on the homebrew homepage (instructions are towards the end of the page)
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 if you have Mac OS X 10.8 or higher.
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.
Install a few prerequisites
brew install gfortran python
Add additional repositories
brew tap homebrew/science
brew tap samueljohn/python
brew tap michaelwimmer/kwant
Install Kwant and its prerequisites
pip install nose
brew install numpy scipy matplotlib
brew install kwant
Notes:
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
- 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.
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.)
Execute
sudo port selfupdate
Now, install Kwant and its prerequisites
sudo port install py27-kwant
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:
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
Determine whether you have a 32-bit or 64-bit Windows installation by following these instructions.
Download and install Python 2.7 for the appropriate architecture (32-bit or 64-bit) from the official Python download site.
Open a command prompt, as described in “How do I get a command prompt” at the Microsoft Windows website.
In the command prompt window, execute:
C:\Python27\python.exe C:\Python27\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:\Python27 by the actual location where Python is installed.
Reboot your computer.
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. For Kwant, we recommend to download at least NumPy, SciPy, Matplotlib, Nose, Tinyarray, and Kwant itself.
Now open a command prompt with administrator rights, as described in “How do I run a command with elevated permissions” at the Microsoft Windows website.
In this new command prompt window, execute
pip install <filename>
for each of the downloaded files (replacing <filename> with it).
Now you are done, you can import kwant from within Python scripts.
(Note that many other userful scientific packages are available in Gohlke’s repository. For example, you might want to install IPython and its various dependencies so that you can use the IPython notebook.)
In addition, to build a copy of Kwant that has been checked-out directly from its Git repository, you will also need Cython 0.22 or newer. You do not need Cython to build Kwant that has been unpacked from a source .tar.gz-file.
Kwant can be built and installed following the usual Python conventions by running the following commands in the root directory of the Kwant distribution.
pip install .
Depending on your system, you might have to run the second command with administrator privileges (e.g. prefixing it with sudo). If you use Python older than 2.7.9, see pip installation instructions.
After installation, tests can be run with:
python -c 'import kwant; kwant.test()'
The tutorial examples can be found in the directory tutorial inside the root directory of the Kwant source distribution.
Kwant should run on all recent Unix-like systems. The following instructions have been verified to work on Debian 7 (Wheezy) or newer, and on Ubuntu 12.04 or newer. For other distributions step 1 will likely have to be adapted. If Ubuntu-style sudo is not available, the respective command must be run as root.
Install the required packages. On Debian-based systems like Ubuntu this can be done by running the command
sudo apt-get install python-dev python-scipy python-matplotlib python-nose g++ gfortran libopenblas-dev liblapack-dev libmumps-scotch-dev
Unpack Tinyarray, enter its directory. To build and install, run
sudo pip install .
Inside the Kwant source distribution’s root directory run
sudo pip install .
By default the package will be installed under /usr/local. Type pip help install for installation options and see pip documentation for a detailed description of pip.
The required dependencies of Kwant are best installed with one of the packaging systems. Here we only consider the case of MacPorts in detail. Some remarks for homebrew are given below.
In order to set up MacPorts or homebrew, follow steps 1 - 3 of the respective instructions of MacPorts
Install the required dependencies:
sudo port install gcc47 python27 py27-numpy py27-scipy py27-matplotlib mumps_seq
sudo port select --set python python27
Unpack Tinyarray, enter its directory, build and install:
python setup.py build
sudo python setup.py install
Unpack Kwant, go to the Kwant directory, and edit build.conf to read:
[lapack]
extra_link_args = -Wl,-framework -Wl,Accelerate
[mumps]
include_dirs = /opt/local/include
library_dirs = /opt/local/lib
libraries = zmumps_seq mumps_common_seq pord_seq esmumps scotch scotcherr mpiseq gfortran
Then, build and install Kwant.
CC=gcc-mp-4.7 LDSHARED='gcc-mp-4.7 -shared -undefined dynamic_lookup' python setup.py build
sudo python setup.py install
You might note that installing Kwant on Mac OS X is somewhat more involved than installing on Linux. Part of the reason is that we need to mix Fortran and C code in Kwant: While C code is usually compiled using Apple compilers, Fortran code must be compiled with the Gnu Fortran compiler (there is no Apple Fortran compiler). For this reason we force the Gnu compiler suite with the environment variables CC and LDSHARED as shown above.
It is also possible to build Kwant using homebrew. The dependencies can be installed as
brew install gcc python
brew tap homebrew/science
brew tap homebrew/python
brew tap michaelwimmer/kwant
pip install nose six
brew install numpy scipy matplotlib
Note that during the installation you will be told which paths to add when you want to compile/link against scotch/metis/mumps; you need to add these to the build.conf file. Also, when linking against mumps, one needs also to link against metis (in addition to the libraries needed for MacPorts).
Our efforts to compile Kwant on Windows using only free software (MinGW) were only moderately successful. At the end of a very complicated process we obtained packages that worked, albeit unreliably. As the only recommended way to compile Python extensions on Windows is using Visual C++, it may well be that there exists no easy solution.
It is possible to compile Kwant on Windows using non-free compilers, however we (the authors of Kwant) have no experience with this. The existing Windows binary installers of Kwant and Tinyarray were kindly prepared by Christoph Gohlke.
The setup script of Kwant has to know how to link against LAPACK & BLAS, and, optionally, MUMPS. By default it will assume that LAPACK and BLAS can be found under their usual names. MUMPS will be not linked against by default, except on Debian-based systems when the package libmumps-scotch-dev is installed.
All these settings can be configured by creating/editing the file build.conf in the root directory of the Kwant distribution. This configuration file consists of sections, one for each dependency, led by a [dependency-name] header and followed by name = value entries. Possible names are keyword arguments for distutils.core.Extension (For a complete list, see its documentation). The corresponding values are whitespace-separated lists of strings.
The two currently possible sections are [lapack] and [mumps]. The former configures the linking against LAPACK _AND_ BLAS, the latter against MUMPS (without LAPACK and BLAS).
Example build.conf for linking Kwant against a self-compiled MUMPS, SCOTCH and METIS:
[mumps]
libraries = zmumps mumps_common pord metis esmumps scotch scotcherr mpiseq
gfortran
Example build.conf for linking Kwant with Intel MKL.:
[lapack]
libraries = mkl_intel_lp64 mkl_sequential mkl_core mkl_def
library_dirs = /opt/intel/mkl/lib/intel64
extra_link_args = -Wl,-rpath=/opt/intel/mkl/lib/intel64
The detailed syntax of build.conf is explained in the documentation of Python’s configparser module.
To build the documentation, the Sphinx documentation generator is required with numpydoc extension (version 0.5 or newer). If PDF documentation is to be built, the tools from the libRSVG (Debian/Ubuntu package librsvg2-bin) are needed to convert SVG drawings into the PDF format.
As a prerequisite for building the documentation, Kwant must have been built successfully using ./setup.py build as described above (or Kwant must be already installed in Python’s search path). HTML documentation is built by entering the doc subdirectory of the Kwant package and executing make html. PDF documentation is generated by executing make latex followed by make all-pdf in doc/build/latex.
Because of some quirks of how Sphinx works, it might be necessary to execute make clean between building HTML and PDF documentation. If this is not done, Sphinx may mistakenly use PNG files for PDF output or other problems may appear.