.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>

ACKNOWLEDGEMENTS

-==========================
-Suggested acknowledgements
-==========================
-
-To be written.

AUTHORS

-================
-Authors of kwant
-================
-
-The principal developers of kwant are
-
-* Christoph W. Groth (SPSMS-INAC-CEA Grenoble)
-* Michael Wimmer (Leiden University)
-* Anton R. Akhmerov (Harvard University, Leiden University)
-* Xavier Waintal (SPSMS-INAC-CEA Grenoble)
-
-The authors can be reached at authors@kwant-project.org.
-
-The contributions of Christoph and Xavier are part of their work at `CEA
-<http://cea.fr>`_, the French Commissariat à l'énergie atomique et aux énergies
-alternatives.
-
-Other people that have contributed to kwant include
-
-* Daniel Jaschke
-* Joseph Weston
-
--------------------------------------------------------------
-
-To find out who exactly wrote a certain part of kwant, please use the "blame"
-feature of `git <http://git-scm.com/>`_, the version control system.

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.rst

+============
+Citing Kwant
+============
+
+We provide Kwant as free software under a :doc:`BSD license <license>` as a
+service to the physics community.  If you have used Kwant for work that has
+lead to a scientific publication, please mention the fact that you used it
+explicitly in the text body.  For example, you may add
+
+  *the numerical calculations were performed using the Kwant code*
+
+to the description of your numerical calculations.  In addition, we ask you to
+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)
+  <https://doi.org/10.1088/1367-2630/16/6/063065>`_.
+
+
+Other references we ask you to consider
+---------------------------------------
+
+If you have profited from the quantum transport functionality of Kwant, please
+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
+<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
+  Anal. & Appl. 23 (1), 15 (2001).
+
+Finally, if you use the routine for generation of circular ensembles of random
+matrices, please cite
+
+  \F. Mezzadri, Notices Am. Math. Soc. 54, 592 (2007).

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

