.gitlab-ci.yml

@@ -166,6 +166,14 @@ check for dependencies installed:
 
 
 .test: &test
+  stage: test
+  script:
+    - py.test -r w --flakes kwant --junitxml=tests.xml --durations=10
+  artifacts:
+    reports:
+      junit: tests.xml
+
+.coverage: &coverage
   stage: test
   script:
     - py.test -r w --cov=kwant --cov-report term --cov-report html --flakes kwant --junitxml=tests.xml --durations=10
@@ -215,6 +223,14 @@ test:bleeding-edge:
     - schedules
   allow_failure: true
 
+coverage:latest:
+  <<: *coverage
+  <<: *latest_env
+  dependencies:
+    - build:latest
+  only:
+    - schedules
+
 ## Documentation building
 
 build documentation:
@@ -223,7 +239,9 @@ build documentation:
     - build:latest
   stage: test
   script:
-    - make -C doc realclean; make -C doc html SPHINXOPTS='-A website_deploy=True -n -W' SOURCE_LINK_TEMPLATE="$CI_PROJECT_URL"/blob/\$\$r/\$\$f
+    - pip install git+https://github.com/jupyter-widgets/jupyter-sphinx
+    - python -m ipykernel install --user --name kwant-latest
+    - make -C doc realclean; make -C doc html SPHINXOPTS='-A website_deploy=True -n -W -D jupyter_execute_default_kernel=kwant-latest' SOURCE_LINK_TEMPLATE="$CI_PROJECT_URL"/blob/\$\$r/\$\$f
   artifacts:
     paths:
       - doc/build/html/
@@ -235,7 +253,9 @@ build PDF documentation:
     - build:latest
   stage: test
   script:
-    - make -C doc latex SPHINXOPTS='-n -W'
+    - pip install git+https://github.com/jupyter-widgets/jupyter-sphinx
+    - python -m ipykernel install --user --name kwant-latest
+    - make -C doc latex SPHINXOPTS='-n -W -D jupyter_execute_default_kernel=kwant-latest'
     - cd doc/build/latex
     - make all-pdf
   artifacts:
@@ -258,7 +278,9 @@ check for broken links in doc:
 upload coverage:
   stage: deploy
   only:
-    - branches@kwant/kwant
+    - schedules
+  dependencies:
+    - coverage:latest
   environment:
     name: coverage/$CI_BUILD_REF_NAME
     url: https://kwant-project.org/coverage/$CI_BUILD_REF_SLUG

