.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

@@ -2,17 +2,19 @@
 *.pyc
 *.pyo
 *.so
+*.pyd
 /kwant/*.c
 /kwant/*/*.c
-/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.rst

@@ -2,36 +2,55 @@
 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
+The Kwant authors can be reached at authors@kwant-project.org.
 
-* Daniel Jaschke (SPSMS-INAC-CEA Grenoble)
-* Joseph Weston (SPSMS-INAC-CEA Grenoble)
-
-We thank Christoph Gohlke for the creation of Windows installers.
+The principal developers of Kwant are
 
-`CEA <http://cea.fr>`_ is the French Commissariat à l'énergie atomique et aux
+* `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 <http://git-scm.com/>`_, the version control system.
+`Git <https://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.
+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

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

@@ -4,81 +4,8 @@ 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.
+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.

README.rst

@@ -28,10 +28,11 @@ Kwant can calculate
 Other computations involving tight-binding Hamiltonians can be implemented
 easily.
 
-See the `Kwant web site <http://kwant-project.org/>`_ for the latest version.  A
-`mailing list <http://kwant-project.org/community>`_ is available for
-discussions, questions, and reporting bugs. The development of Kwant can be
-followed via the `public git repository <http://git.kwant-project.org/kwant>`_.
+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.
 
-See also in this directory: `<INSTALL.rst>`_, `<LICENSE.rst>`_, `<AUTHORS.rst>`_,
-`<CITING.rst>`_, `<CONTRIBUTE.rst>`_.
+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>`_.

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
-
-* 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
-
-* Improve lattice.neighbors()
-  to support the following cases:
-  - The lattice has lower dimensionality than the space
-  - Hoppings between sites from two separate lattices
-
-  The function should be rewritten in a more robust manner using Delaunay
-  tessellation from Scipy/QHull and a proper choice of the set of sites on
-  which to perform the tessellation.
-
-* 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.)
-
-* Harmonize numerical tolerances throughout Kwant
-  By default, a channel should open at the same energy in any solver.
-  If this is possible, we may want to have one central tolerance setting.
-
-* Plotter: show site upon click
-
-* fix physics.noise (docstring, __all__, etc.)
-
-* Verify that selective plotting works.
-
-* Improve support for imperfect lattices / amorphous systems.
-  - Provide a "list of atoms" site group
-  - Allow attaching leads in real space: attach_lead(realspace=True)
-  - Add example / tutorial
-
-* 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.  Fixing unit cells could be postponed
-  until a lead is attached.
-
-* 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.
-
-* Implement a pretty printer for lists/tuples of sites
-
-* Ensure 100% test coverage
-
-* Ideas for kwant 2
-** Consider whether to use *args or args in System.hamiltonian
-
-** lead_info
-Currently, lead_info is either of two things, a sequence of propagating modes or a sequence of self-energies.
-- There is no need to have lead_info as an attribute of BlockResult.
-- In the case of SMatrix and GreensFunction this attribute should be renamed to what it is, i.e. propagating_modes and selfenergies.
-- In cases where a common name is needed (i.e. return value of _make_linear_sys), a better name might be lead_data or solved_leads.
-- BlockResult itself could be renamed to something more specific, perhaps GeneralSMatrix.
-
-** Unify the order of indices
-For example in wave_function and in PropagatingModes.
-
-** Take advantage of when a system is known to be Hermitian
-Either
-- omit the lead with most open channels by default when calling smatrix and greens_function or
-- verify that the scattering matrix is indeed current-conserving (it might be not due to numerical error)
-
-** lattices
-- In add_site_family, the first argument cannot be a general site family, it must be a lattice from lattice.py.  We should rename site_family -> lattice in this context.  In fact, that argument could be even a Polyatomic lattice (that is not a site family at all).
-- The automatically selected other_vectors could be longer but more orthogonal.
-
-** modes
-When on a band edge, the calculation of modes should fail in a clear way, for example by raising kwant.UndefinedResultError (itself derived from ValueError).  We could also provide a function (tentative name: kwant.tolerate) that turns such exceptions into None values (useful for plotting).
-
-** hamiltonian_submatrix and hamiltonian
-Systems have both methods and its confusing which does what.

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

conftest.py

+# Copyright 2011-2018 Kwant authors.
+#
+# This file is part of Kwant.  It is subject to the license terms in the file
+# LICENSE.rst found in the top-level directory of this distribution and at
+# https://kwant-project.org/license.  A list of Kwant authors can be found in
+# the file AUTHORS.rst at the top-level directory of this distribution and at
+# https://kwant-project.org/authors.
+"""Pytest plugin to ignore packages that have uninstalled dependencies.
+
+This ignores packages on test collection, which is required when the
+tests reside in a package that itself requires the dependency to be
+installed.
+"""
+
+import importlib
+
+
+# map from subpackage to sequence of dependency module names
+subpackage_dependencies = {
+    'kwant/continuum': ['sympy'],
+    'kwant/tests/test_qsymm': ['qsymm', 'sympy'],
+}
+
+
+# map from subpackage to sequence of dependency modules that are not installed
+dependencies_not_installed = {}
+for package, dependencies in subpackage_dependencies.items():
+    not_installed = []
+    for dep in dependencies:
+        try:
+            importlib.import_module(dep)
+        except ImportError:
+            not_installed.append(dep)
+    if len(not_installed) != 0:
+        dependencies_not_installed[package] = not_installed
+
+
+def pytest_ignore_collect(path, config):
+    for subpackage, not_installed in dependencies_not_installed.items():
+        if subpackage in path.strpath:
+            print('ignoring {} because the following dependencies are not '
+                  'installed: {}'.format(subpackage, ', '.join(not_installed)))
+            return True

doc/Makefile

-# Makefile for Sphinx documentation
-
-# Copyright 2011-2013 Kwant authors.
+# Minimal makefile for Sphinx documentation
 #
-# This file is part of Kwant.  It is subject to the license terms in the file
-# LICENSE.rst found in the top-level directory of this distribution and at
-# http://kwant-project.org/license.  A list of Kwant authors can be found in
-# the file AUTHORS.rst at the top-level directory of this distribution and at
-# http://kwant-project.org/authors.
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
-PAPER         =
+SOURCEDIR     = source
 BUILDDIR      = build
 
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
-
-# We convert all SVG files to PDF for LaTeX output.  For HTML output, we don't
-# create PNGs but rather use the SVG files directly.
-IMAGESOURCES    = $(shell find source -name "*.svg")
-GENERATEDPDF    = $(patsubst %.svg,%.pdf,$(IMAGESOURCES))
-
-# Image generation from patched tutorial scripts
-#
-# As make does not support the generation of multiple targets by a single
-# invocation of a (non-implicit) rule, we use a trick: We pretend to be
-# generating a single (empty) flag file per invocation.  The image files are
-# generated as well, but only as side-effects.  Each flag file is used to
-# remember the time at which the corresponding image-generating script was run.
-# This works perfectly unless the actual output files are deleted without
-# deleting the corresponding flag file.
-SCRIPTS = $(patsubst source/images/%.diff,%,$(wildcard source/images/*.py.diff))
-FLAGS = $(patsubst %.py,source/images/.%_flag,$(SCRIPTS))
-
-.PHONY: help clean realclean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
-
+# Put it first so that "make" without argument is like "make help".
 help:
-	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html      to make standalone HTML files"
-	@echo "  dirhtml   to make HTML files named index.html in directories"
-	@echo "  pickle    to make pickle files"
-	@echo "  json      to make JSON files"
-	@echo "  htmlhelp  to make HTML files and a HTML help project"
-	@echo "  qthelp    to make HTML files and a qthelp project"
-	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  changes   to make an overview of all changed/added/deprecated items"
-	@echo "  linkcheck to check all external links for integrity"
-	@echo "  doctest   to run all doctests embedded in the documentation (if enabled)"
-
-clean:
-	-rm -rf $(BUILDDIR)/* $(GENERATEDPDF)
-	-rm -rf source/reference/generated
-
-realclean: clean
-	-rm -f $(FLAGS)
-	-rm -f $(patsubst %,source/images/%,$(SCRIPTS))
-	-rm -f $(patsubst %.py,source/images/%_*.png,$(SCRIPTS))
-	-rm -f $(patsubst %.py,source/images/%_*.pdf,$(SCRIPTS))
-
-html:	$(FLAGS)
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-dirhtml: $(FLAGS)
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+.PHONY: help Makefile
 
-pickle: $(FLAGS)
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
-	@echo
-	@echo "Build finished; now you can process the pickle files."
-
-json:   $(FLAGS)
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
-	@echo
-	@echo "Build finished; now you can process the JSON files."
-
-htmlhelp: $(FLAGS)
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
-	@echo
-	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in $(BUILDDIR)/htmlhelp."
-
-qthelp: $(FLAGS)
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
-	@echo
-	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
-	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/kwant.qhcp"
-	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/kwant.qhc"
-
-latex:  $(GENERATEDPDF) $(FLAGS)
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo
-	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
-	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
-	      "run these through (pdf)latex."
-
-changes:
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
-	@echo
-	@echo "The overview file is in $(BUILDDIR)/changes."
-
-linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
-	@echo
-	@echo "Link check complete; look for any errors in the above output " \
-	      "or in $(BUILDDIR)/linkcheck/output.txt."
-
-doctest:
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
-	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/doctest/output.txt."
-
-%.pdf: %.svg
-	rsvg-convert -f pdf -o $@ $<
-
-# Make the image generation scripts by patching tutorial scipts.
-.SECONDARY:
-%.py: %.py.diff
-	@grep -v '^#HIDDEN' source/tutorial/$(notdir $@) >$@
-	@patch $@ $<
+clean:
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-# The image generation scripts depend on their unpatched originals
-define makedep
-source/images/$(1): source/tutorial/$(1)
-endef
-$(foreach name,$(SCRIPTS),$(eval $(call makedep,$(name))))
+latex:
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-# Generation of images
-.%_flag: %.py
-	cd $(dir $<) && python $(notdir $<)
-	@touch $@
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/kwantdoctheme/static/kwantdoctheme.css

-/* This theme is based on pydoctheme by Georg Brandl. */
-
-@import url("default.css");
-
-body {
-    background-color: white;
-    margin-left: 1em;
-    margin-right: 1em;
-}
-
-/* Disable typewriter font in headings. */
-h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
-    font-family: "Bitstream Vera Sans", Verdana, sans-serif;
-    font-size: 100%;
-}
-
-div.body p, div.body dd, div.body li {
-    -webkit-hyphens: auto;
-    -moz-hyphens: auto;
-    -ms-hyphens: auto;
-    -o-hyphens: auto;
-    hyphens: auto;
-}
-
-div.related {
-    margin-bottom: 1.2em;
-    padding: 0.5em 0;
-    border-top: 1px solid #ccc;
-    margin-top: 0.5em;
-}
-
-dt:target, .highlighted {
-    background-color: #fbf1aa;
-}
-
-div.related:first-child {
-    border-top: 0;
-    border-bottom: 1px solid #ccc;
-}
-
-div.sphinxsidebar {
-    background-color: #eeeeee;
-    border-radius: 5px;
-    line-height: 130%;
-    font-size: smaller;
-    overflow: hidden;
-}
-
-div.sphinxsidebar h3, div.sphinxsidebar h4 {
-    margin-top: 1.5em;
-}
-
-div.sphinxsidebarwrapper > h3:first-child {
-    margin-top: 0.2em;
-}
-
-div.sphinxsidebarwrapper > ul > li > ul > li {
-    margin-bottom: 0.4em;
-}
-
-div.sphinxsidebar input {
-    font-family: 'Bitstream Vera Serif',  Georgia, serif
-    border: 1px solid #999999;
-    font-size: smaller;
-    border-radius: 3px;
-}
-
-div.sphinxsidebar input[type=text] {
-    max-width: 220px;
-}
-
-div.body {
-    padding: 0 0 0 1.2em;
-}
-
-div.body p {
-    line-height: 140%;
-}
-
-div.body h1, div.body h2, div.body h3, div.body h4, div.body h5, div.body h6 {
-    margin: 0;
-    border: 0;
-    padding: 0.3em 0;
-}
-
-div.body hr {
-    border: 0;
-    background-color: #ccc;
-    height: 1px;
-}
-
-div.body pre {
-    border-radius: 3px;
-    border: 1px solid #ac9;
-}
-
-div.body div.admonition, div.body div.impl-detail {
-    border-radius: 3px;
-}
-
-div.body div.impl-detail > p {
-    margin: 0;
-}
-
-div.body div.seealso {
-    border: 1px solid #dddd66;
-}
-
-tt, pre {
-    font-family: monospace, sans-serif;
-    font-size: 96.5%;
-    -webkit-hyphens: none;
-    -moz-hyphens: none;
-    -ms-hyphens: none;
-    -o-hyphens: none;
-    hyphens: none;
-}
-
-div.body tt {
-    border-radius: 3px;
-}
-
-div.body tt.descname {
-    font-size: 120%;
-}
-
-div.body tt.xref, div.body a tt {
-    font-weight: normal;
-}
-
-p.deprecated {
-    border-radius: 3px;
-}
-
-table.docutils {
-    border: 1px solid #ddd;
-    min-width: 20%;
-    border-radius: 3px;
-    margin-top: 10px;
-    margin-bottom: 10px;
-}
-
-table.docutils td, table.docutils th {
-    border: 1px solid #ddd !important;
-    border-radius: 3px;
-}
-
-table p, table li {
-    text-align: left !important;
-}
-
-table.docutils th {
-    background-color: #eee;
-    padding: 0.3em 0.5em;
-}
-
-table.docutils td {
-    background-color: white;
-    padding: 0.3em 0.5em;
-}
-
-table.footnote, table.footnote td {
-    border: 0 !important;
-}
-
-div.footer {
-    line-height: 150%;
-    margin-top: -2em;
-    text-align: right;
-    width: auto;
-    margin-right: 10px;
-}
-
-/* have arguments of functions or classes also a monospace font */
-table.longtable.docutils > tbody > tr > td:first-child,
-dl.function > dt,
-dl.class > dt,
-dl.method > dt
-{
-    font-family: "Bitstream Vera Sans Mono", monospace, serif;
-    font-size: 96.5%;
-}
-
-/* rescale font for <tt> so that it is again 96.5% with respect to body */
-table.longtable.docutils > tbody > tr > td:first-child tt,
-dl.function > dt tt,
-dl.class > dt tt,
-dl.method > dt tt
-{
-    font-family: "Bitstream Vera Sans Mono", monospace, serif;
-    font-size: 100%;
-}
-
-td.field-body strong
-{
-    font-family: "Bitstream Vera Sans Mono", monospace, serif;
-    font-size: 96.5%;
-}

doc/kwantdoctheme/theme.conf

-# This theme is based on pydoctheme by Georg Brandl
-
-[theme]
-inherit = default
-stylesheet = kwantdoctheme.css
-pygments_style = sphinx
-
-[options]
-bodyfont = "Bitstream Vera Serif", Georgia, serif
-headfont = "Bitstream Vera Sans", Verdana, sans-serif
-footerbgcolor = white
-footertextcolor = #555555
-relbarbgcolor = white
-relbartextcolor = #666666
-relbarlinkcolor = #444444
-sidebarbgcolor = white
-sidebartextcolor = #444444
-sidebarlinkcolor = #444444
-sidebarwidth = 300
-bgcolor = white
-textcolor = black
-linkcolor = #045e94
-visitedlinkcolor = #045e94
-headtextcolor = black
-headbgcolor = white
-headlinkcolor = #aaaaaa

doc/source/_static/kwant.css

-@import "kwantdoctheme.css";
-
-/* spacing around blockquoted fields in parameters/attributes/returns */
-/* Essential. Otherwise there is way too much space around*/
-td.field-body > blockquote {
-    margin-top: 0.1em;
-    margin-bottom: 0.5em;
-}
-
-.field-list th {
-  /* color: rgb(0,50,150); */
-  /* background-color: #EEE8AA; */
-  white-space: nowrap; /* Essential. Otherwise the colons can break
-                          into a new line */
-}
-
-table.field-list {
-  border-collapse: separate; /* Essential. Otherwise Parameters and Returns
-                                are sharing one solid colored field. That looks
-                                weird. */
-  border-spacing: 10px;
-  border-style: hidden;
-}
-
-div.specialnote-title {
-    font-size: 105%;
-    font-weight: bold;
-    font-color: #3B4D3C;
-    background-color: #DCE4DC;
-    padding: 1em;
-    padding-top: 0.4em;
-    padding-bottom: 0.4em;
-    margin-top: 10px;
-    margin-bottom: 10px;
-    border-width: 1px;
-    border-color: #546C55;
-    border-style: solid;
-}
-
-div.specialnote-body {
-    background-color: #DCE4DC;
-    padding: 1em;
-    padding-top: 0.1em;
-    padding-bottom: 0.4em;
-    margin-top: -10px;
-    margin-bottom: 10px;
-    border-width: 1px;
-    border-top-width: 0px;
-    border-color: #546C55;
-    border-style: solid;
-}

doc/source/_static/mathconf.js

+MathJax.Hub.Config({
+    TeX: {
+        Macros: {
+            bra: ['{\\left\\langle #1\\right|}',1],
+            ket: ['{\\left| #1\\right\\rangle}',1],
+            braket: ['\\left\\langle#1|#2\\right\\rangle', 2],
+            ri: '\\text{i}',
+            rd: '\\text{d}'
+        }
+    }
+});