-=============================
-Building and installing kwant
-=============================
-
-Prerequisites
-=============
-
-Building kwant requires
- * `Python <http://python.org>`_ 2.6 or 2.7 (Python 3 is not supported yet),
- * `SciPy <http://scipy.org>`_ 0.7.2 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 unfree `MKL
-   <http://software.intel.com/en-us/intel-mkl>`_.)
- * 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.  (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
-version control (git), 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
-====================
-
-Please note the `system-specific instructions`_ below.
-
-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.
-
-
-System-specific instructions
-============================
-
-Unix-like systems (Linux)
--------------------------
-
-kwant should run on all recent Unix-like systems.  The following instructions
-have been verified to work on Debian 6 (Squeeze) or newer, and on Ubuntu 12.04
-or newer.  For other systems 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
---------
-
-These instructions were verified in April 2013 under Mac OS X 10.8.2
-
-The instructions also include installing MUMPS for optimal performance
-of kwant. If you choose to omit MUMPS, you can skip over the optional
-steps 3 and 5.
-
-1. Install the current version of `MacPorts
-   <http://www.macports.org/>`_.  As a prerequisite, you will also
-   have to install a current version of Xcode (Apple's developer
-   tools). For that, follow the `installation instructions of MacPorts
-   <http://www.macports.org/install.php>`_. (Note that you will need an
-   account with Apple to download the latest version of Xcode).
-
-2. Install the required packages::
-
-       sudo port install gcc48
-       sudo port install python27
-       sudo port select --set python python27
-       sudo port install py27-numpy py27-scipy py27-cython py27-matplotlib
-
-3. (OPTIONAL) For the best performance, install also the MUMPS library and its
-   prerequisites.
-
-   * Download `METIS <http://glaros.dtc.umn.edu/gkhome/metis/metis/overview>`_.
-     You need to download version 4.0.3 from the METIS `download page
-     <http://glaros.dtc.umn.edu/gkhome/fsroot/sw/metis/OLD>`_ (the newer
-     versions have an incompatible interface).
-
-     In order to compile metis, edit the corresponding lines in
-     ``Makefile.in`` such that they read::
-
-         CC = gcc-mp-4.8
-         COPTIONS = -fPIC
-         LDOPTIONS = -fPIC
-
-     Then, execute ``make``.
-
-   * Download `MUMPS <http://graal.ens-lyon.fr/MUMPS/>`_. In order to install
-     it, copy ``Make.inc/Makefile.gfortran.SEQ`` to ``Makefile.inc``, and
-     edit in it the corresponding lines such they read::
-
-         LMETISDIR = <metisdir>
-         LMETIS    = -L$(LMETISDIR) -lmetis
-
-         ORDERINGSF  = -Dpord -Dmetis
-
-         CC = gcc-mp-4.8
-         FC = gfortran-mp-4.8
-         FL = gfortran-mp-4.8
-
-         LIBBLAS = -lblas
-
-         OPTF = -O -DALLOW_NON_INIT -fPIC
-         OPTL = -O -fPIC
-         OPTC = -O -fPIC
-
-     where ``<metisdir>`` is the directory of METIS.
-
-     Then, execute ``make all``.
-
-4. Unpack tinyarray, enter its directory, build and install::
-
-       python setup.py build
-       sudo python setup.py install
-
-5. (OPTIONAL) To make kwant use MUMPS, go to the kwant directory, and
-   edit ``build.conf`` to read::
-
-       [mumps]
-       include_dirs = <mumpsdir>/include
-       library_dirs = <mumpsdir>/lib <mumpsdir>/libseq <metisdir>/
-       libraries = zmumps mumps_common pord metis mpiseq
-
-   where ``<mumpsdir>`` and <metisdir>`` are the driectories of the previously
-   installed MUMPS and METIS.
-
-6. Then, build and install kwant. ::
-
-       python setup.py build
-       sudo python setup.py install
-
-
-Microsoft Windows
------------------
-
-This describes one way to build a 32 bit (win32) version of kwant without MUMPS
-on Windows using free software only.  These instructions were verified in April
-2013 with the following software versions: Windows XP SP3, Python 2.7.4,
-scipy-stack 13.4.9, mingw-get-inst-20120426, OpenBLAS 0.2.6.
-
-32-bit kwant without MUMPS will be limited to rather small systems and will run
-significantly slower than a kwant with MUMPS.  Volunteers who would like to
-improve these instructions are welcome.
-
-1. Install the official win32 Python 2.7 distribution from `the official Python
-   download page <http://python.org/download/>`_.  See the point "Python 2.7.x
-   Windows Installer" there.
-
-2. Install the Python packages required by kwant (NumPy, SciPy, matplotlib).  An
-   easy way to do so is to install the `scipy-stack package
-   <http://www.lfd.uci.edu/~gohlke/pythonlibs/#scipy-stack>`_ (win32-py2.7)
-   kindly provided by Christoph Gohlke.  Please also note the instructions at
-   the top of that page.
-
-3. Install `MinGW <http://mingw.org/wiki/Getting_Started>`_, the "Minimalist GNU
-   for Windows" (look for "mingw-get-inst" on that page).  This is a version of
-   the GNU Compiler Collection (GCC) for Windows.  Check the boxes for the C,
-   C++, and Fortran compilers and the "MSYS Basic System" when asked about which
-   components to install.  Follow the instructions on the web page linked above
-   (section "Environment Settings") to append ``;C:\MinGW\bin`` to the value of
-   the PATH environment variable (or to create it).
-
-4. Make MinGW the default compiler for distutils: Create the file
-   ``c:\python27\lib\distutils\distutils.cfg`` (The exact path depends on where
-   Python has been installed) with the following contents:
-
-       [build]
-       compiler=mingw32
-
-5. Until this `bug in distutils's support for MinGW
-   <http://bugs.python.org/issue12641>`_ is fixed, work around it by editing
-   ``c:\python27/lib/distutils/cygwinccompiler.py`` and removing all the five
-   occurrences of the string ``-mno-cygwin``.
-
-   Now you have a complete environment for compiling Python extensions.  To be
-   able to build kwant, we need to install the required linear algebra
-   libraries.
-
-6. Download `OpenBLAS <http://xianyi.github.com/OpenBLAS/>`_ (the download link
-   is at the bottom of the page).  Unpack the archive and launch the "MinGW
-   shell".  Inside the shell, the command ``mount`` will inform about how the
-   "drives" of windows are mounted into the single file system of MSYS.
-   Typically, drive C will be /c/.
-
-   Go to the root directory of the OpenBLAS distribution and execute
-
-       mingw-get install msys-wget
-       mingw-get install msys-perl
-       make USE_THREAD=0
-
-   (If you do not want to forcefully disable threading for OpenBLAS, simply use
-   ``make``.)
-
-   This should create a file named like ``libopenblas_nehalem-r0.2.6.lib``
-   where the name of the architecture (here: nehalem) and the version might
-   differ in your case.  Copy this file as ``openblas.lib`` into the library
-   directory of MinGW:
-
-      cp libopenblas_nehalem-r0.2.6.lib /c/MinGW/lib/openblas.lib
-
-7. Unpack tinyarray, enter its directory. To build and install, run ::
-
-       c:\python27\python setup.py build
-       c:\python27\python setup.py install
-
-8. Inside the kwant source distribution's root directory create a file
-   ``build.conf`` with the following contents.::
-
-       [lapack]
-       libraries = openblas gfortran
-
-   Finally, build and install kwant::
-
-       c:\python27\python setup.py build
-       c:\python27\python setup.py install
-
-
-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
-
-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, 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 if you want to modify them.

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

 =============
-kwant License
+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-2015 C. W. Groth (CEA), M. Wimmer, A. R. Akhmerov,
+X. Waintal (CEA), and others.  All rights reserved.
 
-Copyright 2011-2013, kwant authors.  All rights reserved.
+(CEA = Commissariat à l'énergie atomique et aux énergies alternatives)
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:

MANIFEST.in

-# This file specifies the files to be included in the source distribution
-# in addition to the default ones.
-
-include MANIFEST.in
-include INSTALL LICENSE AUTHORS ACKNOWLEDGEMENTS TODO README_WINDOWS.txt
-
-# We explicitly include both pyx and c files, so that both are shipped in
-# source tarballs independently of whether "setup.py sdist" is run with
-# --no-cython or not.
-recursive-include kwant *.pyx
-recursive-include kwant *.pxd
-recursive-include kwant *.c
-recursive-include kwant *.h
-recursive-include examples *.py
-
-include doc/other/*[a-zA-Z]
-include doc/Makefile
-recursive-include doc/source *.rst *.py *.svg *.sh *.diff
-recursive-include doc/source/_static *[a-zA-Z]
-recursive-exclude doc/source/images [a-zA-Z]*.py
-recursive-include doc/templates *[a-zA-Z]
-prune doc/source/reference/generated
-recursive-include doc/sphinxext *.py *.txt *.in

README

-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 (of any dimensionality) that can be described by a
-tight-binding model.  It offers direct support for calculations of Landauer
-transport (conductance, noise), dispersion relations, modes, wave functions,
-various Green's functions, and local density of states.  Being extensible and
-modular, kwant has been designed to be useful for other computations involving
-tight-binding Hamiltonians as well.
-
-See also the files INSTALL, LICENSE, AUTHORS, and ACKNOWLEDGEMENTS 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-*-
-
-* Document the order of sites/orbitals in finalized builders
-
-* Make kwant run on windows
-
-* Add calculation of current density
-
-* Consider making the b parameter of _solve_linear_sys a matrix instead of a
-  list of matrices
-
-* 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
-  - 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.
-
-* 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 slice 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 the slice.
-
-* Add a test of kwant that verifies QHE conductance quantization
-
-* 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.
-  Perhaps a general python module for units would suffice?
-
-* 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.contrib.digest
-  by using SipHash and Ziggurat algorithm in C/Cython