.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 (either on [stable](https://gitlab.kwant-project.org/kwant/kwant/tree/stable) or on [master](https://gitlab.kwant-project.org/kwant/kwant/tree/master) branch)
+- [ ] Documentation looks correct https://test.kwant-project.org/doc/<branch name>
+- [ ] [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

RELEASE.rst

@@ -3,6 +3,10 @@ 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
 ################
@@ -114,21 +118,23 @@ Building the documentation requires 'sphinx' and a Latex installation.
 First build the HTML and PDF documentation::
 
     ./setup.py build
-    cd doc
-    make realclean
-    make html latex SPHINXOPTS='-A website_deploy=True -n -W'
-    cd doc/build/latex
-    make all-pdf
+    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::
 
-    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
+    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)::
 
-    mv doc/build/latex/kwant.pdf dist/kwant-doc-<version>.pdf
+    make -C doc html SPHINXOPTS='-A website_deploy=True -n -W'
 
 
 Clone the repository of the Kwant Debian package
@@ -514,23 +520,20 @@ Ask Christoph Groth if you need to be granted access.
 
 Upload the zipped HTML and PDF documentation::
 
-    scp dist/kwant-doc-<version>.zip kwant-project.org:webapps/downloads/doc
-    scp dist/kwant-doc-<version>.pdf kwant-project.org:webapps/downloads/doc
-
-Point the symbolic links ``latest.zip`` and ``latest.pdf`` to these new files::
-
-    ssh kwant-project.org "cd webapps/downloads/doc; ln -s kwant-doc-<version>.zip latest.zip"
-    ssh kwant-project.org "cd webapps/downloads/doc; ln -s kwant-doc-<version>.pdf latest.pdf"
+    scp dist/kwant-doc-<version>.{zip,pdf} kwant-project.org:webapps/downloads/doc
 
-Then upload the HTML documentation for the main website::
+Upload the HTML documentation for the website::
 
     rsync -rlv --delete doc/build/html/* kwant-project.org:webapps/kwant/doc/<short-version>
 
 where in the above ``<short-version>`` is just the major and minor version numbers.
 
-Finally point the symbolic link ``<major-version>`` to ``<short-version>``::
+Finally, create symbolic links for the website::
 
-    ssh kwant-project.org "cd webapps/kwant/doc; ln -s <major> <short-version>"
+    ssh kwant-project.org
+    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

doc/source/conf.py

@@ -15,8 +15,15 @@ import sys
 import os
 import string
 from distutils.util import get_platform
-sys.path.insert(0, "../../build/lib.{0}-{1}.{2}".format(
-        get_platform(), *sys.version_info[:2]))
+
+package_path = os.path.abspath(
+    "../../build/lib.{0}-{1}.{2}"
+    .format(get_platform(), *sys.version_info[:2]))
+
+# Insert into sys.path so that we can import kwant here
+sys.path.insert(0, package_path)
+# Insert into PYTHONPATH so that jupyter-sphinx will pick it up
+os.environ['PYTHONPATH'] = ':'.join((package_path, os.environ.get('PYTHONPATH','')))
 
 import kwant
 import kwant.qsymm
@@ -31,7 +38,7 @@ sys.path.insert(0, os.path.abspath('../sphinxext'))
 
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosummary',
               'sphinx.ext.todo', 'sphinx.ext.mathjax', 'numpydoc',
-              'kwantdoc', 'sphinx.ext.linkcode']
+              'kwantdoc', 'sphinx.ext.linkcode', 'jupyter_sphinx.execute']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['../templates']
@@ -239,7 +246,6 @@ autosummary_generate = True
 autoclass_content = "both"
 autodoc_default_flags = ['show-inheritance']
 
-
 # -- Teach Sphinx to document bound methods like functions ---------------------
 import types
 from sphinx.ext import autodoc

doc/source/pre/whatsnew/1.5.rst

+What's new in Kwant 1.5
+=======================
+
+This article explains the user-visible changes in Kwant 1.5.0.

doc/source/pre/whatsnew/index.rst

@@ -2,6 +2,7 @@ What's new in Kwant
 ===================
 
 .. toctree::
+    1.5
     1.4
     1.3
     1.2

doc/source/tutorial/first_steps.rst

@@ -62,13 +62,35 @@ Transport through a quantum wire
 
 .. seealso::
     The complete source code of this example can be found in
-    :download:`quantum_wire.py </code/download/quantum_wire.py>`
+    :jupyter-download:script:`quantum_wire`
 
 In order to use Kwant, we need to import it:
 
-.. literalinclude:: /code/include/quantum_wire.py
-    :start-after: #HIDDEN_BEGIN_dwhx
-    :end-before: #HIDDEN_END_dwhx
+.. jupyter-kernel::
+    :id: quantum_wire
+
+.. jupyter-execute::
+    :hide-code:
+
+    # Tutorial 2.2.2. Transport through a quantum wire
+    # ================================================
+    #
+    # Physics background
+    # ------------------
+    #  Conductance of a quantum wire; subbands
+    #
+    # Kwant features highlighted
+    # --------------------------
+    #  - Builder for setting up transport systems easily
+    #  - Making scattering region and leads
+    #  - Using the simple sparse solver for computing Landauer conductance
+
+    # For plotting
+    from matplotlib import pyplot
+
+.. jupyter-execute::
+
+    import kwant
 
 Enabling Kwant is as easy as this [#]_ !
 
@@ -76,9 +98,11 @@ The first step is now the definition of the system with scattering region and
 leads. For this we make use of the `~kwant.builder.Builder` type that allows to
 define a system in a convenient way. We need to create an instance of it:
 
-.. literalinclude:: /code/include/quantum_wire.py
-    :start-after: #HIDDEN_BEGIN_goiq
-    :end-before: #HIDDEN_END_goiq
+.. jupyter-execute::
+
+    # First define the tight-binding system
+
+    syst = kwant.Builder()
 
 Observe that we just accessed `~kwant.builder.Builder` by the name
 ``kwant.Builder``.  We could have just as well written
@@ -92,9 +116,10 @@ Apart from `~kwant.builder.Builder` we also need to specify
 what kind of sites we want to add to the system. Here we work with
 a square lattice. For simplicity, we set the lattice constant to unity:
 
-.. literalinclude:: /code/include/quantum_wire.py
-    :start-after: #HIDDEN_BEGIN_suwo
-    :end-before: #HIDDEN_END_suwo
+.. jupyter-execute::
+
+    a = 1
+    lat = kwant.lattice.square(a)
 
 Since we work with a square lattice, we label the points with two
 integer coordinates `(i, j)`. `~kwant.builder.Builder` then
@@ -111,9 +136,25 @@ needed in Builder (more about that in the technical details below).
 We now build a rectangular scattering region that is `W`
 lattice points wide and `L` lattice points long:
 
-.. literalinclude:: /code/include/quantum_wire.py
-    :start-after: #HIDDEN_BEGIN_zfvr
-    :end-before: #HIDDEN_END_zfvr
+.. jupyter-execute::
+
+    t = 1.0
+    W, L = 10, 30
+
+    # Define the scattering region
+
+    for i in range(L):
+        for j in range(W):
+            # On-site Hamiltonian
+            syst[lat(i, j)] = 4 * t
+
+            # Hopping in y-direction
+            if j > 0:
+                syst[lat(i, j), lat(i, j - 1)] = -t
+
+            # Hopping in x-direction
+            if i > 0:
+                syst[lat(i, j), lat(i - 1, j)] = -t
 
 Observe how the above code corresponds directly to the terms of the discretized
 Hamiltonian:
@@ -140,9 +181,14 @@ Next, we define the leads. Leads are also constructed using
 `~kwant.builder.Builder`, but in this case, the
 system must have a translational symmetry:
 
-.. literalinclude:: /code/include/quantum_wire.py
-    :start-after: #HIDDEN_BEGIN_xcmc
-    :end-before: #HIDDEN_END_xcmc
+.. jupyter-execute::
+
+     # Then, define and attach the leads:
+
+     # First the lead to the left
+     # (Note: TranslationalSymmetry takes a real-space vector)
+     sym_left_lead = kwant.TranslationalSymmetry((-a, 0))
+     left_lead = kwant.Builder(sym_left_lead)
 
 Here, the `~kwant.builder.Builder` takes a
 `~kwant.lattice.TranslationalSymmetry` as the optional parameter. Note that the
@@ -155,17 +201,22 @@ as the hoppings inside one unit cell and to the next unit cell of the lead.
 For a square lattice, and a lead in y-direction the unit cell is
 simply a vertical line of points:
 
-.. literalinclude:: /code/include/quantum_wire.py
-    :start-after: #HIDDEN_BEGIN_ndez
-    :end-before: #HIDDEN_END_ndez
+.. jupyter-execute::
+
+    for j in range(W):
+        left_lead[lat(0, j)] = 4 * t
+        if j > 0:
+            left_lead[lat(0, j), lat(0, j - 1)] = -t
+        left_lead[lat(1, j), lat(0, j)] = -t
 
 Note that here it doesn't matter if you add the hoppings to the next or the
 previous unit cell -- the translational symmetry takes care of that.  The
 isolated, infinite is attached at the correct position using
 
-.. literalinclude:: /code/include/quantum_wire.py
-    :start-after: #HIDDEN_BEGIN_fskr
-    :end-before: #HIDDEN_END_fskr
+.. jupyter-execute::
+    :hide-output:
+
+     syst.attach_lead(left_lead)
 
 This call returns the lead number which will be used to refer to the lead when
 computing transmissions (further down in this tutorial). More details about
@@ -175,9 +226,21 @@ We also want to add a lead on the right side. The only difference to
 the left lead is that the vector of the translational
 symmetry must point to the right, the remaining code is the same:
 
-.. literalinclude:: /code/include/quantum_wire.py
-    :start-after: #HIDDEN_BEGIN_xhqc
-    :end-before: #HIDDEN_END_xhqc
+.. jupyter-execute::
+    :hide-output:
+
+    # Then the lead to the right
+
+    sym_right_lead = kwant.TranslationalSymmetry((a, 0))
+    right_lead = kwant.Builder(sym_right_lead)
+
+    for j in range(W):
+        right_lead[lat(0, j)] = 4 * t
+        if j > 0:
+            right_lead[lat(0, j), lat(0, j - 1)] = -t
+        right_lead[lat(1, j), lat(0, j)] = -t
+
+    syst.attach_lead(right_lead)
 
 Note that here we added points with x-coordinate 0, just as for the left lead.
 You might object that the right lead should be placed `L`
@@ -187,13 +250,9 @@ you do not need to worry about that.
 Now we have finished building our system! We plot it, to make sure we didn't
 make any mistakes:
 
-.. literalinclude:: /code/include/quantum_wire.py
-    :start-after: #HIDDEN_BEGIN_wsgh
-    :end-before: #HIDDEN_END_wsgh
+.. jupyter-execute::
 
-This should bring up this picture:
-
-.. image:: /code/figure/quantum_wire_syst.*
+    kwant.plot(syst);
 
 The system is represented in the usual way for tight-binding systems:
 dots represent the lattice points `(i, j)`, and for every
@@ -203,16 +262,29 @@ fading color.
 
 In order to use our system for a transport calculation, we need to finalize it
 
-.. literalinclude:: /code/include/quantum_wire.py
-    :start-after: #HIDDEN_BEGIN_dngj
-    :end-before: #HIDDEN_END_dngj
+.. jupyter-execute::
+
+     # Finalize the system
+     syst = syst.finalized()
 
 Having successfully created a system, we now can immediately start to compute
 its conductance as a function of energy:
 
-.. literalinclude:: /code/include/quantum_wire.py
-    :start-after: #HIDDEN_BEGIN_buzn
-    :end-before: #HIDDEN_END_buzn
+.. jupyter-execute::
+
+    # Now that we have the system, we can compute conductance
+    energies = []
+    data = []
+    for ie in range(100):
+        energy = ie * 0.01
+
+        # compute the scattering matrix at a given energy
+        smatrix = kwant.smatrix(syst, energy)
+
+        # compute the transmission probability from lead 0 to
+        # lead 1
+        energies.append(energy)
+        data.append(smatrix.transmission(1, 0))
 
 We use ``kwant.smatrix`` which is a short name for
 `kwant.solvers.default.smatrix` of the default solver module
@@ -227,13 +299,15 @@ Finally we can use ``matplotlib`` to make a plot of the computed data
 (although writing to file and using an external viewer such as
 gnuplot or xmgrace is just as viable)
 
-.. literalinclude:: /code/include/quantum_wire.py
-    :start-after: #HIDDEN_BEGIN_lliv
-    :end-before: #HIDDEN_END_lliv
-
-This should yield the result
+.. jupyter-execute::
 
-.. image:: /code/figure/quantum_wire_result.*
+    # Use matplotlib to write output
+    # We should see conductance steps
+    pyplot.figure()
+    pyplot.plot(energies, data)
+    pyplot.xlabel("energy [t]")
+    pyplot.ylabel("conductance [e^2/h]")
+    pyplot.show()
 
 We see a conductance quantized in units of :math:`e^2/h`,
 increasing in steps as the energy is increased. The
@@ -333,7 +407,12 @@ Building the same system with less code
 
 .. seealso::
     The complete source code of this example can be found in
-    :download:`quantum_wire_revisited.py </code/download/quantum_wire_revisited.py>`
+    :jupyter-download:script:`quantum_wire_revisited`
+
+
+.. jupyter-kernel::
+    :id: quantum_wire_revisited
+
 
 Kwant allows for more than one way to build a system. The reason is that
 `~kwant.builder.Builder` is essentially just a container that can be filled in
@@ -347,19 +426,51 @@ the code into separate entities. In this example we therefore also aim at more
 structure.
 
 We begin the program collecting all imports in the beginning of the
-file and put the build-up of the system into a separate function
-`make_system`:
+file and defining the a square lattice and empty scattering region.
+
+.. jupyter-execute::
+    :hide-code:
+
+    # Tutorial 2.2.3. Building the same system with less code
+    # =======================================================
+    #
+    # Physics background
+    # ------------------
+    #  Conductance of a quantum wire; subbands
+    #
+    # Kwant features highlighted
+    # --------------------------
+    #  - Using iterables and builder.HoppingKind for making systems
+    #  - introducing `reversed()` for the leads
+    #
+    # Note: Does the same as tutorial1a.py, but using other features of Kwant.
+
+.. jupyter-execute::
+
+    import kwant
+
+    # For plotting
+    from matplotlib import pyplot
+
+    a = 1
+    t = 1.0
+    W, L = 10, 30
+
+    # Start with an empty tight-binding system and a single square lattice.
+    # `a` is the lattice constant (by default set to 1 for simplicity).
+    lat = kwant.lattice.square(a)
+
+    syst = kwant.Builder()
 
-.. literalinclude:: /code/include/quantum_wire_revisited.py
-    :start-after: #HIDDEN_BEGIN_xkzy
-    :end-before: #HIDDEN_END_xkzy
 
 Previously, the scattering region was build using two ``for``-loops.
 Instead, we now write:
 
-.. literalinclude:: /code/include/quantum_wire_revisited.py
-    :start-after: #HIDDEN_BEGIN_vvjt
-    :end-before: #HIDDEN_END_vvjt
+
+.. jupyter-execute::
+
+    syst[(lat(x, y) for x in range(L) for y in range(W))] = 4 * t
+
 
 Here, all lattice points are added at once in the first line.  The
 construct ``((i, j) for i in range(L) for j in range(W))`` is a
@@ -375,9 +486,9 @@ hoppings. In this case, an iterable like for the lattice
 points becomes a bit cumbersome, and we use instead another
 feature of Kwant:
 
-.. literalinclude:: /code/include/quantum_wire_revisited.py
-    :start-after: #HIDDEN_BEGIN_nooi
-    :end-before: #HIDDEN_END_nooi
+.. jupyter-execute::
+
+    syst[lat.neighbors()] = -t
 
 In regular lattices, hoppings form large groups such that hoppings within a
 group can be transformed into one another by lattice translations. In order to
@@ -397,9 +508,11 @@ values for all the nth-nearest neighbors at once, one can similarly use
 
 The left lead is constructed in an analogous way:
 
-.. literalinclude:: /code/include/quantum_wire_revisited.py
-    :start-after: #HIDDEN_BEGIN_iepx
-    :end-before: #HIDDEN_END_iepx
+.. jupyter-execute::
+
+    lead = kwant.Builder(kwant.TranslationalSymmetry((-a, 0)))
+    lead[(lat(0, j) for j in range(W))] = 4 * t
+    lead[lat.neighbors()] = -t
 
 The previous example duplicated almost identical code for the left and
 the right lead.  The only difference was the direction of the translational
@@ -408,30 +521,59 @@ symmetry vector.  Here, we only construct the left lead, and use the method
 of a lead pointing in the opposite direction.  Both leads are attached as
 before and the finished system returned:
 
-.. literalinclude:: /code/include/quantum_wire_revisited.py
-    :start-after: #HIDDEN_BEGIN_yxot
-    :end-before: #HIDDEN_END_yxot
+.. jupyter-execute::
+    :hide-output:
+
+    syst.attach_lead(lead)
+    syst.attach_lead(lead.reversed())
+
 
 The remainder of the script has been organized into two functions.  One for the
 plotting of the conductance.
 
-.. literalinclude:: /code/include/quantum_wire_revisited.py
-    :start-after: #HIDDEN_BEGIN_ayuk
-    :end-before: #HIDDEN_END_ayuk
+
+.. jupyter-execute::
+
+    def plot_conductance(syst, energies):
+        # Compute conductance
+        data = []
+        for energy in energies:
+            smatrix = kwant.smatrix(syst, energy)
+            data.append(smatrix.transmission(1, 0))
+
+        pyplot.figure()
+        pyplot.plot(energies, data)
+        pyplot.xlabel("energy [t]")
+        pyplot.ylabel("conductance [e^2/h]")
+        pyplot.show()
 
 And one ``main`` function.
 
-.. literalinclude:: /code/include/quantum_wire_revisited.py
-    :start-after: #HIDDEN_BEGIN_cjel
-    :end-before: #HIDDEN_END_cjel
+.. jupyter-execute::
+
+    def main():
+        # Check that the system looks as intended.
+        kwant.plot(syst)
+
+        # Finalize the system.
+        fsyst = syst.finalized()
+
+        # We should see conductance steps.
+        plot_conductance(fsyst, energies=[0.01 * i for i in range(100)])
+
 
 Finally, we use the following standard Python construct [#]_ to execute
 ``main`` if the program is used as a script (i.e. executed as
 ``python quantum_wire_revisited.py``):
 
-.. literalinclude:: /code/include/quantum_wire_revisited.py
-    :start-after: #HIDDEN_BEGIN_ypbj
-    :end-before: #HIDDEN_END_ypbj
+
+.. jupyter-execute::
+
+    # Call the main function if the script gets executed (as opposed to imported).
+    # See <http://docs.python.org/library/__main__.html>.
+    if __name__ == '__main__':
+        main()
+
 
 If the example, however, is imported inside Python using ``import
 quantum_wire_revisted as qw``, ``main`` is not executed automatically.
@@ -453,11 +595,9 @@ The result of the example should be identical to the previous one.
 
      For technical reasons it is not possible to add several points
      using a tuple of sites. Hence it is worth noting
-     a subtle detail in
+     a subtle detail in:
 
-     .. literalinclude:: /code/include/quantum_wire_revisited.py
-         :start-after: #HIDDEN_BEGIN_vvjt
-         :end-before: #HIDDEN_END_vvjt
+     >>> syst[(lat(x, y) for x in range(L) for y in range(W))] = 4 * t
 
      Note that ``(lat(x, y) for x in range(L) for y in range(W))`` is not
      a tuple, but a generator.

doc/source/tutorial/spectrum.rst

@@ -6,7 +6,29 @@ Band structure calculations
 
 .. seealso::
     The complete source code of this example can be found in
-    :download:`band_structure.py </code/download/band_structure.py>`
+    :jupyter-download:script:`band_structure`
+
+.. jupyter-kernel::
+    :id: band_structure
+
+.. jupyter-execute::
+    :hide-code:
+
+    # Tutorial 2.4.1. Band structure calculations
+    # ===========================================
+    #
+    # Physics background
+    # ------------------
+    #  band structure of a simple quantum wire in tight-binding approximation
+    #
+    # Kwant features highlighted
+    # --------------------------
+    #  - Computing the band structure of a finalized lead.
+
+    import kwant
+
+    # For plotting
+    from matplotlib import pyplot
 
 When doing transport simulations, one also often needs to know the band
 structure of the leads, i.e. the energies of the propagating plane waves in the
@@ -19,9 +41,26 @@ tight-binding wire.
 Computing band structures in Kwant is easy. Just define a lead in the
 usual way:
 
-.. literalinclude:: /code/include/band_structure.py
-    :start-after: #HIDDEN_BEGIN_zxip
-    :end-before: #HIDDEN_END_zxip
+.. jupyter-execute::
+
+    def make_lead(a=1, t=1.0, W=10):
+        # Start with an empty lead with a single square lattice
+        lat = kwant.lattice.square(a)
+
+        sym_lead = kwant.TranslationalSymmetry((-a, 0))
+        lead = kwant.Builder(sym_lead)
+
+        # build up one unit cell of the lead, and add the hoppings
+        # to the next unit cell
+        for j in range(W):
+            lead[lat(0, j)] = 4 * t
+
+            if j > 0:
+                lead[lat(0, j), lat(0, j - 1)] = -t
+
+            lead[lat(1, j), lat(0, j)] = -t
+
+        return lead
 
 "Usual way" means defining a translational symmetry vector, as well
 as one unit cell of the lead, and the hoppings to neighboring
@@ -42,13 +81,24 @@ do something more profound with the dispersion relation these energies may be
 calculated directly using `~kwant.physics.Bands`. For now we just plot the
 bandstructure:
 
-.. literalinclude:: /code/include/band_structure.py
-    :start-after: #HIDDEN_BEGIN_pejz
-    :end-before: #HIDDEN_END_pejz
+.. jupyter-execute::
+
+    def main():
+        lead = make_lead().finalized()
+        kwant.plotter.bands(lead, show=False)
+        pyplot.xlabel("momentum [(lattice constant)^-1]")
+        pyplot.ylabel("energy [t]")
+        pyplot.show()
 
 This gives the result:
 
-.. image:: /code/figure/band_structure_result.*
+.. jupyter-execute::
+    :hide-code:
+
+    # Call the main function if the script gets executed (as opposed to imported).
+    # See <http://docs.python.org/library/__main__.html>.
+    if __name__ == '__main__':
+        main()
 
 where we observe the cosine-like dispersion of the square lattice. Close
 to ``k=0`` this agrees well with the quadratic dispersion this tight-binding
@@ -61,7 +111,31 @@ Closed systems
 
 .. seealso::
     The complete source code of this example can be found in
-    :download:`closed_system.py </code/download/closed_system.py>`
+    :jupyter-download:script:`closed_system`
+
+.. jupyter-kernel::
+    :id: closed_system
+
+.. jupyter-execute::
+    :hide-code:
+
+    # Tutorial 2.4.2. Closed systems
+    # ==============================
+    #
+    # Physics background
+    # ------------------
+    #  Fock-darwin spectrum of a quantum dot (energy spectrum in
+    #  as a function of a magnetic field)
+    #
+    # Kwant features highlighted
+    # --------------------------
+    #  - Use of `hamiltonian_submatrix` in order to obtain a Hamiltonian
+    #    matrix.
+
+    from cmath import exp
+    import numpy as np
+    from matplotlib import pyplot
+    import kwant
 
 Although Kwant is (currently) mainly aimed towards transport problems, it
 can also easily be used to compute properties of closed systems -- after
@@ -74,16 +148,49 @@ To compute the eigenenergies and eigenstates, we will make use of the sparse
 linear algebra functionality of `SciPy <https://www.scipy.org>`_, which
 interfaces the ARPACK package:
 
-.. literalinclude:: /code/include/closed_system.py
-    :start-after: #HIDDEN_BEGIN_tibv
-    :end-before: #HIDDEN_END_tibv
+
+.. jupyter-execute::
+
+    # For eigenvalue computation
+    import scipy.sparse.linalg as sla
 
 We set up the system using the `shape`-function as in
 :ref:`tutorial-abring`, but do not add any leads:
 
-.. literalinclude:: /code/include/closed_system.py
-    :start-after: #HIDDEN_BEGIN_qlyd
-    :end-before: #HIDDEN_END_qlyd
+.. jupyter-execute::
+    :hide-code:
+
+    a = 1
+    t = 1.0
+    r = 10
+
+.. jupyter-execute::
+
+    def make_system(a=1, t=1.0, r=10):
+
+        lat = kwant.lattice.square(a, norbs=1)
+
+        syst = kwant.Builder()
+
+        # Define the quantum dot
+        def circle(pos):
+            (x, y) = pos
+            rsq = x ** 2 + y ** 2
+            return rsq < r ** 2
+
+        def hopx(site1, site2, B):
+            # The magnetic field is controlled by the parameter B
+            y = site1.pos[1]
+            return -t * exp(-1j * B * y)
+
+        syst[lat.shape(circle, (0, 0))] = 4 * t
+        # hoppings in x-direction
+        syst[kwant.builder.HoppingKind((1, 0), lat, lat)] = hopx
+        # hoppings in y-directions
+        syst[kwant.builder.HoppingKind((0, 1), lat, lat)] = -t
+
+        # It's a closed system for a change, so no leads
+        return syst
 
 We add the magnetic field using a function and a global variable as we
 did in the two previous tutorial. (Here, the gauge is chosen such that
@@ -93,14 +200,40 @@ The spectrum can be obtained by diagonalizing the Hamiltonian of the
 system, which in turn can be obtained from the finalized
 system using `~kwant.system.System.hamiltonian_submatrix`:
 
-.. literalinclude:: /code/include/closed_system.py
-    :start-after: #HIDDEN_BEGIN_yvri
-    :end-before: #HIDDEN_END_yvri
+.. jupyter-execute::
+
+    def plot_spectrum(syst, Bfields):
+
+        energies = []
+        for B in Bfields:
+            # Obtain the Hamiltonian as a sparse matrix
+            ham_mat = syst.hamiltonian_submatrix(params=dict(B=B), sparse=True)
+
+            # we only calculate the 15 lowest eigenvalues
+            ev = sla.eigsh(ham_mat.tocsc(), k=15, sigma=0,
+                           return_eigenvectors=False)
+
+            energies.append(ev)
+
+        pyplot.figure()
+        pyplot.plot(Bfields, energies)
+        pyplot.xlabel("magnetic field [arbitrary units]")
+        pyplot.ylabel("energy [t]")
+        pyplot.show()
 
 Note that we use sparse linear algebra to efficiently calculate only a
 few lowest eigenvalues. Finally, we obtain the result:
 
-.. image:: /code/figure/closed_system_result.*
+.. jupyter-execute::
+    :hide-code:
+
+    syst = make_system()
+
+    syst = syst.finalized()
+
+    # We should observe energy levels that flow towards Landau
+    # level energies with increasing magnetic field.
+    plot_spectrum(syst, [iB * 0.002 for iB in range(100)])
 
 At zero magnetic field several energy levels are degenerate (since our
 quantum dot is rather symmetric). These degeneracies are split
@@ -110,11 +243,34 @@ Landau level energies at higher magnetic fields [#]_.
 The eigenvectors are obtained very similarly, and can be plotted directly
 using `~kwant.plotter.map`:
 
-.. literalinclude:: /code/include/closed_system.py
-    :start-after: #HIDDEN_BEGIN_wave
-    :end-before: #HIDDEN_END_wave
+.. jupyter-execute::
+    :hide-code:
+
+    def sorted_eigs(ev):
+        evals, evecs = ev
+        evals, evecs = map(np.array, zip(*sorted(zip(evals, evecs.transpose()))))
+        return evals, evecs.transpose()
+
+.. jupyter-execute::
+
+    def plot_wave_function(syst, B=0.001):
+        # Calculate the wave functions in the system.
+        ham_mat = syst.hamiltonian_submatrix(sparse=True, params=dict(B=B))
+        evals, evecs = sorted_eigs(sla.eigsh(ham_mat.tocsc(), k=20, sigma=0))
+
+        # Plot the probability density of the 10th eigenmode.
+        kwant.plotter.map(syst, np.abs(evecs[:, 9])**2,
+                          colorbar=False, oversampling=1)
 
-.. image:: /code/figure/closed_system_eigenvector.*
+.. jupyter-execute::
+    :hide-code:
+
+    syst = make_system(r=30)
+
+    # Plot an eigenmode of a circular dot. Here we create a larger system for
+    # better spatial resolution.
+    syst = make_system(r=30).finalized()
+    plot_wave_function(syst);
 
 The last two arguments to `~kwant.plotter.map` are optional.  The first prevents
 a colorbar from appearing.  The second, ``oversampling=1``, makes the image look
@@ -127,11 +283,22 @@ that they can have *non-zero* local current. We can calculate the local
 current due to a state by using `kwant.operator.Current` and plotting
 it using `kwant.plotter.current`:
 
-.. literalinclude:: /code/include/closed_system.py
-    :start-after: #HIDDEN_BEGIN_current
-    :end-before: #HIDDEN_END_current
+.. jupyter-execute::
+
+    def plot_current(syst, B=0.001):
+        # Calculate the wave functions in the system.
+        ham_mat = syst.hamiltonian_submatrix(sparse=True, params=dict(B=B))
+        evals, evecs = sorted_eigs(sla.eigsh(ham_mat.tocsc(), k=20, sigma=0))
+
+        # Calculate and plot the local current of the 10th eigenmode.
+        J = kwant.operator.Current(syst)
+        current = J(evecs[:, 9], params=dict(B=B))
+        kwant.plotter.current(syst, current, colorbar=False)
+
+.. jupyter-execute::
+    :hide-code:
 
-.. image:: /code/figure/closed_system_current.*
+    plot_current(syst);
 
 .. specialnote:: Technical details
 

doc/source/tutorial/spin_potential_shape.rst

@@ -11,7 +11,10 @@ Matrix structure of on-site and hopping elements
 
 .. seealso::
     The complete source code of this example can be found in
-    :download:`spin_orbit.py </code/download/spin_orbit.py>`
+    :jupyter-download:script:`spin_orbit`
+
+.. jupyter-kernel::
+    :id: spin_orbit
 
 We begin by extending the simple 2DEG-Hamiltonian by a Rashba spin-orbit
 coupling and a Zeeman splitting due to an external magnetic field:
@@ -42,24 +45,75 @@ use matrices in our program, we import the Tinyarray package.  (`NumPy
 <http://www.numpy.org/>`_ would work as well, but Tinyarray is much faster
 for small arrays.)
 
-.. literalinclude:: /code/include/spin_orbit.py
-    :start-after: #HIDDEN_BEGIN_xumz
-    :end-before: #HIDDEN_END_xumz
+.. jupyter-execute::
+    :hide-code:
+
+    # Tutorial 2.3.1. Matrix structure of on-site and hopping elements
+    # ================================================================
+    #
+    # Physics background
+    # ------------------
+    #  Gaps in quantum wires with spin-orbit coupling and Zeeman splititng,
+    #  as theoretically predicted in
+    #   http://prl.aps.org/abstract/PRL/v90/i25/e256601
+    #  and (supposedly) experimentally oberved in
+    #   http://www.nature.com/nphys/journal/v6/n5/abs/nphys1626.html
+    #
+    # Kwant features highlighted
+    # --------------------------
+    #  - Numpy matrices as values in Builder
+
+    import kwant
+
+    # For plotting
+    from matplotlib import pyplot
+
+.. jupyter-execute::
+
+    # For matrix support
+    import tinyarray
 
 For convenience, we define the Pauli-matrices first (with :math:`\sigma_0` the
 unit matrix):
 
-.. literalinclude:: /code/include/spin_orbit.py
-    :start-after: #HIDDEN_BEGIN_hwbt
-    :end-before: #HIDDEN_END_hwbt
+.. jupyter-execute::
+
+    # define Pauli-matrices for convenience
+    sigma_0 = tinyarray.array([[1, 0], [0, 1]])
+    sigma_x = tinyarray.array([[0, 1], [1, 0]])
+    sigma_y = tinyarray.array([[0, -1j], [1j, 0]])
+    sigma_z = tinyarray.array([[1, 0], [0, -1]])
 
 Previously, we used numbers as the values of our matrix elements.
 However, `~kwant.builder.Builder` also accepts matrices as values, and
 we can simply write:
 
-.. literalinclude:: /code/include/spin_orbit.py
-    :start-after: #HIDDEN_BEGIN_uxrm
-    :end-before: #HIDDEN_END_uxrm
+.. jupyter-execute::
+    :hide-code:
+
+    # Start with an empty tight-binding system and a single square lattice.
+    # `a` is the lattice constant (by default set to 1 for simplicity).
+    lat = kwant.lattice.square()
+
+    syst = kwant.Builder()
+
+    t = 1.0
+    alpha = 0.5
+    e_z = 0.08
+    W, L = 10, 30
+
+
+.. jupyter-execute::
+
+    #### Define the scattering region. ####
+    syst[(lat(x, y) for x in range(L) for y in range(W))] = \
+        4 * t * sigma_0 + e_z * sigma_z
+    # hoppings in x-direction
+    syst[kwant.builder.HoppingKind((1, 0), lat, lat)] = \
+        -t * sigma_0 + 1j * alpha * sigma_y / 2
+    # hoppings in y-directions
+    syst[kwant.builder.HoppingKind((0, 1), lat, lat)] = \
+        -t * sigma_0 - 1j * alpha * sigma_x / 2
 
 Note that the Zeeman energy adds to the onsite term, whereas the Rashba
 spin-orbit term adds to the hoppings (due to the derivative operator).
@@ -85,14 +139,49 @@ when specifying `(1, 0)` it is not necessary to specify `(-1, 0)`),
 
 The leads also allow for a matrix structure,
 
-.. literalinclude:: /code/include/spin_orbit.py
-    :start-after: #HIDDEN_BEGIN_yliu
-    :end-before: #HIDDEN_END_yliu
+
+.. jupyter-execute::
+    :hide-code:
+
+    #### Define the left lead. ####
+    lead = kwant.Builder(kwant.TranslationalSymmetry((-1, 0)))
+
+.. jupyter-execute::
+
+    lead[(lat(0, j) for j in range(W))] = 4 * t * sigma_0 + e_z * sigma_z
+    # hoppings in x-direction
+    lead[kwant.builder.HoppingKind((1, 0), lat, lat)] = \
+        -t * sigma_0 + 1j * alpha * sigma_y / 2
+    # hoppings in y-directions
+    lead[kwant.builder.HoppingKind((0, 1), lat, lat)] = \
+        -t * sigma_0 - 1j * alpha * sigma_x / 2
+
+.. jupyter-execute::
+    :hide-code:
+
+    #### Attach the leads and finalize the system. ####
+    syst.attach_lead(lead)
+    syst.attach_lead(lead.reversed())
+    syst = syst.finalized()
 
 The remainder of the code is unchanged, and as a result we should obtain
 the following, clearly non-monotonic conductance steps:
 
-.. image:: /code/figure/spin_orbit_result.*
+.. jupyter-execute::
+    :hide-code:
+
+    # Compute conductance
+    energies=[0.01 * i - 0.3 for i in range(100)]
+    data = []
+    for energy in energies:
+        smatrix = kwant.smatrix(syst, energy)
+        data.append(smatrix.transmission(1, 0))
+
+    pyplot.figure()
+    pyplot.plot(energies, data)
+    pyplot.xlabel("energy [t]")
+    pyplot.ylabel("conductance [e^2/h]")
+    pyplot.show()
 
 .. specialnote:: Technical details
 
@@ -129,7 +218,29 @@ Spatially dependent values through functions
 
 .. seealso::
     The complete source code of this example can be found in
-    :download:`quantum_well.py </code/download/quantum_well.py>`
+    :jupyter-download:script:`quantum_well`
+
+.. jupyter-kernel::
+    :id: quantum_well
+
+.. jupyter-execute::
+    :hide-code:
+
+    # Tutorial 2.3.2. Spatially dependent values through functions
+    # ============================================================
+    #
+    # Physics background
+    # ------------------
+    #  transmission through a quantum well
+    #
+    # Kwant features highlighted
+    # --------------------------
+    #  - Functions as values in Builder
+
+    import kwant
+
+    # For plotting
+    from matplotlib import pyplot
 
 Up to now, all examples had position-independent matrix-elements
 (and thus translational invariance along the wire, which
@@ -148,22 +259,57 @@ changing the potential then implies the need to build up the system again.
 Instead, we use a python *function* to define the onsite energies. We
 define the potential profile of a quantum well as:
 
-.. literalinclude:: /code/include/quantum_well.py
-    :start-after: #HIDDEN_BEGIN_ehso
-    :end-before: #HIDDEN_END_ehso
+.. jupyter-execute::
+    :hide-code:
+
+    a = 1
+    t = 1.0
+    W, L, L_well = 10, 30, 10
+
+.. jupyter-execute::
+
+    # Start with an empty tight-binding system and a single square lattice.
+    # `a` is the lattice constant (by default set to 1 for simplicity).
+    lat = kwant.lattice.square(a)
+
+    syst = kwant.Builder()
+
+    #### Define the scattering region. ####
+    # Potential profile
+    def potential(site, pot):
+        (x, y) = site.pos
+        if (L - L_well) / 2 < x < (L + L_well) / 2:
+            return pot
+        else:
+            return 0
 
 This function takes two arguments: the first of type `~kwant.builder.Site`,
 from which you can get the real-space coordinates using ``site.pos``, and the
 value of the potential as the second.  Note that in `potential` we can access
-variables of the surrounding function: `L` and `L_well` are taken from the
-namespace of `make_system`.
+variables `L` and `L_well` that are defined globally.
 
 Kwant now allows us to pass a function as a value to
 `~kwant.builder.Builder`:
 
-.. literalinclude:: /code/include/quantum_well.py
-    :start-after: #HIDDEN_BEGIN_coid
-    :end-before: #HIDDEN_END_coid
+.. jupyter-execute::
+
+    def onsite(site, pot):
+        return 4 * t + potential(site, pot)
+
+    syst[(lat(x, y) for x in range(L) for y in range(W))] = onsite
+    syst[lat.neighbors()] = -t
+
+.. jupyter-execute::
+    :hide-code:
+
+    #### Define and attach the leads. ####
+    lead = kwant.Builder(kwant.TranslationalSymmetry((-a, 0)))
+    lead[(lat(0, j) for j in range(W))] = 4 * t
+    lead[lat.neighbors()] = -t
+    syst.attach_lead(lead)
+    syst.attach_lead(lead.reversed())
+
+    syst = syst.finalized()
 
 For each lattice point, the corresponding site is then passed as the
 first argument to the function `onsite`. The values of any additional
@@ -180,9 +326,21 @@ of the lead -- this should be kept in mind.
 
 Finally, we compute the transmission probability:
 
-.. literalinclude:: /code/include/quantum_well.py
-    :start-after: #HIDDEN_BEGIN_sqvr
-    :end-before: #HIDDEN_END_sqvr
+.. jupyter-execute::
+
+    def plot_conductance(syst, energy, welldepths):
+
+        # Compute conductance
+        data = []
+        for welldepth in welldepths:
+            smatrix = kwant.smatrix(syst, energy, params=dict(pot=-welldepth))
+            data.append(smatrix.transmission(1, 0))
+
+        pyplot.figure()
+        pyplot.plot(welldepths, data)
+        pyplot.xlabel("well depth [t]")
+        pyplot.ylabel("conductance [e^2/h]")
+        pyplot.show()
 
 ``kwant.smatrix`` allows us to specify a dictionary, `params`, that contains
 the additional arguments required by the Hamiltonian matrix elements.
@@ -191,7 +349,11 @@ of the potential well by passing the potential value (remember above
 we defined our `onsite` function that takes a parameter named `pot`).
 We obtain the result:
 
-.. image:: /code/figure/quantum_well_result.*
+.. jupyter-execute::
+    :hide-code:
+
+    plot_conductance(syst, energy=0.2,
+                     welldepths=[0.01 * i for i in range(100)])
 
 Starting from no potential (well depth = 0), we observe the typical
 oscillatory transmission behavior through resonances in the quantum well.
@@ -218,7 +380,35 @@ Nontrivial shapes
 
 .. seealso::
     The complete source code of this example can be found in
-    :download:`ab_ring.py </code/download/ab_ring.py>`
+    :jupyter-download:script:`ab_ring`
+
+.. jupyter-kernel::
+    :id: ab_ring
+
+.. jupyter-execute::
+    :hide-code:
+
+    # Tutorial 2.3.3. Nontrivial shapes
+    # =================================
+    #
+    # Physics background
+    # ------------------
+    #  Flux-dependent transmission through a quantum ring
+    #
+    # Kwant features highlighted
+    # --------------------------
+    #  - More complex shapes with lattices
+    #  - Allows for discussion of subtleties of `attach_lead` (not in the
+    #    example, but in the tutorial main text)
+    #  - Modifcations of hoppings/sites after they have been added
+
+    from cmath import exp
+    from math import pi
+
+    import kwant
+
+    # For plotting
+    from matplotlib import pyplot
 
 Up to now, we only dealt with simple wire geometries. Now we turn to the case
 of a more complex geometry, namely transport through a quantum ring
@@ -238,9 +428,29 @@ First, define a boolean function defining the desired shape, i.e. a function
 that returns ``True`` whenever a point is inside the shape, and
 ``False`` otherwise:
 
-.. literalinclude:: /code/include/ab_ring.py
-    :start-after: #HIDDEN_BEGIN_eusz
-    :end-before: #HIDDEN_END_eusz
+.. jupyter-execute::
+    :hide-code:
+
+    a = 1
+    t = 1.0
+    W = 10
+    r1, r2 = 10, 20
+
+.. jupyter-execute::
+
+    # Start with an empty tight-binding system and a single square lattice.
+    # `a` is the lattice constant (by default set to 1 for simplicity).
+
+    lat = kwant.lattice.square(a)
+
+    syst = kwant.Builder()
+
+    #### Define the scattering region. ####
+    # Now, we aim for a more complex shape, namely a ring (or annulus)
+    def ring(pos):
+        (x, y) = pos
+        rsq = x ** 2 + y ** 2
+        return (r1 ** 2 < rsq < r2 ** 2)
 
 Note that this function takes a real-space position as argument (not a
 `~kwant.builder.Site`).
@@ -249,9 +459,11 @@ We can now simply add all of the lattice points inside this shape at
 once, using the function `~kwant.lattice.Square.shape`
 provided by the lattice:
 
-.. literalinclude:: /code/include/ab_ring.py
-    :start-after: #HIDDEN_BEGIN_lcak
-    :end-before: #HIDDEN_END_lcak
+.. jupyter-execute::
+
+    # and add the corresponding lattice points using the `shape`-function
+    syst[lat.shape(ring, (0, r1 + 1))] = 4 * t
+    syst[lat.neighbors()] = -t
 
 Here, ``lat.shape`` takes as a second parameter a (real-space) point that is
 inside the desired shape. The hoppings can still be added using
@@ -264,9 +476,30 @@ along the branch cut in the lower arm of the ring. For this we select
 all hoppings in x-direction that are of the form `(lat(1, j), lat(0, j))`
 with ``j<0``:
 
-.. literalinclude:: /code/include/ab_ring.py
-    :start-after: #HIDDEN_BEGIN_lvkt
-    :end-before: #HIDDEN_END_lvkt
+.. jupyter-execute::
+
+    # In order to introduce a flux through the ring, we introduce a phase on
+    # the hoppings on the line cut through one of the arms.  Since we want to
+    # change the flux without modifying the Builder instance repeatedly, we
+    # define the modified hoppings as a function that takes the flux as its
+    # parameter phi.
+    def hopping_phase(site1, site2, phi):
+        return -t * exp(1j * phi)
+
+    def crosses_branchcut(hop):
+        ix0, iy0 = hop[0].tag
+
+        # builder.HoppingKind with the argument (1, 0) below
+        # returns hoppings ordered as ((i+1, j), (i, j))
+        return iy0 < 0 and ix0 == 1  # ix1 == 0 then implied
+
+    # Modify only those hopings in x-direction that cross the branch cut
+    def hops_across_cut(syst):
+        for hop in kwant.builder.HoppingKind((1, 0), lat, lat)(syst):
+            if crosses_branchcut(hop):
+                yield hop
+
+    syst[hops_across_cut] = hopping_phase
 
 Here, `crosses_branchcut` is a boolean function that returns ``True`` for
 the desired hoppings. We then use again a generator (this time with
@@ -279,9 +512,19 @@ by the parameter `phi`.
 
 For the leads, we can also use the ``lat.shape``-functionality:
 
-.. literalinclude:: /code/include/ab_ring.py
-    :start-after: #HIDDEN_BEGIN_qwgr
-    :end-before: #HIDDEN_END_qwgr
+.. jupyter-execute::
+
+    #### Define the leads. ####
+    # left lead
+    sym_lead = kwant.TranslationalSymmetry((-a, 0))
+    lead = kwant.Builder(sym_lead)
+
+    def lead_shape(pos):
+        (x, y) = pos
+        return (-W / 2 < y < W / 2)
+
+    lead[lat.shape(lead_shape, (0, 0))] = 4 * t
+    lead[lat.neighbors()] = -t
 
 Here, the shape must be compatible with the translational symmetry
 of the lead ``sym_lead``. In particular, this means that it should extend to
@@ -290,9 +533,12 @@ no restriction on ``x`` in ``lead_shape``) [#]_.
 
 Attaching the leads is done as before:
 
-.. literalinclude:: /code/include/ab_ring.py
-    :start-after: #HIDDEN_BEGIN_skbz
-    :end-before: #HIDDEN_END_skbz
+.. jupyter-execute::
+    :hide-output:
+
+    #### Attach the leads ####
+    syst.attach_lead(lead)
+    syst.attach_lead(lead.reversed())
 
 In fact, attaching leads seems not so simple any more for the current
 structure with a scattering region very much different from the lead
@@ -309,12 +555,36 @@ the lead is attached:
 
 After the lead has been attached, the system should look like this:
 
-.. image:: /code/figure/ab_ring_syst.*
+.. jupyter-execute::
+    :hide-code:
+
+    kwant.plot(syst);
 
 The computation of the conductance goes in the same fashion as before.
 Finally you should get the following result:
 
-.. image:: /code/figure/ab_ring_result.*
+
+.. jupyter-execute::
+    :hide-code:
+
+    def plot_conductance(syst, energy, fluxes):
+        # compute conductance
+
+        normalized_fluxes = [flux / (2 * pi) for flux in fluxes]
+        data = []
+        for flux in fluxes:
+            smatrix = kwant.smatrix(syst, energy, params=dict(phi=flux))
+            data.append(smatrix.transmission(1, 0))
+
+        pyplot.figure()
+        pyplot.plot(normalized_fluxes, data)
+        pyplot.xlabel("flux [flux quantum]")
+        pyplot.ylabel("conductance [e^2/h]")
+        pyplot.show()
+
+    # We should see a conductance that is periodic with the flux quantum
+    plot_conductance(syst.finalized(), energy=0.15,
+                     fluxes=[0.01 * i * 3 * 2 * pi for i in range(100)])
 
 where one can observe the conductance oscillations with the
 period of one flux quantum.
@@ -330,7 +600,41 @@ period of one flux quantum.
     becomes more apparent if we attach the leads a bit further away
     from the central axis o the ring, as was done in this example:
 
-    .. image:: /code/figure/ab_ring_note1.*
+    .. jupyter-kernel::
+        :id: ab_ring_note1
+
+    .. jupyter-execute::
+        :hide-code:
+
+        import kwant
+        from matplotlib import pyplot
+
+        a = 1
+        t = 1.0
+        W = 10
+        r1, r2 = 10, 20
+
+        lat = kwant.lattice.square()
+        syst = kwant.Builder()
+        def ring(pos):
+            (x, y) = pos
+            rsq = x**2 + y**2
+            return ( r1**2 < rsq < r2**2)
+        syst[lat.shape(ring, (0, 11))] = 4 * t
+        syst[lat.neighbors()] = -t
+        sym_lead0 = kwant.TranslationalSymmetry((-a, 0))
+        lead0 = kwant.Builder(sym_lead0)
+        def lead_shape(pos):
+            (x, y) = pos
+            return (-1 < x < 1) and ( 0.5 * W < y < 1.5 * W )
+        lead0[lat.shape(lead_shape, (0, W))] = 4 * t
+        lead0[lat.neighbors()] = -t
+        lead1 = lead0.reversed()
+        syst.attach_lead(lead0)
+        syst.attach_lead(lead1)
+
+        kwant.plot(syst);
+
 
   - Per default, `~kwant.builder.Builder.attach_lead` attaches
     the lead to the "outside" of the structure, by tracing the
@@ -345,7 +649,40 @@ period of one flux quantum.
     starts the trace-back in the middle of the ring, resulting
     in the lead being attached to the inner circle:
 
-    .. image:: /code/figure/ab_ring_note2.*
+    .. jupyter-kernel::
+        :id: ab_ring_note2
+
+    .. jupyter-execute::
+        :hide-code:
+
+        import kwant
+        from matplotlib import pyplot
+
+        a = 1
+        t = 1.0
+        W = 10
+        r1, r2 = 10, 20
+
+        lat = kwant.lattice.square(a)
+        syst = kwant.Builder()
+        def ring(pos):
+            (x, y) = pos
+            rsq = x**2 + y**2
+            return ( r1**2 < rsq < r2**2)
+        syst[lat.shape(ring, (0, 11))] = 4 * t
+        syst[lat.neighbors()] = -t
+        sym_lead0 = kwant.TranslationalSymmetry((-a, 0))
+        lead0 = kwant.Builder(sym_lead0)
+        def lead_shape(pos):
+            (x, y) = pos
+            return (-1 < x < 1) and ( -W/2 < y < W/2  )
+        lead0[lat.shape(lead_shape, (0, 0))] = 4 * t
+        lead0[lat.neighbors()] = -t
+        lead1 = lead0.reversed()
+        syst.attach_lead(lead0)
+        syst.attach_lead(lead1, lat(0, 0))
+
+        kwant.plot(syst);
 
     Note that here the lead is treated as if it would pass over
     the other arm of the ring, without intersecting it.

kwant/__init__.py

@@ -29,22 +29,29 @@ except ImportError:
         raise
 
 from ._common import KwantDeprecationWarning, UserCodeError
-
 __all__.extend(['KwantDeprecationWarning', 'UserCodeError'])
 
-for module in ['system', 'builder', 'lattice', 'solvers', 'digest', 'rmt',
-               'operator', 'kpm', 'wraparound']:
-    exec('from . import {0}'.format(module))
-    __all__.append(module)
+# Pre-import most submodules.  (We make exceptions for submodules that have
+# special dependencies or where that would take too long.)
+from . import system
+from . import builder
+from . import lattice
+from . import solvers
+from . import digest
+from . import rmt
+from . import operator
+from . import kpm
+from . import wraparound
+__all__.extend(['system', 'builder', 'lattice', 'solvers', 'digest', 'rmt',
+                'operator', 'kpm', 'wraparound'])
 
 # Make selected functionality available directly in the root namespace.
-available = [('builder', ['Builder', 'HoppingKind']),
-             ('lattice', ['TranslationalSymmetry']),
-             ('solvers.default',
-              ['smatrix', 'greens_function', 'ldos', 'wave_function'])]
-for module, names in available:
-    exec('from .{0} import {1}'.format(module, ', '.join(names)))
-    __all__.extend(names)
+from .builder import Builder, HoppingKind
+__all__.extend(['Builder', 'HoppingKind'])
+from .lattice import TranslationalSymmetry
+__all__.extend(['TranslationalSymmetry'])
+from .solvers.default import smatrix, greens_function, ldos, wave_function
+__all__.extend(['smatrix', 'greens_function', 'ldos', 'wave_function'])
 
 # Importing plotter might not work, but this does not have to be a problem --
 # only no plotting will be available.

kwant/continuum/__init__.py

@@ -15,6 +15,5 @@ except ImportError as error:
            "dependencies is not installed.")
     raise ImportError(msg) from error
 
-
 __all__ = ['discretize', 'discretize_symbolic', 'build_discretized',
            'sympify', 'lambdify', 'momentum_operators', 'position_operators']

kwant/graph/__init__.py

@@ -9,8 +9,7 @@
 """Functionality for graphs"""
 
 # Merge the public interface of all submodules.
-__all__ = []
-for module in ['core', 'defs']:
-    exec('from . import {0}'.format(module))
-    exec('from .{0} import *'.format(module))
-    exec('__all__.extend({0}.__all__)'.format(module))
+from .core import *
+from .defs import *
+
+__all__ = [core.__all__ + defs.__all__]

kwant/linalg/__init__.py

@@ -10,7 +10,10 @@ __all__ = ['lapack']
 from . import lapack
 
 # Merge the public interface of the other submodules.
-for module in ['decomp_lu', 'decomp_ev', 'decomp_schur']:
-    exec('from . import {0}'.format(module))
-    exec('from .{0} import *'.format(module))
-    exec('__all__.extend({0}.__all__)'.format(module))
+from .decomp_lu import *
+from .decomp_schur import *
+from .decomp_ev import *
+
+__all__.extend([decomp_lu.__all__,
+                decomp_ev.__all__,
+                decomp_schur.__all__])

kwant/physics/__init__.py

@@ -8,8 +8,14 @@
 """Physics-related algorithms"""
 
 # Merge the public interface of all submodules.
-__all__ = []
-for module in ['leads', 'dispersion', 'noise', 'symmetry', 'gauge']:
-    exec('from . import {0}'.format(module))
-    exec('from .{0} import *'.format(module))
-    exec('__all__.extend({0}.__all__)'.format(module))
+from .leads import *
+from .dispersion import *
+from .noise import *
+from .symmetry import *
+from .gauge import *
+
+__all__ = [leads.__all__
+           + dispersion.__all__
+           + noise.__all__
+           + symmetry.__all__
+           + gauge.__all__]

pytest.ini

 [pytest]
 testpaths = kwant
 flakes-ignore =
-    __init__.py UnusedImport
+    __init__.py UnusedImport ImportStarUsed ImportStarUsage
     kwant/_plotter.py UnusedImport
     graph/tests/test_scotch.py UndefinedName
-    graph/tests/test_dissection.py UndefinedName