Commit 2a1bfc72 authored by Christoph Groth's avatar Christoph Groth

split README file, rework introduction and installation instructions

parent c5f06a58
=============================
Building and installing kwant
=============================
Prerequisites
=============
Building kwant requires
- `Python <http://python.org>`_ 2.6 or newer;
- `SciPy <http://scipy.org>`_ 0.7.2 or newer;
- `LAPACK <http://netlib.org/lapack/>`_ and `BLAS <http://netlib.org/blas/>`_;
- tinyarray, a NumPy-like Python package optimized for very small arrays;
- An environment which allows to compile Python extensions written in C and
C++.
The following software is highly recommended though not strictly required:
- `matplotlib <http://matplotlib.sourceforge.net/>`_, for kwant's plotting
module and the tutorial;
- `MUMPS <http://graal.ens-lyon.fr/MUMPS/>`_, a sparse linear algebra library
that will in many cases speed up kwant several times and reduce the memory
footprint.
Suggested:
- The `nose <http://nose.readthedocs.org/>`_ testing framework is required to
run the extensive tests included with kwant.
Generic instructions
====================
kwant can be built and installed following the `usual Python conventions
<http://docs.python.org/install/index.html>`_ by running the following commands
in the root directory of the kwant distribution. ::
python setup.py build
python setup.py install
Depending on your system, you might have to run the second command with
administrator privileges (e.g. prefixing it with ``sudo``).
To check successful installation try executing some scripts in the ``tutorial``
subdirectory, e.g.::
cd tutorial
python 1-quantum_wire_revisited.py
If "nose" is installed, you can also run the tests ::
python -c 'import kwant; kwant.test()'
from some directory *other* than the kwant distribution's root directory.
System-specific instructions
============================
Unix-like systems (Linux)
-------------------------
1. Install the required software. On Debian/Ubuntu-like systems this can be
done by running ::
sudo apt-get install python-dev scipy-dev g++ libmumps-scotch-dev python-matplotlib python-nose
2. Unpack tinyarray, enter its directory, build and install. ::
python setup.py build
sudo python setup.py install
3. Inside the kwant source distribution's root directory run ::
python setup.py build
sudo python setup.py install
By default the package will be installed under ``/usr/local``. You can
change this using the ``--prefix`` option, e.g.::
sudo python setup.py install --prefix=/opt
If you would like to install kwant into your home directory only you can use ::
python setup.py install --home=~
This does not require root privileges. If you install kwant in this way
be sure to tell python where to find it. This can be done by setting the
``PYTHONPATH`` environment variable::
export PYTHONPATH=$HOME/lib/python
You can make this setting permanent by adding this line to the file
``.bashrc`` (or equivalent) in your home directory.
Mac OS X
--------
(Please help to improve these instructions.)
These are instructions for installing kwant on Mac computers using the software
MacPorts. MacPorts allows to download and install a large number of
open-source software packages. There exist also other ways to install the
required libraries.
Following these instructions will install kwant without `MUMPS
<http://graal.ens-lyon.fr/MUMPS/>`_. With MUMPS kwant will run several times
faster and will use less memory.
These instructions were verified in November 2011 under Mac OS X 10.6.8.
1. Install a fresh version of Xcode (Apple's development environment).
2. Install `MacPorts <http://www.macports.org/>`_. After installation, you
probably want to update its data base with ::
sudo port selfupdate
3. OPTIONAL: Install a more recent gcc compiler::
sudo port install mp-gcc44
(``port search gcc`` will give you the available versions) and set it as
your default ::
sudo port select --set gcc mp-gcc44
(``port select gcc`` will give you the possible choices)
4. Install the required packages::
sudo port install python27
sudo port install py27-scipy
sudo port install py27-matplotlib
5. You might need to modify the matplotlib configuration file::
> python
>>> import matplotlib
>>> matplotlib.matplotlib_fname()
'/Users/username/.matplotlib/matplotlibrc'
Edit the corresponding ``matplotlibrc`` configuration file, look for the
line starting with backend and modify it to::
backend : MacOSX
6. Set python 2.7 as your default. ::
sudo port select --set python python27
7. Unpack tinyarray, enter its directory, build and install. ::
python setup.py build
sudo python setup.py install
8. Go to the kwant directory, build and install. ::
python setup.py build
sudo python setup.py install
Microsoft Windows
-----------------
It should be possible to run kwant under Microsoft Windows but so far no one
has tried hard enough. We will happily include Windows-specific installation
instructions in this document once someone contributes them.
A good starting point should be the `free edition of the Enthought Python
Distribution <http://www.enthought.com/products/epd_free.php>`_.
Build configuration
===================
The setup script of kwant has to know how to link against LAPACK & BLAS, and,
optionally, MUMPS. Be 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 the third table from top of `this document
<http://docs.python.org/distutils/apiref.html>`_). 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
<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
Building the documentation
==========================
To build the documentation, kwant has to be installed as described above.
Additionally, the `sphinx documentation generator <http://sphinx.pocoo.org/>`_
is required.
HTML documentation can be built by entering the ``doc`` subdirectory of the
kwant package and executing ``make html``. PDF documentation is generated by
executing ``make latex`` followed by a ``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 might mistakenly use PNG files for PDF output.
Hacking
=======
To work on kwant itself it is useful to build it in-place. This can be done
with the following command ::
python setup.py build_ext -i
The ``kwant`` subdirectory of the source distribution will be thus turned into
a proper python package which can be imported. To be able to import kwant from
within python, one can either work in the root directory of the distribution
(where the subdirectory ``kwant`` is located), or make a (symbolic) link from
somewhere in the Python search path to the the package subdirectory.
Some conventions to keep in mind:
* Write tests for all the important functionality you add. Be sure not to
break existing tests.
* Please keep the code consistent by adhering to the prevailing naming and
formatting conventions. We generally follow the `"Style Guide for Python
Code" <http://www.python.org/dev/peps/pep-0008/>`_ For docstrings, we follow
`NumPy's "Docstring Standard"
<http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_ and
`Python's "Docstring Conventions"
<http://www.python.org/dev/peps/pep-0257/>`_.
Several modules are written in `Cython <http://cython.org/>`_ (.pyx file name
extension). You will need Cython 0.17.1 if you want to modify them.
kwant includes extensive unit tests which are supposed to cover all of its
functionality. We use the `nose <http://nose.readthedocs.org/>`_ testing
framework. To run the tests, execute the command ``nosetests`` from the root
directory of the package after it has been built in place. You can also
``import kwant`` inside Python and run ``kwant.test()``.
License
=======
This software (kwant) is NOT TO BE DISTRIBUTED, neither in part nor as a whole.
The only exception to this is the ``doc/sphinxext`` subdirectory, which is free
software. (See the file ``LICENSE.txt`` in that subdirectory.)
=============================================================
kwant, a package for numerical quantum transport calculations
=============================================================
Licence
=======
This software is NOT TO BE DISTRIBUTED, neither in part nor as a whole.
The only exception to this is the ``doc/sphinxext`` subdirectory, which is free
software. (See the file ``LICENSE.txt`` in that subdirectory.)
Installation from source
========================
The prerequisites are
- More or less current versions of `Python <http://python.org>`_ and `SciPy
<http://scipy.org>`_. Python 2.6 and scipy 0.7.2 should be enough.
- An environment which allows to compile Python extensions written in C and
C++. This includes a C/C++ compiler and Python C headers. The latter might
be provided in a separate package like ``python-dev``.
- Some incarnation of `LAPACK <http://www.netlib.org/lapack/>`_.
Recommended:
- `MUMPS <http://graal.ens-lyon.fr/MUMPS/>`_ will in many cases speed up kwant
several times and reduce the memory footprint.
- `pycairo <http://cairographics.org/pycairo/>`_
- `matplotlib <http://matplotlib.sourceforge.net/>`_
kwant can be built and installed using distutils, following standard Python
conventions. To build and install, run the following commands in the root
directory of the package. ::
python setup.py build
python setup.py install
The second command has to be run as root (e.g. prefixing it with ``sudo``). By
default the package will be installed under ``/usr/local``. You can change
this using the ``--prefix`` option, e.g.::
python setup.py install --prefix=/opt
If you would like to install kwant into your home directory only you can use ::
python setup.py install --home=~
This does not require superuser priviledges. If you install kwant in this way
be sure to tell python where to find it. This can be done by setting the
``PYTHONPATH`` environment variable::
export PYTHONPATH=$HOME/lib/python
You can make this setting permanent by adding this line to the file
``.bashrc`` in your home directory.
To check successful installation try executing some scripts in the ``examples``
subdirectory.
Documentation
=============
To build the documentation, kwant has to be installed as described in the
previous section. The `sphinx documentation generator
<http://sphinx.pocoo.org/>`_ is required.
HTML documentation can be built by entering the ``doc`` subdirectory of the
kwant package and executing ``make html``. PDF documentation is generated by
executing ``make latex`` followed by a ``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 might mistakenly use PNG files for PDF output.
Please consult the documentation for further information on how to use kwant.
Hacking
=======
To work on kwant itself it is useful to build it in-place. This can be done
with the following command ::
python setup.py build_ext -i
The ``kwant`` subdirectory of the source distribution will be thus turned into
a proper python package which can be imported. To be able to import kwant from
within python, one can either work in the root directory of the distribution
(where the subdirectory ``kwant`` is located), or make a (symbolic) link from
somewhere in the Python search path to the the package subdirectory.
Some conventions to keep in mind:
* Write tests for all the important functionality you add. Be sure not to
break existing tests.
* Please keep the code consistent by adhering to the prevailing naming and
formatting conventions. We generally follow the `"Style Guide for Python
Code" <http://www.python.org/dev/peps/pep-0008/>`_ For docstrings, we follow
`NumPy's "Docstring Standard"
<http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_ and
`Python's "Docstring Conventions"
<http://www.python.org/dev/peps/pep-0257/>`_.
Several modules are written in `Cython <http://cython.org/>`_ (.pyx file name
extension). You will need Cython 0.17.1 if you want to modify them.
Tests
=====
kwant includes extensive unit tests which are supposed to cover all of its
functionality. We use the `nose
<http://somethingaboutorange.com/mrl/projects/nose/>`_ testing framework. To
run the tests, execute the command ``nosetests`` from the root directory of the
package after it has been built in place.
kwant is a Python package for numerical quantum transport calculations. It
aims to be an user-friendly, powerful and efficient toolbox for the simulation
of physical systems governed by tight-binding Hamiltonians. It is currently
suitable for calculations of Landauer transport (conductance, noise),
dispersion relations, modes, wavefunctions, various Green functions, local
density of states.
See the file INSTALL.txt for installation instructions and LICENSE.txt for
legal information. Complete reference documentation and a tutorial are also
available.
......@@ -2,10 +2,18 @@
kwant documentation
===================
.. include:: ../../README.txt
:end-before: See the file INSTALL.txt
.. toctree::
:maxdepth: 1
Installation instructions <install>
.. toctree::
:maxdepth: 1
README file (includes installation instructions) <readme>
license
.. toctree::
:maxdepth: 1
......
.. include:: ../../INSTALL.txt
.. include:: ../../LICENSE.txt
.. include:: ../../README.txt
Introduction
============
kwant is currently suitable for calculating Landauer transport and
calculating dispersions of various tight binding systems. Possible future
extensions are calculations of local density of states, supercurrent, of
various transport properties like Wigner-Smith delay time or Goos-Hänchen
shift, Boltzmann transport, etc.
There are two steps in obtaining a numerical solution to a problem: The first
is defining the problem in a computer-accessible way, the second solving it.
The aim of a software package like kwant is to make both steps easier.
......
Markdown is supported
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