.coveragerc

+[run]
+plugins = Cython.Coverage
+omit =
+     */tests/*
+     kwant/graph/dissection.py
+     kwant/_kwant_version.py
+     */__init__.py
+branch = True
+[report]
+exclude_lines =
+    skip coverage
+    @abc.abstractmethod
+    @abc.abstractproperty

.gitattributes

+kwant/_kwant_version.py export-subst

.gitignore

 *~
-MANIFEST
 *.pyc
+*.pyo
 *.so
+*.pyd
 /kwant/*.c
 /kwant/*/*.c
-/kwant/_static_version.py
-/tutorial
 /build
 /dist
 /doc/build
 /doc/source/reference/generated/
-/doc/source/images/*.png
-/doc/source/images/*.pdf
-/doc/source/images/.*_flag
-/doc/source/images/[a-zA-Z]*.py
+/doc/source/figure/*.pdf
 /build.conf
+/kwant.egg-info/
+/MANIFEST.in
+.cache/
+.coverage
+.eggs/
+htmlcov/
+.ipynb_checkpoints/

.gitlab-ci.yml

+image: gitlab.kwant-project.org:5005/kwant/kwant
+
+stages:
+  - build-env
+  - build
+  - test
+  - deploy
+  - release
+
+before_script:
+  # Here and below, a workaround for gitlab runner not fetching tags
+  # See https://gitlab.com/gitlab-org/gitaly/-/issues/2221
+  - git config --global --add safe.directory /builds/kwant/kwant
+  - git fetch --tags
+
+variables:
+  # rsync is used to send documentation to our web servers: we never send any
+  # secret information, and using 'ssh-keyscan' causes the CI server's IP to be blacklisted
+  SSH_COMMAND: "ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null"
+  # Turn off threading to avoid slowdowns
+  OPENBLAS_NUM_THREADS : 1
+  OMP_NUM_THREADS : 1
+  MKL_DYNAMIC : FALSE
+  MKL_NUM_THREADS : 1
+
+## Building Docker environments
+## Only runs when docker specifications change
+
+.build-env:
+  stage: build-env
+  when: manual
+  image:
+    name: gcr.io/kaniko-project/executor:debug
+    entrypoint: [""]
+  before_script:
+    - mkdir -p /kaniko/.docker
+    - echo "{\"auths\":{\"$CI_REGISTRY\":{\"username\":\"$CI_REGISTRY_USER\",\"password\":\"$CI_REGISTRY_PASSWORD\"}}}" > /kaniko/.docker/config.json
+    - git config --global --add safe.directory /builds/kwant/kwant
+    - git fetch --tags
+
+build-env:ubuntu:
+  extends: .build-env
+  script:
+    - /kaniko/executor
+      --context $CI_PROJECT_DIR/docker
+      --dockerfile $CI_PROJECT_DIR/docker/Dockerfile.ubuntu
+      --destination $CI_REGISTRY_IMAGE/ubuntu
+
+build-env:debian:
+  extends: .build-env
+  script:
+    - /kaniko/executor
+      --context $CI_PROJECT_DIR/docker
+      --dockerfile $CI_PROJECT_DIR/docker/Dockerfile.debian
+      --destination $CI_REGISTRY_IMAGE/debian
+
+build-env:default:
+  extends: .build-env
+  script:
+    - /kaniko/executor
+      --context $CI_PROJECT_DIR/docker
+      --dockerfile $CI_PROJECT_DIR/docker/Dockerfile.conda
+      --destination $CI_REGISTRY_IMAGE
+
+
+## Build environment specifications
+
+.build:
+  stage: build
+  script:
+    - echo -e "[DEFAULT]\ndefine_macros = CYTHON_TRACE=1 NPY_NO_DEPRECATED_API=NPY_1_7_API_VERSION" >build.conf
+    - ./setup.py build
+    - ./setup.py build_ext -i
+  artifacts:
+    untracked: true
+    expire_in: 2 hour
+
+
+.stable-env:
+  before_script:
+    - eval "$(micromamba shell hook --shell bash)"
+    - micromamba activate kwant-stable
+    - git config --global --add safe.directory /builds/kwant/kwant
+    - git fetch --tags
+
+.no-extras-env:
+  before_script:
+    - eval "$(micromamba shell hook --shell bash)"
+    - micromamba activate kwant-stable-no-extras
+    - git config --global --add safe.directory /builds/kwant/kwant
+    - git fetch --tags
+
+# Note that this is 'latest' as of when the image was last built
+.latest-env:
+  before_script:
+    - eval "$(micromamba shell hook --shell bash)"
+    - micromamba activate kwant-latest
+    - git config --global --add safe.directory /builds/kwant/kwant
+    - git fetch --tags
+
+.bleeding-edge-env:
+  before_script:
+    - eval "$(micromamba shell hook --shell bash)"
+    - micromamba activate kwant-latest
+    - micromamba update --all
+    - git config --global --add safe.directory /builds/kwant/kwant
+    - git fetch --tags
+
+.ubuntu-env:
+  image: gitlab.kwant-project.org:5005/kwant/kwant/ubuntu
+
+.debian-env:
+  image: gitlab.kwant-project.org:5005/kwant/kwant/debian
+
+## Build Jobs
+
+build:ubuntu:
+  extends:
+    - .build
+    - .ubuntu-env
+
+build:debian:
+  extends:
+    - .build
+    - .debian-env
+
+build:stable:
+  extends:
+    - .build
+    - .stable-env
+
+build:no-extras:
+  extends:
+    - .build
+    - .no-extras-env
+
+build:latest:
+  extends:
+    - .build
+    - .latest-env
+
+build:bleeding-edge:
+  extends:
+    - .build
+    - .bleeding-edge-env
+  only:
+    - schedules
+  allow_failure: true
+
+## Test Jobs
+
+check whitespace style:
+  stage: test
+  script: ./check_whitespace
+  allow_failure: true
+
+check for dependencies installed:
+  stage: test
+  script:
+    - if [ -d .eggs ]; then echo "$(ls -d .eggs/*/) downloaded by build, update build environment" >&2; fi
+  allow_failure: true
+
+
+.test:
+  stage: test
+  script:
+    - py.test -r w --flakes kwant --junitxml=tests.xml --durations=10
+  artifacts:
+    reports:
+      junit: tests.xml
+
+.coverage:
+  stage: test
+  script:
+    - py.test -r w --cov=kwant --cov-report term --cov-report html --flakes kwant --junitxml=tests.xml --durations=10
+  artifacts:
+    paths:
+      - htmlcov
+    reports:
+      junit: tests.xml
+
+
+test:stable:
+  extends:
+    - .test
+    - .stable-env
+  dependencies:
+    - build:stable
+
+test:no-extras:
+  extends:
+    - .test
+    - .no-extras-env
+  dependencies:
+    - build:no-extras
+
+test:ubuntu:
+  extends:
+    - .test
+    - .ubuntu-env
+  dependencies:
+    - build:ubuntu
+
+test:debian:
+  extends:
+    - .test
+    - .debian-env
+  dependencies:
+    - build:debian
+
+test:latest:
+  extends:
+    - .test
+    - .latest-env
+  dependencies:
+    - build:latest
+
+test:bleeding-edge:
+  extends:
+    - .test
+    - .bleeding-edge-env
+  dependencies:
+    - build:bleeding-edge
+  only:
+    - schedules
+  allow_failure: true
+
+test:python-mumps:
+  extends:
+    - .test
+    - .latest-env
+  dependencies:
+    - build:latest
+  script:
+    - micromamba install -y -c conda-forge python-mumps
+    - py.test -r w --flakes kwant --junitxml=tests.xml --durations=10
+
+coverage:latest:
+  extends:
+    - .coverage
+    - .latest-env
+  dependencies:
+    - build:latest
+  only:
+    - schedules
+
+## Documentation building
+
+build documentation:
+  extends: .latest-env
+  dependencies:
+    - build:latest
+  stage: test
+  script:
+    - pip install --editable .  # Makefile executes from folders
+    - python -c 'from matplotlib import pyplot'  # Pre-generate font cache
+    - pip install ipykernel  # Temporary, should be removed after a jupyter-sphinx feedstock update.
+    - python -m ipykernel install --user --name kwant-latest  # Register the kernel
+    - make -C doc clean; make -C doc html SPHINXOPTS='-A website_deploy=True -n -D jupyter_execute_default_kernel=kwant-latest' SOURCE_LINK_TEMPLATE="$CI_PROJECT_URL"/blob/\$\$r/\$\$f
+  artifacts:
+    paths:
+      - doc/build/html/
+    expire_in: 1 month
+
+build PDF documentation:
+  extends: .latest-env
+  dependencies:
+    - build:latest
+  stage: test
+  script:
+    - pip install --editable .  # Makefile executes from folders
+    - python -c 'from matplotlib import pyplot'  # Pre-generate font cache
+    - pip install ipykernel  # Temporary, should be removed after a jupyter-sphinx feedstock update.
+    - python -m ipykernel install --user --name kwant-latest  # Register the kernel
+    - make -C doc latex SPHINXOPTS='-n -D jupyter_execute_default_kernel=kwant-latest'
+    - cd doc/build/latex
+    - make all-pdf
+  artifacts:
+    paths:
+      - doc/build/latex/kwant.pdf
+    expire_in: 1 month
+
+check for broken links in doc:
+  extends: .latest-env
+  dependencies:
+    - build:latest
+  stage: test
+  script:
+    - pip install --editable .  # Makefile executes from folders
+    - pip install ipykernel  # Temporary, should be removed after a jupyter-sphinx feedstock update.
+    - python -m ipykernel install --user --name kwant-latest  # Register the kernel
+    - make -C doc linkcheck SPHINXOPTS='-n -D jupyter_execute_default_kernel=kwant-latest'
+  allow_failure: true
+
+
+## Upload coverage reports and dev documentation
+
+upload coverage:
+  stage: deploy
+  only:
+    - schedules
+  dependencies:
+    - coverage:latest
+  environment:
+    name: coverage/$CI_COMMIT_REF_NAME
+    url: https://kwant-project.org/coverage/$CI_COMMIT_REF_SLUG
+    on_stop: remove_coverage
+  script:
+    - eval $(ssh-agent -s)
+    - echo $MASTER_WEBSITE_KEY | base64 -d | ssh-add -
+    - mv htmlcov $CI_COMMIT_REF_SLUG
+    - rsync -rlv -e "$SSH_COMMAND" --delete --relative $CI_COMMIT_REF_SLUG kwant@kwant-project.org:coverage/
+
+
+remove_coverage:
+  stage: deploy
+  only:
+    - branches@kwant/kwant
+  when: manual
+  environment:
+    name: coverage/$CI_COMMIT_REF_NAME
+    action: stop
+  script:
+    - eval $(ssh-agent -s)
+    - echo $MASTER_WEBSITE_KEY | base64 -d | ssh-add -
+    - mkdir empty/
+    - rsync -rlv -e "$SSH_COMMAND" --delete empty/ kwant@kwant-project.org:coverage/$CI_COMMIT_REF_SLUG
+
+
+upload documentation to the test server:
+  stage: deploy
+  environment:
+    name: docs review/$CI_COMMIT_REF_NAME
+    url: https://test.kwant-project.org/doc/$CI_COMMIT_REF_SLUG
+    on_stop: remove_docs
+  only:
+    - branches@kwant/kwant
+  script:
+    - eval $(ssh-agent -s)
+    - echo $TEST_WEBSITE_KEY | base64 -d | ssh-add -
+    - rsync -rlv -e "$SSH_COMMAND" --delete doc/build/html/* kwant2@test.kwant-project.org:doc/$CI_COMMIT_REF_SLUG
+
+
+remove_docs:
+  stage: deploy
+  when: manual
+  only:
+    - branches@kwant/kwant
+  environment:
+    name: docs review/$CI_COMMIT_REF_NAME
+    action: stop
+  script:
+    - eval $(ssh-agent -s)
+    - echo $TEST_WEBSITE_KEY | base64 -d | ssh-add -
+    - mkdir empty
+    - rsync -arv -e "$SSH_COMMAND" --delete empty/ kwant2@test.kwant-project.org:doc/$CI_COMMIT_REF_SLUG/
+
+
+upload dev version docs:
+  stage: deploy
+  environment:
+    name: production
+    url: https://kwant-project.org/doc/dev
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $CI_PROJECT_PATH == "kwant/kwant"
+  script:
+    - eval $(ssh-agent -s)
+    - echo $MASTER_WEBSITE_KEY | base64 -d | ssh-add -
+    - rsync -rlv -e "$SSH_COMMAND" --delete doc/build/html/* kwant@kwant-project.org:doc/dev
+
+
+## Build documentation for tagged releases
+
+.tagged-version:
+    only:
+       - /^v[0-9]+\.[0-9]+.[0-9]+$/@kwant/kwant
+
+gather release artifacts:
+  extends: .tagged-version
+  stage: release
+  script:
+    - ./setup.py sdist
+    - mkdir docs
+    - mv doc/build/latex/kwant.pdf docs/kwant-doc-${CI_COMMIT_TAG//v}.pdf
+    - mv doc/build/html docs/html
+    - zip -r docs/kwant-doc-${CI_COMMIT_TAG//v}.zip docs/html
+  artifacts:
+    paths:
+      - docs
+      - dist

.gitlab/issue_templates/release.md

+# Release %vX.Y.Z **UPDATE THIS**
+
+This is a checklist based on the [release document](RELEASE.rst); consult it for more details.
+
+## Preflight checks
+
+- [ ] All the issues from this milestone are resolved
+- [ ] Ensure that tests pass on [main](https://gitlab.kwant-project.org/kwant/kwant/tree/main) branch
+- [ ] Documentation looks correct https://test.kwant-project.org/doc/main
+- [ ] [Whatnew](doc/source/pre/whatsnew) is up to date
+- [ ] `AUTHORS.rst` and `.mailmap` are up to date (run `git shortlog -s | sed -e "s/^ *[0-9\t ]*//"| xargs -i sh -c 'grep -q "{}" AUTHORS.rst || echo "{}"'`)
+
+## Make a release, but do not publish it yet
+
+- [ ] Tag the release
+- [ ] Build the source tarball and inspect it
+- [ ] Build the documentation
+
+## Test packaging
+
+These steps may be done in parallel
+
+### Debian
+
+- [ ] Follow the steps for building the Debian packages from [RELEASE.rst](RELEASE.rst)
+
+### Conda
+
+- [ ] Publish the release candidate source tarball "somewhere on the internet" (SOTI)
+- [ ] open a PR to the [conda-forge/kwant-feedstock](https://github.com/conda-forge/kwant-feedstock/) repo on Github. Make sure to mark the PR as WIP so that it doesn't get merged in accidentally
+    - [ ] set the upstream tarball URL (in meta.yaml) to SOTI
+    - [ ] update the tarball hash in meta.yaml
+- [ ] See if the package builds
+
+## Publish the release
+- [ ] push the tag
+- [ ] upload the source tarball to PyPI
+- [ ] upload the source tarball to the Kwant website
+- [ ] publish the debian packages
+- [ ] publish the ubuntu packages
+- [ ] create a new version of the Kwant conda-forge feedstock, and open a pull request to upstream
+- [ ] upload the documentation to the Kwant website
+- [ ] update the Kwant website to say that Conda is the preferred way to install Kwant on Windows
+
+## Announce the release
+- [ ] Write a short post summarizing the highlights on the Kwant website
+- [ ] post to the Kwant mailing list
+
+## Working towards next release
+- [ ] add a whatsnew file for the next release
+- [ ] tag this release with an `a0` suffix
+- [ ] push this tag to the official Kwant repository
+- [ ] create a milestone for the next release

.mailmap

+Thomas Kloss <kloss@itp.uni-frankfurt.de>
+<joseph@weston.cloud> <joseph.weston08@gmail.com>
+<joseph@weston.cloud> <joseph.weston@cea.fr>
+<joseph@weston.cloud> <me@josephweston.org>
+<joseph@weston.cloud> <v-josewe@microsoft.com>
+Tómas Örn Rosdahl <torosdahl@gmail.com>
+<slavoutich@ostroukh.me> <ostroukh@lorentz.leidenuniv.nl>
+<m.t.wimmer@tudelft.nl> <wimmer@lorentz.leidenuniv.nl>
+Dániel Varjas <dvarjas@gmail.com>
+Pablo Pérez Piskunow <pablo.perez.piskunow@gmail.com>
+Michał Nowak <albeercik@gmail.com>
+Paul Clisson <clissonpaul@gmail.com>
+Jörg Behrmann <behrmann@physik.fu-berlin.de>
+Rafał Skolasiński <r.j.skolasinski@gmail.com>

AUTHORS

-================
-Authors of Kwant
-================
-
-The principal developers of Kwant are
-
-* Christoph W. Groth (SPSMS-INAC-CEA Grenoble)
-* Michael Wimmer (TU Delft)
-* Anton R. Akhmerov (TU Delft)
-* Xavier Waintal (SPSMS-INAC-CEA Grenoble)
-
-The authors can be reached at authors@kwant-project.org.
-
-Other people that have contributed to Kwant include
-
-* Daniel Jaschke (SPSMS-INAC-CEA Grenoble)
-* Joseph Weston (SPSMS-INAC-CEA Grenoble)
-
-We thank Christoph Gohlke for the creation of Windows installers.
-
-`CEA <http://cea.fr>`_ is the French Commissariat à l'énergie atomique et aux
-énergies alternatives.  The CEA is the copyright holder for the contributions of
-C. W. Groth, X. Waintal, and its other employees involved in Kwant.
-
-To find out who wrote a certain part of Kwant, please use the "blame" feature of
-`Git <http://git-scm.com/>`_, the version control system.
-
-
-Funding
--------
-
-During the development of Kwant 1.0, A. R. Akhmerov and M. Wimmer were supported
-by the Dutch Science Foundation NWO/FOM and by the ERC Advanced Investigator
-Grant of C. W. J. Beenakker who enthousiastically supported this project.
-A. R. Akhmerov was partially supported by a Lawrence Golub fellowship.
-C. W. Groth and X. Waintal were supported by the ERC Consolidator Grant MesoQMC.
-X. Waintal also acknowledges support from the STREP ConceptGraphene.

AUTHORS.rst

+================
+Authors of Kwant
+================
+
+The Kwant authors can be reached at authors@kwant-project.org.
+
+The principal developers of Kwant are
+
+* `Christoph Groth <mailto:christoph.groth@cea.fr>`_ (CEA Grenoble)
+* `Michael Wimmer <https://michaelwimmer.org>`_ (TU Delft)
+* `Anton Akhmerov <https://antonakhmerov.org>`_ (TU Delft)
+* `Xavier Waintal <https://www.pheliqs.fr/en/Pages/Portrait/Xavier-Waintal.aspx>`_ (CEA Grenoble)
+* `Joseph Weston <https://joseph.weston.cloud>`_ (TU Delft)
+
+Contributors to Kwant include
+
+* Jörg Behrmann (FU Berlin)
+* Pierre Carmier (CEA Grenoble)
+* Paul Clisson (CEA Grenoble)
+* `Dennis Heffels <mailto:d.heffels@fz-juelich.de>`_ (FZJ PGI-9)
+* Mathieu Istas (CEA Grenoble)
+* Daniel Jaschke (CEA Grenoble)
+* Thomas Kloss (CEA Grenoble)
+* Kelvin Loh (TNO)
+* Bas Nijholt (TU Delft)
+* Michał Nowak (TU Delft)
+* Viacheslav Ostroukh (Leiden University)
+* Pablo Pérez Piskunow (TU Delft)
+* Tómas Örn Rosdahl (TU Delft)
+* Sebastian Rubbert (TU Delft)
+* Rafał Skolasiński (TU Delft)
+* Adrien Sorgniard (CEA Grenoble)
+* Dániel Varjas (TU Delft)
+* Kostas Vilkelis (TU Delft)
+
+We thank Christoph Gohlke for the creation of installers for Microsoft Windows.
+
+`CEA <https://www.cea.fr>`_ is the French Commissariat à l'énergie atomique et aux
+énergies alternatives.  The CEA is the copyright holder for the contributions of
+C. W. Groth, X. Waintal, and its other employees involved in Kwant.
+
+To find out who wrote a certain part of Kwant, please use the "blame" feature of
+`Git <https://git-scm.com/>`_, the version control system.
+
+
+Funding
+-------
+
+Research related to Kwant was funded by
+
+* the US Office of Naval Research,
+* the European Research Council,
+* the Netherlands Organisation for Scientific Research NWO (formerly NWO/FOM).
+* the French National Agency for Research (ANR)
+* the Future and Emerging Technologies (FET) & Information and Communication Technologies (ICT) actions
+* Lawrence Golub fellowship

CITING → CITING.rst

@@ -15,7 +15,7 @@ cite the main paper that introduces Kwant:
   C. W. Groth, M. Wimmer, A. R. Akhmerov, X. Waintal,
   *Kwant: a software package for quantum transport*,
   `New J. Phys. 16, 063065 (2014)
-  <http://iopscience.iop.org/1367-2630/16/6/063065/article>`_.
+  <https://doi.org/10.1088/1367-2630/16/6/063065>`_.
 
 
 Other references we ask you to consider
@@ -26,7 +26,7 @@ also cite the upcoming paper that describes the relevant algorithms. The
 reference will also be added here once it is available.
 
 Kwant owes much of its current performance to the use of the `MUMPS
-<http://graal.ens-lyon.fr/MUMPS/>`_ library for solving systems of sparse linear
+<https://graal.ens-lyon.fr/MUMPS/>`_ library for solving systems of sparse linear
 equations.  If you have done high-performance calculations, we suggest citing
 
   P. R. Amestoy, I. S. Duff, J. S. Koster, J. Y. L’Excellent, SIAM. J. Matrix

CONTRIBUTE

-============================================
-Contributing to Kwant and reporting problems
-============================================
-
-We see Kwant not just as a package with fixed functionality, but rather as a
-framework for implementing different physics-related algorithms using a common
-set of concepts and, if possible, a shared interface.  We have designed it
-leaving room for growth, and plan to keep extending it.
-
-External contributions to Kwant are highly welcome.  You can help to advance
-the project not only by writing code, but also by reporting bugs, and
-fixing/improving the documentation.  A `mailing list
-<http://kwant-project.org/community.html>`_ is available for discussions.
-
-If you have some code that works well with Kwant, or extends it in some useful
-way, please consider sharing it.  Any external contribution will be clearly
-marked as such, and relevant papers will be added to the list of
-:doc:`suggested acknowledgements <citing>`.  The complete development history
-is also made available through a `web interface
-<http://git.kwant-project.org/kwant>`_.  If you plan to contribute, it is best
-to coordinate with us in advance either through the `mailing list
-<http://kwant-project.org/community.html>`__, or directly by `email
-<mailto:authors@kwant-project.org>`_ for matters that you prefer to not discuss
-publicly.
-
-Reporting bugs
---------------
-
-If you encounter a problem with Kwant, first try to reproduce it with as simple
-a system as possible.  Double-check with the documentation that what you
-observe is actually a bug in Kwant. If you think it is, please check whether
-the problem is already known by searching the `mailing list
-<http://kwant-project.org/community.html>`__.
-
-If the problem is not known yet, please email a bug report to the `Kwant mailing
-list <http://kwant-project.org/community.html>`__. A report should contain:
-
-* The versions of software you are using (Kwant, Python, operating system, etc.)
-
-* A description of the problem, i.e. what exactly goes wrong.
-
-* Enough information to reproduce the bug, preferably in the form of a simple
-  script.
-
-How to contribute
------------------
-
-We use the version control system `Git <http://git-scm.com/>`_ to coordinate the
-development of Kwant.  If you are new to Git, we invite you to learn its basics.
-(There's a plethora of information available on the Web.)  Kwant's Git
-repository contains not only the source code, but also all of the reference
-documentation and the tutorial.
-
-It is best to base your work on the latest version of Kwant::
-
-    git clone http://git.kwant-project.org/kwant
-
-Then you can modify the code, and build Kwant and the documentation as described
-in the :doc:`installation instructions <install>`.
-
-Some things to keep in mind:
-
-* 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/>`_.
-
-* Write tests for all the important functionality you add.  Be sure not to
-  break existing tests.
-
-A useful trick for working on the source code is to build in-place so that there
-is no need to re-install after each change.  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 that 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.

CONTRIBUTE.rst

+============================================
+Contributing to Kwant and reporting problems
+============================================
+
+We see Kwant not just as a package with fixed functionality, but rather as a
+framework for implementing different physics-related algorithms using a common
+set of concepts. Contributions to Kwant are highly welcome. You can help the
+project not only by writing code, but also by reporting bugs, and
+fixing/improving the website and the documentation. Please see the
+`"Contributing" page <https://kwant-project.org/contribute>`_ of the Kwant
+website for more information.

INSTALL

-=========================
-Installation instructions
-=========================
-
-Kwant can be installed either using prepared packages (Debian and Ubuntu
-variants of GNU/Linux, Mac OS X, and 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.
-
-
-************************
-Installing from packages
-************************
-
-Ubuntu (and derivatives)
-========================
-
-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``.
-
-
-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 "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.
-
-1. 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
-
-2. (Optional) Add the OpenPGP key used to sign the repositories by executing::
-
-       sudo apt-key adv --keyserver pgp.mit.edu --recv-key C3F147F5980F3535
-
-3. 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.
-
-
-Windows
-=======
-
-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
-
-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 2.7 for the appropriate architecture (32-bit or
-   64-bit) from the official `Python download site
-   <http://www.python.org/download/>`_.
-
-3. Download and install ``scipy-stack``, ``tinyarray``, and ``kwant`` for Python
-   2.7 from `Christoph Gohlke's page
-   <http://www.lfd.uci.edu/~gohlke/pythonlibs/>`_.  Once again you should choose
-   the architecture that is appropriate for your system.  ("win32" means 32-bit,
-   "amd64" means 64-bit -- even if you have a processor from Intel.)  If the
-   download from Gohlke's site is slow, try to download from `our mirror
-   <http://downloads.kwant-project.org/gohlke-mirror/>`_.
-
-   You may see a warning that says "The publisher could not be verified. Do you
-   want to run this software?". Select "Run".
-
-
-Mac OSX
-=======
-
-There is a number of different package managers for bringing software
-from the Unix/Linux world to Mac OSX. Since the community is quite
-split, we provide Kwant and its dependencies both via the `MacPorts
-<http://www.macports.org>`_ and `homebrew <http://brew.sh>`_ systems.
-
-Mac OSX: MacPorts
-=================
-
-MacPorts is a full-fledged package manager that recreates a whole Linux-like
-environment on your Mac. It requires little choices to be made by the user,
-and allows for the simplest way to install Kwant.
-
-In order to install Kwant, you have to
-
-1. Install a recent version of MacPorts, as explained in the
-   `installation instructions of MacPorts
-   <http://www.macports.org/install.php>`_.
-   In particular, as explained there, you will have to install also a
-   few prerequisites, namely
-
-  * the Xcode developer tools (compiler suite for Mac OSX) 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 MacOSX 10.8 or higher, the X11 server from the
-    `XQuartz project <http://xquartz.macosforge.org>`_.
-
-2. 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.)
-
-3. Execute ::
-
-       sudo port selfupdate
-
-4. Now, install Kwant and its prerequisites ::
-
-       sudo port install py27-kwant
-
-5. 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:
-
-* If you have problems with macports because your institution's firewall
-  blocks macports (more precisely, the `rsync` port), resulting in
-  errors from ``sudo port selfupdate``, follow
-  `these instructions <https://trac.macports.org/wiki/howto/PortTreeTarball>`_.
-* Of course, if you already have macports installed, you can skip step 1
-  and continue with step 2.
-
-
-Mac OS X: homebrew
-==================
-
-homebrew is a recent addition to the package managers on Mac OSX. It is
-more lightweight, tries to be as minimalistic as possible and give the user
-more freedom. Because of that, it requires a little more experience on
-the user side compared to MacPorts. The requirements are moderate though,
-if you know how to add directories to the ``$PATH`` variable for your shell,
-you are safe.
-
-1. Open a terminal and install homebrew as described on the `homebrew
-   homepage <http://brew.sh>`_ (instructions are towards the end of
-   the page)
-
-2. 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 OSX) 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
-    <http://xquartz.macosforge.org>`_ if you have Mac OSX 10.8 or higher.
-
-3. 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.
-
-4. Install a few prerequisites ::
-
-       brew install gfortran python
-
-5. Add additional repositories ::
-
-       brew tap homebrew/science
-       brew tap samueljohn/python
-       brew tap michaelwimmer/kwant
-
-6. Install Kwant and its prerequisites ::
-
-       pip install nose
-       brew install numpy scipy matplotlib
-       brew install kwant
-
-Notes:
-
-- If something does not work as expected, use ``brew doctor`` for
-  instructions (it will find conflicts and things like that).
-- As mentioned, homebrew allows for quite some freedom. In particular,
-  if you are an expert, you don't need necessarily to install
-  numpy/scipy/matplotlib from homebrew, but can use your own installation.
-  The only prerequisite is that they are importable from python. (the
-  Kwant installation will in any case complain if they are not)
-- In principle, you need not install the homebrew python, but could use
-  Apple's already installed python. Homebrew's python is more up-to-date,
-  though.
-
-
-***********************************
-Building and installing from source
-***********************************
-
-Prerequisites
-=============
-
-Building Kwant requires
- * `Python <http://python.org>`_ 2.6 or 2.7 (Python 3 is not supported yet),
- * `SciPy <http://scipy.org>`_ 0.9 or newer,
- * `LAPACK <http://netlib.org/lapack/>`_ and `BLAS <http://netlib.org/blas/>`_,
-   (For best performance we recommend the free `OpenBLAS
-   <http://xianyi.github.com/OpenBLAS/>`_ or the nonfree `MKL
-   <http://software.intel.com/en-us/intel-mkl>`_.)
- * `Tinyarray <http://kwant-project.org/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/>`_ 1.1 or newer, 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.  (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.)
- * The `nose <http://nose.readthedocs.org/>`_ testing framework for running the
-   tests included with Kwant.
-
-In addition, to build a copy of Kwant that has been checked-out directly from
-`its Git repository <http://git.kwant-project.org/kwant>`_, you will also need
-`Cython <http://cython.org/>`_ 0.17.1 or newer.  You do not need Cython to build
-Kwant that has been unpacked from a source .tar.gz-file.
-
-
-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``).
-
-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.
-
-
-Unix-like systems (GNU/Linux)
-=============================
-
-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.
-
-1. 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
-
-2. Unpack Tinyarray, enter its directory. To build and install, run ::
-
-       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: MacPorts
-==================
-
-The required dependencies of Kwant are best installed with one of the packaging
-systems. Here we only consider the case of `MacPorts
-<http://www.macports.org>`_ in detail. Some remarks for homebrew are given
-below.
-
-1. In order to set up MacPorts or homebrew, follow steps 1 - 3 of
-   the respective instructions of `MacPorts`_
-
-2. Install the required dependencies::
-
-       sudo port install gcc47 python27 py27-numpy py27-scipy py27-matplotlib mumps_seq
-       sudo port select --set python python27
-
-3. Unpack Tinyarray, enter its directory, build and install::
-
-       python setup.py build
-       sudo python setup.py install
-
-5. 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
-
-6. 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 OSX 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.
-
-
-Mac OS X: homebrew
-==================
-
-It is also possible to build Kwant using homebrew. The dependencies can be
-installed as ::
-
-    brew install gfortran python
-    brew tap homebrew/science
-    brew tap samueljohn/python
-    brew tap michaelwimmer/kwant
-    pip install nose
-    brew install numpy scipy matplotlib
-    brew install mumps_seq
-
-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).
-
-
-Windows
-=======
-
-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.
-
-
-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 its `documentation
-<http://docs.python.org/2/distutils/apiref.html#distutils.core.Extension>`_).
-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
-
-The detailed syntax of ``build.conf`` is explained in the `documentation of
-Python's configparser module
-<http://docs.python.org/3/library/configparser.html#supported-ini-file-structure>`_.
-
-
-Building the documentation
-==========================
-
-To build the documentation, the `Sphinx documentation generator
-<http://sphinx.pocoo.org/>`_ is required.  If PDF documentation is to be built,
-the tools from the `libRSVG <http://live.gnome.org/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.

INSTALL.rst

+=====================
+Installation of Kwant
+=====================
+
+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
+<https://kwant-project.org/install>`_ for instructions on how to install Kwant
+on your platform.  This is the recommended way for new users.
+
+The remainder of this section documents how to build Kwant from source.  This
+information is mostly of interest to contributors and packagers.
+
+
+********************
+Generic instructions
+********************
+
+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.org/project/kwant>`_.  The sources may be also
+cloned directly from the `official Kwant git repository
+<https://gitlab.kwant-project.org/kwant/kwant>`_.
+
+
+Prerequisites
+=============
+
+Building Kwant requires
+ * `Python <https://www.python.org/>`_ 3.8 or above,
+ * `NumPy <https://numpy.org/>`_ 1.18.0 or newer,
+ * `SciPy <https://www.scipy.org/>`_ 1.3.0 or newer,
+ * `LAPACK <https://netlib.org/lapack/>`_ and `BLAS <https://netlib.org/blas/>`_,
+   (For best performance we recommend the free `OpenBLAS
+   <https://www.openblas.net/>`_ or the nonfree `MKL
+   <https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html>`_.)
+ * `Tinyarray <https://gitlab.kwant-project.org/kwant/tinyarray>`_ 1.2.2 or newer,
+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 <https://matplotlib.org/>`_ 3.2.2 or newer, for the module `kwant.plotter` and the tutorial,
+ * `SymPy <https://sympy.org/>`_ 1.5.1 or newer, for the subpackage `kwant.continuum`.
+ * `Qsymm <https://pypi.org/project/qsymm/>`_ 1.2.6 or newer, for the subpackage `kwant.qsymm`.
+ * `MUMPS <https://mumps-solver.org/>`_, a sparse linear algebra library
+   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.)
+ * The `py.test testing framework <https://docs.pytest.org/>`_ 3.3.2 or newer for running the
+   tests included with Kwant.
+
+In addition, to build a copy of Kwant that has been checked-out directly from
+version control, you will also need `Cython <https://cython.org/>`_ 3.0 or
+newer.  You do not need Cython to build Kwant that has been unpacked from a
+source .tar.gz-file.
+
+
+Building and installing Kwant
+=============================
+
+Kwant can be built and installed by running the following commands in the root
+directory of the Kwant distribution. ::
+
+    python3 setup.py build
+    python3 setup.py install
+
+Depending on your system, you might have to run the second command with
+administrator privileges (e.g. prefixing it with ``sudo``).
+
+After installation, tests can be run with::
+
+    python3 -c 'import kwant; kwant.test()'
+
+The tutorial examples can be found in the directory ``tutorial`` inside the root
+directory of the Kwant source distribution.
+
+(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.)
+
+
+.. _build-configuration:
+
+Build configuration
+===================
+
+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
+sections, one for each extension module that is contained in Kwant, led by a
+``[section name]`` header and followed by ``key = value`` lines.
+
+The sections bear the names of the extension modules, for example
+``[kwant.operator]``.  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 ``setuptools.Extension`` (For a
+complete list, see its `documentation
+<https://setuptools.pypa.io/en/latest/userguide/ext_modules.html>`_).
+The corresponding values are whitespace-separated lists of strings.
+
+Example ``build.conf`` for compiling Kwant with C assertions and Cython's line
+trace feature::
+
+    [DEFAULT]
+    undef_macros = NDEBUG
+    define_macros = CYTHON_TRACE=1
+
+Kwant can optionally be linked against MUMPS.  The main
+application of build configuration is adopting the build process to the various
+deployments of MUMPS. MUMPS will be not linked
+against by default, except on Debian-based systems when the package
+``libmumps-scotch-dev`` is installed.
+
+The section ``[kwant.linalg._mumps]`` may be used to adapt the build process.
+(For simplicity and backwards compatibility, ``[mumps]`` is an aliases for the above.)
+
+
+Example ``build.conf`` for linking Kwant against a self-compiled MUMPS, `SCOTCH
+<https://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
+
+The detailed syntax of ``build.conf`` is explained in the `documentation of
+Python's configparser module
+<https://docs.python.org/3/library/configparser.html#supported-ini-file-structure>`_.
+
+
+Building the documentation
+==========================
+
+To build the documentation, the `Sphinx documentation generator
+<https://www.sphinx-doc.org/en/stable/>`_ is required with ``numpydoc`` extension
+(version 0.5 or newer), as well as ``jupyter-sphinx`` (version 0.2 or newer).
+If PDF documentation is to be built, the tools
+from the `libRSVG <https://wiki.gnome.org/action/show/Projects/LibRsvg>`_
+(Debian/Ubuntu package ``librsvg2-bin``) and a Sphinx extension
+``sphinxcontrib-svg2pdfconverter`` are needed to convert SVG drawings into the
+PDF format.
+
+As a prerequisite for building the documentation, Kwant must have been built
+successfully using ``python3 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.
+
+****************************
+Hints for specific platforms
+****************************
+
+Unix-like systems (GNU/Linux)
+=============================
+
+Kwant should run on all recent Unix-like systems.  The following instructions
+have been verified to work on Debian 8 (Jessie) or newer, and on Ubuntu 14.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.
+
+1. Install the required packages.  On Debian-based systems like Ubuntu this can
+   be done by running the command ::
+
+       sudo apt-get install python3-dev python3-setuptools python3-scipy python3-matplotlib python3-pytest python3-sympy g++ gfortran libmumps-scotch-dev
+
+2. Unpack Tinyarray, enter its directory. To build and install, run ::
+
+       python3 setup.py build
+       sudo python3 setup.py install
+
+3. Inside the Kwant source distribution's root directory run ::
+
+       python3 setup.py build
+       sudo python3 setup.py install
+
+By default the package will be installed under ``/usr/local``.  Run ``python3
+setup.py --help install`` for installation options.
+
+
+Microsoft Windows
+=================
+
+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.

