.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
 /build
 /dist
 /doc/build
 /doc/source/reference/generated/
-/doc/source/images/*.png
-/doc/source/images/*.pdf
-/doc/source/images/.*_flag
+/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

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

+=============
+Kwant license
+=============
+
+Copyright 2011-2015 C. W. Groth (CEA), M. Wimmer, A. R. Akhmerov,
+X. Waintal (CEA), and others.  All rights reserved.
+
+(CEA = Commissariat à l'énergie atomique et aux énergies alternatives)
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

MANIFEST.in

-# This file specifies the files to be included in the source distribution
-# in addition to the default ones.
-
-recursive-include kwant *.pxd
-recursive-include kwant *.h
-recursive-include kwant test_*.py
-
-include TODO.txt
-recursive-include examples *.py
-
-include doc/other/*[a-zA-Z]
-include doc/Makefile
-recursive-include doc/source *.rst *.py *.svg
-recursive-include doc/source/_static *[a-zA-Z]
-recursive-include doc/templates *[a-zA-Z]
-prune doc/source/reference/generated
-recursive-include doc/sphinxext *.py *.txt *.in

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

-=============================================================
-kwant, a package for numerical quantum transport calculations
-=============================================================
-
-Licence
-=======
-
-This software is NOT TO BE DISTRIBUTED, neither in part nor as a whole.
-
-The only exception to this is the ``doc/sphinxext`` subdirectory, which is free
-software.  (See the file ``LICENSE.txt`` in that subdirectory.)
-
-
-Installation
-============
-
-The prerequisites are
-
- - More or less current versions of `Python <http://python.org>`_ and `SciPy
-   <http://scipy.org>`_.  Python 2.6 and scipy 0.7.2 should be enough.
-
- - `Cython <http://cython.org/>`_ -- Version 0.13 works for us.
-
-optional:
-
- - `pycairo <http://cairographics.org/pycairo/>`_ (for plotting)
-
- - `matplotlib <http://matplotlib.sourceforge.net/>`_ (for some of the
-   examples)
-
-kwant can be build and installed using distutils, following standard python
-conventions.  To build and install, run the following commands in the root
-directory of the package. ::
-
-    python setup.py build
-    python setup.py install
-
-The second command has to be run as root (e.g. prefixing it with ``sudo``).  By
-default the package will be installed under ``/usr/local``.  You can change
-this using the ``--prefix`` option, e.g.::
-
-    python setup.py install --prefix=/opt
-
-If you would like to install kwant into your home directory only you can use ::
-
-    python setup.py install --home=~
-
-This does not require superuser priviledges.  If you install kwant in this way
-be sure to tell python where to find it.  This can be done by setting the
-``PYTHONPATH`` environment variable::
-
-    export PYTHONPATH=$HOME/lib/python
-
-You can make this setting permanent by adding this line to your the file
-``.bashrc`` in your home directory.
-
-To check successful installation try executing some examples in the
-``examples`` subdirectory.
-
-
-Documentation
-=============
-
-To build the documentation, kwant has to be installed as described in the
-previous section.  The `sphinx documentation generator
-<http://sphinx.pocoo.org/>`_ is required.
-
-HTML documentation can be built by entering the ``doc`` subdirectory of the
-kwant package and executing ``make html``.  PDF documentation is generated by
-executing ``make latex`` followed by a ``make all-pdf`` in ``doc/build/latex``.
-
-Because of some quirks of how sphinx works, it might be necessary to execute
-``make clean`` between building HTML and PDF documentation.  If this is not
-done, sphinx might mistakenly use PNG files for PDF output.
-
-Please consult the documentation for further information on how to use kwant.
-
-
-Hacking
-=======
-
-To work on the library 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:
-
-* Please keep the code consistent by adhering to the already used naming and
-  formatting conventions.  We generally follow the `"Style Guide for Python
-  Code" <http://www.python.org/dev/peps/pep-0008/>`_ and the `"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.
-
-
-Tests
-=====
-
-We use the `nose testing framework
-<http://somethingaboutorange.com/mrl/projects/nose/>`_.  To run the tests,
-execute the command ``nosetests`` from the root directory of the package after
-it has been built in place.

README_WINDOWS.txt

+A note for users of Microsoft Windows
+-------------------------------------
+
+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.txt

-Roughly in order of importance.                                     -*-org-*-
-
-* Define a few benchmarks and check performance.  Optimize the code.
-
-* Write a fast tiny array module.
-  (If this turns out to be a performance bottleneck.)
-
-* Provide support for calculating and nicely plotting LDOS.
-  Make a tutorial example for this.
-
-* Allow attaching lead with further then nearest slice hoppings.
-  The most easy way to do this is increasing the period of the lead.
-
-* Optionally show site coordinates when plotting a system.
-
-* Add support for easily adding magnetic field to a system.
-
-* Generalize InfiniteSystem to multiple directions.
-
-* Add support for optimization of lead fundamental domains.
-
-* Write a module to generate "functional" random numbers.
-  This is a good starting point:
-  http://www.cs.umbc.edu/~olano/papers/GPUTEA.pdf
-
-* Write a RGF solver which uses graph/slicer.
-
-* Implement the C solver interface.
-
-* Wrap TB_SIM as a solver.
-
-* Wrap umfpack or some other sparse linear algebra library with Cython.
-  Use it directly in sparse solver.  This will allow to fine-tune the solution
-  of sparse systems.

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
+# Minimal makefile for Sphinx documentation
 #
 
 # 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
-
-# In difference to the original Makefile, 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))
-
-# Tutorial images.
-TUTORIAL1A_IMAGES = source/images/tutorial1a_result.png source/images/tutorial1a_result.pdf source/images/tutorial1a_sys.png source/images/tutorial1a_sys.pdf
-TUTORIAL2A_IMAGES = source/images/tutorial2a_result.png source/images/tutorial2a_result.pdf
-TUTORIAL2B_IMAGES = source/images/tutorial2b_result.png source/images/tutorial2b_result.pdf
-TUTORIAL2C_IMAGES = source/images/tutorial2c_result.png source/images/tutorial2c_result.pdf source/images/tutorial2c_sys.png source/images/tutorial2c_sys.pdf source/images/tutorial2c_note1.png source/images/tutorial2c_note1.pdf source/images/tutorial2c_note2.png source/images/tutorial2c_note2.pdf
-TUTORIAL3A_IMAGES = source/images/tutorial3a_result.png source/images/tutorial3a_result.pdf
-TUTORIAL3B_IMAGES = source/images/tutorial3b_result.png source/images/tutorial3b_result.pdf source/images/tutorial3b_sys.png source/images/tutorial3b_sys.pdf
-TUTORIAL4_IMAGES = source/images/tutorial4_result.png source/images/tutorial4_result.pdf source/images/tutorial4_sys1.png source/images/tutorial4_sys1.pdf source/images/tutorial4_sys2.png source/images/tutorial4_sys2.pdf source/images/tutorial4_bs.png source/images/tutorial4_bs.pdf
-ALL_TUTORIAL_IMAGES = $(TUTORIAL1A_IMAGES)  $(TUTORIAL2A_IMAGES) $(TUTORIAL2B_IMAGES) $(TUTORIAL2C_IMAGES) $(TUTORIAL3A_IMAGES) $(TUTORIAL3B_IMAGES) $(TUTORIAL4_IMAGES)
-
-.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 $(ALL_TUTORIAL_IMAGES) source/images/.*_flag
-
-html:	$(ALL_TUTORIAL_IMAGES)
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
-dirhtml: $(ALL_TUTORIAL_IMAGES)
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
-
-pickle: $(ALL_TUTORIAL_IMAGES)
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
-	@echo
-	@echo "Build finished; now you can process the pickle files."
-
-json:   $(ALL_TUTORIAL_IMAGES)
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
-	@echo
-	@echo "Build finished; now you can process the JSON files."
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-htmlhelp: $(ALL_TUTORIAL_IMAGES)
-	$(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."
+.PHONY: help Makefile
 
-qthelp: $(ALL_TUTORIAL_IMAGES)
-	$(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) $(ALL_TUTORIAL_IMAGES)
-	$(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
-	inkscape --export-pdf=$@ $<
-
-# Generation of tutorial images.  This requires some serious make trickery, see
-# http://article.gmane.org/gmane.comp.gnu.make.general/5806
-$(TUTORIAL1A_IMAGES): source/images/.tutorial1a_flag
-	@:
-source/images/.tutorial1a_flag: source/images/tutorial1a.py
-	cd source/images/ && python tutorial1a.py
-	touch source/images/.tutorial1a_flag
-
-$(TUTORIAL2A_IMAGES): source/images/.tutorial2a_flag
-	@:
-source/images/.tutorial2a_flag: source/images/tutorial2a.py
-	cd source/images/ && python tutorial2a.py
-	touch source/images/.tutorial2a_flag
-
-$(TUTORIAL2B_IMAGES): source/images/.tutorial2b_flag
-	@:
-source/images/.tutorial2b_flag: source/images/tutorial2b.py
-	cd source/images/ && python tutorial2b.py
-	touch source/images/.tutorial2b_flag
-
-$(TUTORIAL2C_IMAGES): source/images/.tutorial2c_flag
-	@:
-source/images/.tutorial2c_flag: source/images/tutorial2c.py
-	cd source/images/ && python tutorial2c.py
-	touch source/images/.tutorial2c_flag
-
-$(TUTORIAL3A_IMAGES): source/images/.tutorial3a_flag
-	@:
-source/images/.tutorial3a_flag: source/images/tutorial3a.py
-	cd source/images/ && python tutorial3a.py
-	touch source/images/.tutorial3a_flag
+clean:
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-$(TUTORIAL3B_IMAGES): source/images/.tutorial3b_flag
-	@:
-source/images/.tutorial3b_flag: source/images/tutorial3b.py
-	cd source/images/ && python tutorial3b.py
-	touch source/images/.tutorial3b_flag
+latex:
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-$(TUTORIAL4_IMAGES): source/images/.tutorial4_flag
-	@:
-source/images/.tutorial4_flag: source/images/tutorial4.py
-	cd source/images/ && python tutorial4.py
-	touch source/images/.tutorial4_flag
+# 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)