INSTALL.rst 11.7 KB
Newer Older
1
2
3
=====================
Installation of Kwant
=====================
4

5
6
Ready-to-use Kwant packages are available for many platforms (like GNU/Linux,
Mac OS X, Microsoft Windows).  See the `installation page of the Kwant website
7
<https://kwant-project.org/install>`_ for instructions on how to install Kwant
8
on your platform.  This is the recommended way for new users.
9

10
11
The remainder of this section documents how to build Kwant from source.  This
information is mostly of interest to contributors and packagers.
12
13


14
15
16
********************
Generic instructions
********************
17

18
19
20
21
22
23
24
25
26
27
Obtaining the source code
=========================

Source distributions of Kwant (and Tinyarray) are available at the `downloads
section of the Kwant website <https://downloads.kwant-project.org/kwant/>`_ as well
as `PyPI <https://pypi.python.org/pypi/kwant>`_.  The sources may be also
cloned directly from the `official Kwant git repository
<https://gitlab.kwant-project.org/kwant/kwant>`_.


28
29
30
Prerequisites
=============

31
Building Kwant requires
32
 * `Python <https://www.python.org/>`_ 3.4 or above (Kwant 1.1 is the last
33
   version to support Python 2),
34
 * `NumPy <http://numpy.org/>`_ 1.8.1 or newer,
Anton Akhmerov's avatar
Anton Akhmerov committed
35
 * `SciPy <https://scipy.org/>`_ 0.13.3 or newer,
36
37
 * `LAPACK <http://netlib.org/lapack/>`_ and `BLAS <http://netlib.org/blas/>`_,
   (For best performance we recommend the free `OpenBLAS
38
39
   <http://www.openblas.net/>`_ or the nonfree `MKL
   <https://software.intel.com/en-us/intel-mkl>`_.)
Christoph Groth's avatar
Christoph Groth committed
40
 * `Tinyarray <https://gitlab.kwant-project.org/kwant/tinyarray>`_, a NumPy-like
Anton Akhmerov's avatar
Anton Akhmerov committed
41
   Python package optimized for very small arrays,
42
 * An environment which allows to compile Python extensions written in C and
43
44
45
   C++.

The following software is highly recommended though not strictly required:
46
47
 * `matplotlib <http://matplotlib.org/>`_ 1.3.1 or newer, for the module `kwant.plotter` and the tutorial,
 * `SymPy <http://sympy.org/>`_ 0.7.6 or newer, for the subpackage `kwant.continuum`.
48
 * `MUMPS <http://graal.ens-lyon.fr/MUMPS/>`_, a sparse linear algebra library
49
50
51
52
   that will in many cases speed up Kwant several times and reduce the memory
   footprint.  (Kwant uses only the sequential, single core version
   of MUMPS.  The advantages due to MUMPS as used by Kwant are thus independent
   of the number of CPU cores of the machine on which Kwant runs.)
53
 * The `py.test testing framework <http://pytest.org/>`_ for running the
54
   tests included with Kwant.
55

56
In addition, to build a copy of Kwant that has been checked-out directly from
Christoph Groth's avatar
Christoph Groth committed
57
58
59
version control, you will also need `Cython <http://cython.org/>`_ 0.22 or
newer.  You do not need Cython to build Kwant that has been unpacked from a
source .tar.gz-file.
60

61

62
63
Building and installing Kwant
=============================
64

65
Kwant can be built and installed following the `usual Python conventions
66
67
<https://docs.python.org/3/install/index.html>`_ by running the following
commands in the root directory of the Kwant distribution. ::
68

69
70
    python3 setup.py build
    python3 setup.py install
71
72

Depending on your system, you might have to run the second command with
73
administrator privileges (e.g. prefixing it with ``sudo``).
74

75
After installation, tests can be run with::
76

77
    python3 -c 'import kwant; kwant.test()'
78

79
The tutorial examples can be found in the directory ``tutorial`` inside the root
80
directory of the Kwant source distribution.
81

82
83
84
85
86
87
(Cython will be run automatically when the source tree has been checked out of
version control.  Kwant tarballs include the Cython-generated files, and
cythonization is disabled when building not from git.  If ever necessary, this
default can be overridden by giving the ``--cython`` option to setup.py.)


88
89
.. _build-configuration:

90
91
92
Build configuration
===================

93
94
95
96
97
98
Kwant contains several extension modules.  The compilation and linking of these
modules can be configured by editing a build configuration file.  By default,
this file is ``build.conf`` in the root directory of the Kwant distribution.  A
different path may be provided using the ``--configfile=PATH`` option.

This configuration file consists of
Christoph Groth's avatar
Christoph Groth committed
99
sections, one for each extension module that is contained in Kwant, led by a
100
101
102
103
104
105
106
107
108
``[section name]`` header and followed by ``key = value`` lines.

The sections bear the names of the extension modules, for example
``[kwant.operator]`` or ``[kwant.linalg.lapack]``.  There can be also a
``[DEFAULT]`` section that provides default values for all extensions, also
those not explicitly present in the file.

Possible keys are the keyword arguments for ``distutils.core.Extension`` (For a
complete list, see its `documentation
109
<https://docs.python.org/3/distutils/apiref.html#distutils.core.Extension>`_).
110
111
The corresponding values are whitespace-separated lists of strings.

112
113
Example ``build.conf`` for compiling Kwant with C assertions and Cython's line
trace feature::
114
115
116

    [DEFAULT]
    undef_macros = NDEBUG
117
    define_macros = CYTHON_TRACE=1
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