LICENSE → LICENSE.rst

@@ -2,11 +2,7 @@
 Kwant license
 =============
 
-(This license applies to all files of this distribution except those within the
-``doc/sphinxext`` subdirectory for which ``doc/sphinxext/LICENSE.txt``
-applies.)
-
-Copyright 2011-2013 C. W. Groth (CEA), M. Wimmer, A. R. Akhmerov,
+Copyright 2011-2015 C. W. Groth (CEA), M. Wimmer, A. R. Akhmerov,
 X. Waintal (CEA), and others.  All rights reserved.
 
 (CEA = Commissariat à l'énergie atomique et aux énergies alternatives)

README

-Kwant is a Python package for numerical quantum transport calculations. It
-exposes the natural concepts of the theory of quantum transport (lattices,
-symmetries, electrodes, orbital/spin/electron-hole degrees of freedom) in a
-simple and transparent way. Kwant offers direct support for calculations of
-transport properties (conductance, noise, scattering matrix), dispersion
-relations, modes, wave functions, various Green’s functions, and
-out-of-equilibrium local quantities. Other computations involving tight-binding
-Hamiltonians can be implemented easily.
-
-See also the files INSTALL, LICENSE, AUTHORS, CITING, and CONTRIBUTE
-in this directory.

README.rst

+Kwant is a free (open source) Python package for numerical calculations on
+tight-binding models with a strong focus on quantum transport. It is designed to
+be flexible and easy to use. Thanks to the use of innovative algorithms, Kwant
+is often faster than other available codes, even those entirely written in the
+low level FORTRAN and C/C++ languages.
+
+Tight-binding models can describe a vast variety of systems and phenomena in
+quantum physics. Therefore, Kwant can be used to simulate
+
+* metals,
+* graphene,
+* topological insulators,
+* quantum Hall effect,
+* superconductivity,
+* spintronics,
+* molecular electronics,
+* any combination of the above, and many other things.
+
+Kwant can calculate
+
+* transport properties (conductance, noise, scattering matrix),
+* dispersion relations,
+* modes,
+* wave functions,
+* various Green’s functions,
+* out-of-equilibrium local quantities.
+
+Other computations involving tight-binding Hamiltonians can be implemented
+easily.
+
+See the `Kwant website <https://kwant-project.org/>`_ for the latest stable
+version.  The current development version is available via the `Kwant gitlab
+instance <https://gitlab.kwant-project.org/kwant/kwant>`_.  Contributions are
+welcome.
+
+A `mailing list <https://kwant-project.org/community>`_ exists for general
+discussions related to Kwant.  Please report bugs and other issues using the
+`issue tracker <https://gitlab.kwant-project.org/kwant/kwant/issues>`_.

README_WINDOWS.txt

 A note for users of Microsoft Windows
 -------------------------------------
 
-To read the text files in this directory (README, LICENSE, INSTALL, etc.),
-right-click, choose "Open", and open with "WordPad".  ("Notepad" will not
+To read the text files in this directory (README.rst, LICENSE.rst, INSTALL.rst,
+etc.), right-click, choose "Open", and open with "WordPad".  ("Notepad" will not
 display the files properly.)

RELEASE.rst

+Making a Kwant release
+======================
+
+This document guides a contributor through creating a release of Kwant.
+
+Create a release issue
+######################
+
+Use the correct `issue template <gitlab.kwant-project.org/kwant/kwant/issues/new?issuable_template=release>`_, adjust it if necessary.
+
+Preflight checks
+################
+
+The following checks should be made *before* tagging the release.
+
+
+Check that all issues are resolved
+----------------------------------
+
+Check that all the issues and merge requests for the appropriate
+`milestone <https://gitlab.kwant-project.org/kwant/kwant/milestones>`_
+have been resolved. Any unresolved issues should have their milestone
+bumped.
+
+
+Ensure that all tests pass
+--------------------------
+
+For major and minor releases we will be tagging the ``master`` branch.
+For patch releases, the ``stable`` branch.
+This should be as simple as verifying that the latest CI pipeline succeeded,
+however in ``stable`` branch also manually trigger CI task of building the
+conda package and verify that it, too, succeeds.
+
+
+Inspect the documentation
+-------------------------
+
+If the CI pipeline succeeded, then the latest docs should be available at:
+
+    https://test.kwant-project.org/doc/<branch name>
+
+Check that there are no glaring deficiencies.
+
+
+Update the ``whatsnew`` file
+----------------------------
+
+For each new minor release, check that there is an appropriate ``whatsnew`` file
+in ``doc/source/pre/whatsnew``.  This should be named as::
+
+    <major>.<minor>.rst
+
+and referenced from ``doc/source/pre/whatsnew/index.rst``.  It should contain a
+list of the user-facing changes that were made in the release. With any luck
+this file will have been updated at the same time as a feature was implemented,
+if not then you can see what commits were introduced since the last release using
+``git log``. You can also see what issues were assigned to the release's
+milestones and get an idea of what was introduced from there.
+
+Starting with Kwant 1.4, we also mention user-visible changes in bugfix
+releases in the whatsnew files.
+
+
+Verify that ``AUTHORS.rst`` and ``.mailmap`` are up-to-date
+-----------------------------------------
+
+The following command shows if there are any committers that are missing from
+``AUTHORS.rst``::
+
+  git shortlog -s | sed -e "s/^ *[0-9\t ]*//"| xargs -i sh -c 'grep -q "{}" AUTHORS.rst || echo "{}"'
+
+If it outputs anything, then either add the new contributors to the list, or add
+new identities of old contributors to the ``.mailmap``
+
+Make a release, but do not publish it yet
+#########################################
+
+Various problems can surface only during the process of preparing a release and
+make it necessary to fix the codebase.  It would be a pity to have to succeed
+the freshly released version by a minor release just to correct a glitch that
+was detected too late.  Therefore it is a good idea to pursue the release as
+far as possible without announcing it, such that it can be undone and corrected
+if necessary.  In the past tests that failed on the x86-32 architecture and
+wrongly declared dependencies have been detected in this way.
+
+
+Tag the release
+---------------
+
+Make an *annotated*, *signed* tag for the release. The tag must have the name::
+
+    git tag -s v<version> -m "version <version>"
+
+Be sure to respect the format of the tag name (leading "v", e.g. "v1.2.3").
+The tag message format is the one that has been used so far.
+
+Do *not* yet push the tag anywhere; it might have to be undone!
+
+
+Build a source tarball and inspect it
+-------------------------------------
+
+    ./setup.py sdist
+
+This creates the file dist/kwant-<version>.tar.gz.  It is a good idea to unpack it
+in /tmp and inspect that builds in isolation and that the tests run::
+
+    cd /tmp
+    tar xzf ~/src/kwant/dist/kwant-<version>.tar.gz
+    cd kwant-<version>
+    ./setup.py build
+    ./setup.py build_ext -i
+    py.test
+
+
+Build the documentation
+-----------------------
+Building the documentation requires 'sphinx' and a Latex installation.
+First build the HTML and PDF documentation::
+
+    ./setup.py build
+    make -C doc realclean
+    make -C doc html latex
+    make -C doc/build/latex all-pdf
+
+Then create a zipped version of the HTML documentation and name the PDF
+consistently, storing them, for example, in the "dist" directory along with the
+source tarballs::
+
+    version=$(git describe | sed 's/^v//') # Assumes that we are on a tag.
+    ln -s `pwd`/doc/build/html /tmp/kwant-doc-$version
+    (cd /tmp/; zip -r kwant-doc-$version.zip kwant-doc-$version)
+    mv /tmp/kwant-doc-$version.zip dist
+    mv doc/build/latex/kwant.pdf dist/kwant-doc-$version.pdf
+
+Finally, rebuild the documentation for the website (including the web analysis javascript code)::
+
+    make -C doc html SPHINXOPTS='-A website_deploy=True -n -W'
+
+
+Clone the repository of the Kwant Debian package
+------------------------------------------------
+
+This step needs to be performed only once.  The cloned repository can be reused
+for subsequent releases.
+
+Clone the "kwant-debian" repository and go into its root directory.  If you
+keep the Kwant source in "src/kwant", a good location for the Debian package
+repository is "src/debian/kwant".  The packaging process creates many files
+that are placed into the parent directory of the packaging repository, hence
+having an additional directory level ("src/debian") is a good way to keep these
+files separate::
+
+    mkdir debian
+    cd debian
+    git clone ssh://git@gitlab.kwant-project.org:443/kwant/debian-kwant.git kwant
+    cd kwant
+
+Create a local upstream branch::
+
+    git branch upstream origin/upstream
+
+Add a remote for the repository that contains the previously created tag::
+
+    git remote add upstream_repo ~/src/kwant
+
+Make sure that::
+
+    git config --get user.name
+    git config --get user.email
+
+show correct information.
+
+
+Release a new version of the Kwant Debian package
+-------------------------------------------------
+
+Fetch packaging work (from origin) and the git tag created above (from
+upstream_repo) into the packaging repo::
+
+    git fetch --all
+
+Make sure that the branches ``master`` and ``upstream`` are up-to-date::
+
+    git checkout upstream
+    git merge --ff-only origin/upstream
+    git checkout master
+    git merge --ff-only origin/master
+
+Debian packages may include "quilt" patches that are applied on top of the
+pristine tarball.  The tool `gbp pq` manages these patches as a git branch
+``patch-queue/master.  Execute the following commands to (re)create
+that branch based on the patches in ``debian/patches``::
+
+    gbp pq --force import
+    git checkout master
+
+Now it is time to import the new source code.  There are two options.  If, as
+recommended above, the tarball of the new version has not been made public yet,
+it must be imported as follows::
+
+    gbp import-orig ~/src/kwant/dist/kwant-<version>.tar.gz
+
+Alternatively, the following commands will import the newest version from PyPI::
+
+    uscan --report      # This will report if a newer version exists on PyPI
+    gbp import-orig --uscan
+
+Now it is time to review the patch queue.  Rebase and checkout the ``patch-queue/master`` branch using::
+
+    gbp pq rebase
+
+As ususal, the rebase might require manual intervention.  Once done, review all
+the commits of the ``patch-queue/master`` branch.  Are all patches still
+needed, should any be removed?  When done (even if no changes were needed), recreate the files in ``debian/patches`` using::
+
+    gbp pq export
+
+If ``git diff`` reports any changes, be sure to commit them.
+
+Now is the right moment to verify and modify the packaging information inside
+the ``debian/`` directory.  For example, are the dependencies and versions
+stated in ``debian/control`` up-to-date?
+
+When all changes are commited, it is time to finalize by updating the Debian
+changelog file.  Add a point "New upstream release" if there was one, and
+describe any other changes to the Debian *packaging*::
+
+    DEBEMAIL=<your-email> gbp dch -R --commit --distribution testing
+
+Now verify that the package builds with::
+
+    git clean -i
+    gbp buildpackage
+
+This is *not* how the package should be built for distribution.  For that, see
+the following two sections.
+
+If problems surface that require changing the packaging, undo the changelog
+commit, modify the packaging, and re-iterate.  If the problems require fixing
+Kwant, you will have to go back all the way to recreating the source tarball.
+If the version to be packaged has been released publicly already, this will require a new bugfix version.
+
+
+Setup git-pbuilder to build Debian packages
+-------------------------------------------
+
+Pbuilder is a tool to build Debian packages in an isolated chroot.  This allows
+to verify that the package indeed only has the declared dependencies.  It also
+allows to cross-build packages for i386 on amd64.
+
+The following describes how to setup git-pbuilder, see also
+https://wiki.debian.org/git-pbuilder.  This procedure needs to be executed only
+once for a Debian system.
+
+Install the Debian package git-buildpackage.
+
+As root, add the following lines to /etc/sudoers or /etc/sudoers.d/local
+
+    Cmnd_Alias BUILD = /usr/sbin/cowbuilder
+
+and
+
+    user     ALL = SETENV: BUILD
+
+Now create pbuilder images.  In the following, replace ``<dist>`` by the
+current Debian testing codename, e.g. "buster"::
+
+    ARCH=i386 DIST=<dist> git-pbuilder create
+    ARCH=amd64 DIST=<dist> git-pbuilder create
+
+If the packages to be built have special dependencies, use the trick described in https://wiki.debian.org/git-pbuilder#Using_Local_Packages
+
+
+Build Kwant packages using git-pbuilder
+---------------------------------------
+
+Update the builder environment (again, replace ``<dist>`` with the name of the
+current Debian testing)::
+
+    ARCH=i386 DIST=<dist> git-pbuilder update
+    ARCH=amd64 DIST=<dist> git-pbuilder update
+
+Make sure that the working directory is completely clear::
+
+    git clean -id
+
+(Note that pytest has the nasty habit of creating a hidden ``.pytest_cache``
+directory which gitignores itself.  The above command will not delete this
+directory, but git-pbuilder will complain.)
+
+Now build the packages.  First the i386 package.  The option "--git-tag" tags
+and signs the tag if the build is successful.  In a second step, the package is
+built for amd64, but only the architecture-dependent files (not the
+documentation package)::
+
+    gbp buildpackage --git-pbuilder --git-arch=i386 --git-dist=<dist> --git-tag
+    gbp buildpackage --git-pbuilder --git-arch=amd64 --git-dist=<dist> --git-pbuilder-options='--binary-arch'
+
+Another example: build source package only::
+
+    gbp buildpackage --git-export-dir=/tmp -S
+
+
+Build backports for the current Debian stable
+---------------------------------------------
+
+Create a changelog entry for the backport::
+
+    DEBEMAIL=<your-email> dch --bpo
+
+As shown above, run ``git-pbuilder update`` for the appropriate distribution
+codename.
+
+Build backported packages::
+
+    gbp buildpackage --git-pbuilder --git-ignore-new --git-arch=i386 --git-dist=<dist>
+    gbp buildpackage --git-pbuilder --git-ignore-new --git-arch=amd64 --git-dist=<dist> --git-pbuilder-options='--binary-arch'
+
+Do not commit anything.
+
+
+Publish the release
+###################
+
+If the Debian packages build correctly that means that all tests pass both on
+i386 and amd64, and that no undeclared dependencies are needed.  We can be
+reasonably sure that the release is ready to be published.
+
+
+git
+---
+
+Push the tag to the official Kwant repository::
+
+    git push origin v<version>
+
+
+PyPI
+----
+
+Install `twine <https://pypi.org/project/twine>`_ and run the following
+(this requires a file ~/.pypirc with a valid username and password: ask
+Christoph Groth to add you as a maintainer on PyPI, if you are not already)::
+
+    twine upload -s dist/kwant-<version>.tar.gz
+
+It is very important that the tarball uploaded here is the same (bit-by-bit,
+not only the contents) as the one used for the Debian packaging.  Otherwise it
+will not be possible to build the Debian package based on the tarball from
+PyPI.
+
+
+Kwant website
+-------------
+
+The following requires ssh access to ``kwant-project.org`` (ask Christoph
+Groth). The tarball and its signature (generated by the twine command above) should be
+uploaded to the downloads section of the website::
+
+    scp dist/kwant-<version>.tar.gz* kwant:web/downloads/kwant
+
+
+Debian packages
+---------------
+
+Go to the Debian packaging repository and push out the changes::
+
+    git push --tags origin master upstream
+
+Now the Debian packages that we built previously need to be added to the
+repository of Debian packages on the Kwant website.  So far the full
+version of this repository is kept on Christoph Groth's machine, so these
+instructions are for reference only.
+
+Go to the reprepro repository directory and verify that the configuration file
+"conf/distributions" looks up-to-date.  It should look something like this (be
+sure to update the codenames and the versions)::
+
+    Origin: Kwant project
+    Suite: stretch-backports
+    Codename: stretch-backports
+    Version: 9.0
+    Architectures: i386 amd64 source
+    Components: main
+    Description: Unofficial Debian package repository of https://kwant-project.org/
+    SignWith: C3F147F5980F3535
+
+    Origin: Kwant project
+    Suite: testing
+    Codename: buster
+    Version: 10.0
+    Architectures: i386 amd64 source
+    Components: main
+    Description: Unofficial Debian package repository of https://kwant-project.org/
+    SignWith: C3F147F5980F3535
+
+If the config had to be updated execute::
+
+    reprepro --delete clearvanished
+    reprepro export
+    reprepro --delete createsymlinks
+
+In addition to the above, if distributions were removed from the
+configuration file the corresponding directories must be removed
+manually from under the `dists` subdirectory.
+
+Now the source and binary Debian packages can be added.  The last line has to
+be executed for all the .deb files and may be automated with a shell loop. (Be
+sure to use the appropriate <dist>: for the above configuratoin file either
+"testing" or "stretch-backports".)::
+
+    reprepro includedsc <dist> ../../src/kwant_<version>-1.dsc
+    reprepro includedeb <dist> python3-kwant_<version>-1_amd64.deb
+
+Once all the packages have been added, upload the repository::
+
+    rsync -avz --delete dists pool kwant-project.org:webapps/downloads/debian
+
+
+Ubuntu packages
+---------------
+
+Packages for Ubuntu are provided as a PPA (Personal Package Archive):
+https://launchpad.net/~kwant-project/+archive/ubuntu/ppa
+
+Make sure ~/.dput.cf has something like this::
+
+    [ubuntu-ppa-kwant]
+    fqdn = ppa.launchpad.net
+    method = ftp
+    incoming = ~kwant-project/ppa/ubuntu/
+    login = anonymous
+    allow_unsigned_uploads = 0
+
+We will also use the following script (prepare_ppa_upload)::
+
+    #!/bin/sh
+
+    if [ $# -eq 0 ]; then
+        echo -e "\nUsage: $(basename $0) lousy mourning2 nasty\n"
+        exit
+    fi
+
+    version=`dpkg-parsechangelog --show-field Version`
+    mv debian/changelog /tmp/changelog.$$
+
+    for release in $@; do
+        cp /tmp/changelog.$$ debian/changelog
+        DEBEMAIL=christoph.groth@cea.fr dch -b -v "$version~$release" -u low 'Ubuntu PPA upload'
+        sed -i -e "1,1 s/UNRELEASED/${release%[0-9]}/" debian/changelog
+        debuild -S -sa
+    done
+
+    mv /tmp/changelog.$$ debian/changelog
+
+Make sure that the Debian package builds correctly and go to its directory.
+
+Check https://wiki.ubuntu.com/Releases for the relevant releases (we want to
+provide packages at least for the current LTS release and the newer non-LTS
+releases) and execute::
+
+    prepare_ppa_upload <dist0> <dist1> <dist2>
+
+(if a second upload of the same Debian version is needed, something like "vivid2" instead of "vivid" can be used.)
+
+Now the changes files are "put" to start the build process on the PPA servers::
+
+    cd ..
+    dput ubuntu-ppa-kwant *~*.changes
+
+
+Clone the repository of the Kwant conda-forge package
+-----------------------------------------------------
+
+This step needs to be performed only once.  The cloned repository can be reused
+for subsequent releases.
+
+Clone the "Kwant feedstock" repository and go into its root directory.  If you
+keep the Kwant source in "src/kwant", a good location for the Conda package
+repository is "src/conda-forge/kwant"::
+
+    cd ~/src
+    mkdir conda-forge
+    cd conda-forge
+    git clone https://github.com/conda-forge/kwant-feedstock kwant
+    cd kwant
+
+Rename the default remote to ``upstream``::
+
+    git remote rename origin upstream
+
+
+Create a new version of the Kwant conda-forge package
+-----------------------------------------------------
+
+Edit the file ``recipe/meta.yml``. Correctly set the ``version``
+at the top of the file to the version of this release. Set the ``sha256``
+string in the ``source`` section near the top of the file to the SHA256 hash
+of the kwant source tarball that we previously created. You can find the
+SHA256 hash by running ``openssl sha256 <filename>`` on Linux and Mac OSX.
+
+Commit your changes.
+
+
+Conda forge
+-----------
+This step requires a GitHub account, as Conda forge packages are autobuilt
+from repositories hosted on GitHub.
+
+Fork the `Kwant feedstock <https://github.com/conda-forge/kwant-feedstock>`_
+repository and add your fork as a remote to the copy that you previously cloned::
+
+    cd ~/conda-forge/kwant
+    git remote add myfork https://github.com/<your-gh-username>/kwant-feedstock
+
+Push the changes that you previously commited to your fork::
+
+    git push myfork master
+
+Open a pull request to Kwant feedstock repository. Ask Bas Nijholt or
+Joseph Weston to review and accept the pull request.
+
+
+Documentation
+-------------
+The following requires ssh access to  ``kwant-project.org``.
+Ask Christoph Groth if you need to be granted access.
+
+Upload the zipped HTML and PDF documentation::
+
+    scp dist/kwant-doc-<version>.{zip,pdf} kwant:web/downloads/doc
+
+Upload the HTML documentation for the website::
+
+    rsync -rlv --delete doc/build/html/* kwant:web/main/doc/<short-version>
+
+where in the above ``<short-version>`` is just the major and minor version numbers.
+
+Finally, create symbolic links for the website::
+
+    ssh kwant
+    for e in zip pdf; do ln -sf kwant-doc-<version>.$e webapps/downloads/doc/latest.$e; done
+    ln -nsf <short-version> webapps/kwant/doc/<major>
+    exit
+
+
+Announce the release
+####################
+
+Write a short post summarizing the highlights of the release on the
+`Kwant website <https://gitlab.kwant-project.org/kwant/website>`, then
+post this to the mailing list kwant-discuss@kwant-project.org.
+
+
+Working towards the next release
+################################
+
+After finalizing a release, a new ``whatsnew`` file should be created for
+the *next* release, and this addition should be committed and tagged as::
+
+    <new major>.<new minor>.<new patch>a0
+
+This tag should be pushed to Kwant Gitlab, and a new milestone for the next
+release should be created.

TODO

-Roughly in order of importance.                                     -*-org-*-
-
-* Fix lattice.neighbors() when lattice has lower dimensionality than the space.
-
-* Document the order of sites/orbitals in finalized builders
-
-* Add calculation of current density
-
-* Re-design the interface of low level systems
-  considering the following
-  - We want support for multiple symmetry directions
-  - Consider making System.hamiltonian a vectorized function.  Value functions
-    should be vectorizable as well (when marked with a decorator?)
-  - Consider using two-way-compressed uni-directional graphs in systems
-    advantages:
-    - The number of edges gets reduced by 1/2.
-    - The Hermicity of the Hamiltonian is enforced in a more obvious way.
-    - It's clear at system level which Hamiltonian elements are defined
-      directly.
-  - Verify that the graph slicing algorithm continues to work.
-
-* Improve experience when working with sites in a finalized builder
-  (It should be possible to map sites to nodes efficiently.  Probably, the best
-  way to do it is to sort the sites in finalized builders.)
-  One could then also RLE compress sites in finalized builders.
-
-* Make Kwant objects pickleable
-
-* Implement "inhomogeneous arrays" for ldos and wavefunc
-  The point is to have ldos or wavefunc return objects that behave like 2d
-  arrays, where the site index and orbital index are separate.  However, this
-  must work in the general case where the number of orbitals per site varies.
-
-* Go through the documentation and apply consistent linking/naming practice:
-  We could adopt the scheme that is used in Python's stdlib.  See for example
-  http://docs.python.org/2/library/threading.html
-  This would mean:
-  - When referring to functions, we always append "()" to their name.
-  - Names of objects (types, functions, ...) that are a documented part of
-    Kwant are always hyperlinks _when_ the object itself is meant.
-  - Concepts that are meant in a more general sense are not hyperlinked, even if
-    there exists an object of the same name in Kwant.  (Consider the usage of
-    linking for the term "Thread" in the document linked above.)
-
-* Plotter: show site upon click
-
-* fix physics.noise (docstring, __all__, etc.)
-
-* Verify that selective plotting works.
-
-* Write an RGF solver that uses graph/slicer.
-
-* Add support for easily adding magnetic field to a system.
-
-* Allow plotting of infinite systems
-
-* Use sparse linear algebra to calculate bands
-  However, SciPy's sparse eigenvalues don't seem to work well.
-
-* Allow attaching leads with further than nearest lead unit cell hoppings.
-  The most easy way to do this is increasing the period of the lead.
-  Alternatively, generalize modes and InfiniteSystem format.
-
-* In finalized leads, only keep the sites of a single lead unit cell.
-
-* Add support for optimization of lead fundamental domains.
-
-* Incorprorate efficient correlated disorder using scipy.spatial.
-
-* Implement the C solver interface.
-
-* Wrap TB_SIM as a solver.
-
-* Benchmark MUMPS and check whether nested dissection would be useful.
-  If yes, implement it.
-
-* Consider implementing "models" module, incorporate units into it.
-  - It is potentially related to vectorized value functions (since modesl are
-    spatially homogeneous)
-  - It may also be related to units, which we may borrow from somewhere,
-    or implement on our own.
-
-* Improve handling of s-matrices with important additional degrees of freedom.
-  i.e. spin, or electron-hole.  Currently, one needs to manually process lead
-  modes and to perform a basis transformation of the scattering matrix.
-
-* Implement automatic search for discrete symmetries of a tight binding model
-  and of conservation laws.
-
-* Revisit Symmetry, make it more general. I.e. allow for description of other
-  discrete symmetries, possibly also symmetries which change site and hopping
-  values (=gauge symmetries).
-
-* Make an option for plotting hoppings as arcs, in order for overlapping
-  hoppings to be distinguishable. Also potentially add arrows to the hoppings.
-
-* Adopt mincut/maxflow algorithm from networkx or python-graph to find the best
-  representation of a lead unit cell.
-
-* Speed up kwant.digest
-  by using SipHash and Ziggurat algorithm in C/Cython
-
-* Improve finding of modes with zero velocity or infinite decay length
-  Right now a mode with truly zero velocity may be incorrectly identified as
-  propagating or evanescent.
-
-* Remove sphinxext and use an external numpydoc once it is available

check_whitespace

+#!/bin/sh
+
+! for f in $(git ls-files | grep -v \\.diff$); do
+    file $f | grep -q ' text' || continue
+    grep -q '[[:blank:]]$' $f && echo $f: trailing whitespace
+    tail -n1 $f | read -r _ || echo $f: no newline at end of file
+    tail -n1 $f | grep -q '^$' && echo $f: empty line at end of file
+done | grep . >&2