Kwant must be linked against LAPACK & BLAS, and, optionally, MUMPS.  The main
application of build configuration is adopting the build process to the various
(deployment) variants of these libraries.  By default ``setup.py`` assumes 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.

The sections ``[kwant.linalg.lapack]`` and ``[kwant.linalg._mumps]`` may be
used to adapt the build process.  (For simplicity and backwards compatibility,
``[lapack]`` and ``[mumps]`` are aliases for the above.)

The section ``[lapack]`` configures the linking against LAPACK _AND_ BLAS, the
section ``[mumps]`` against MUMPS.  The contents of ``[lapack]`` are
appended to the configuration for MUMPS itself needs LAPACK and BLAS as well.
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

Example ``build.conf`` for linking Kwant against a self-compiled MUMPS, `SCOTCH
<http://www.labri.fr/perso/pelegrin/scotch/>`_ and `METIS
<http://glaros.dtc.umn.edu/gkhome/metis/metis/overview>`_::

    [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
150
<https://docs.python.org/3/library/configparser.html#supported-ini-file-structure>`_.
151
152
153
154
155
156


Building the documentation
==========================

To build the documentation, the `Sphinx documentation generator
157
<http://www.sphinx-doc.org/en/stable/>`_ is required with ``numpydoc`` extension
158
(version 0.5 or newer).  If PDF documentation is to be built, the tools
Anton Akhmerov's avatar
Anton Akhmerov committed
159
from the `libRSVG <https://wiki.gnome.org/action/show/Projects/LibRsvg>`_ (Debian/Ubuntu package
160
161
162
``librsvg2-bin``) are needed to convert SVG drawings into the PDF format.

As a prerequisite for building the documentation, Kwant must have been built
163
successfully using ``python3 setup.py build`` as described above (or Kwant must
164
165
166
167
168
169
170
171
172
173
174
175
176
177
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.


****************************
Hints for specific platforms
****************************
178

179
Unix-like systems (GNU/Linux)
180
=============================
181

182
Kwant should run on all recent Unix-like systems.  The following instructions
183
have been verified to work on Debian 8 (Jessie) or newer, and on Ubuntu 14.04 or
184
185
186
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.
187

188
189
1. Install the required packages.  On Debian-based systems like Ubuntu this can
   be done by running the command ::
190

Anton Akhmerov's avatar
Anton Akhmerov committed
191
       sudo apt-get install python3-dev python3-scipy python3-matplotlib python3-pytest g++ gfortran libopenblas-dev liblapack-dev libmumps-scotch-dev
192

193
2. Unpack Tinyarray, enter its directory. To build and install, run ::
194

195
196
       python3 setup.py build
       sudo python3 setup.py install
197

198
3. Inside the Kwant source distribution's root directory run ::
199

200
201
       python3 setup.py build
       sudo python3 setup.py install
202

203
By default the package will be installed under ``/usr/local``.  Run ``python3
204
setup.py --help install`` for installation options.
205
206


207
208
Mac OS X: MacPorts
==================
209

210
211
212
The following instructions are valid for Kwant 1.1 with Python 2.7.  They need
to be updated for Kwant 1.2.  (Help is welcome.)

Michael Wimmer's avatar
Michael Wimmer committed
213
The required dependencies of Kwant are best installed with one of the packaging
214
systems. Here we only consider the case of `MacPorts
215
<https://www.macports.org>`_ in detail. Some remarks for homebrew are given
216
below.
217

218
1. Install a recent version of MacPorts, as explained in the `installation
Anton Akhmerov's avatar
Anton Akhmerov committed
219
   instructions of MacPorts <https://www.macports.org/install.php>`_.
220

221
2. Install the required dependencies::
222

223
       sudo port install gcc47 python27 py27-numpy py27-scipy py27-matplotlib mumps_seq
224
       sudo port select --set python python27
225

226
3. Unpack Tinyarray, enter its directory, build and install::
227
228
229
230

       python setup.py build
       sudo python setup.py install

231
p5. Unpack Kwant, go to the Kwant directory, and edit ``build.conf`` to read::
232

233
234
       [lapack]
       extra_link_args = -Wl,-framework -Wl,Accelerate
235
       [mumps]
236
237
238
       include_dirs = /opt/local/include
       library_dirs = /opt/local/lib
       libraries = zmumps_seq mumps_common_seq pord_seq esmumps scotch scotcherr mpiseq gfortran
239

240
6. Then, build and install Kwant. ::
241

242
       CC=gcc-mp-4.7 LDSHARED='gcc-mp-4.7 -shared -undefined dynamic_lookup' python setup.py build
243
244
       sudo python setup.py install

Christoph Groth's avatar
Christoph Groth committed
245
You might note that installing Kwant on Mac OS X is somewhat more involved than
246
247
248
249
250
251
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.

252

253
254
Mac OS X: homebrew
==================
255

256
257
258
The following instructions are valid for Kwant 1.1 with Python 2.7.  They need
to be updated for Kwant 1.2.  (Help is welcome.)

Michael Wimmer's avatar
Michael Wimmer committed
259
It is also possible to build Kwant using homebrew. The dependencies can be
260
261
installed as ::

262
    brew install gcc python
263
    brew tap homebrew/science
264
    brew tap homebrew/python
265
    brew tap kwant-project/kwant
Anton Akhmerov's avatar
Anton Akhmerov committed
266
    pip install pytest pytest-runner six
267
268
269
270
    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
271
272
build.conf file. Also, when linking against MUMPS, one needs also to link
against METIS (in addition to the libraries needed for MacPorts).
273
274


275
276
Microsoft Windows
=================
277
278
279
280
281
282
283
284
285
286
287

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.