doc/source/pre/whatsnew/1.3.rst

@@ -5,7 +5,7 @@ This article explains the user-visible changes in Kwant 1.3.0,
 released on 19 May 2017.
 See also the `full list of changes up to the most recent bugfix
 release of the 1.3 series
-<https://gitlab.kwant-project.org/kwant/kwant/compare/v1.3.0...latest-1.3>`_.
+<https://gitlab.kwant-project.org/kwant/kwant/-/compare/v1.3.0...latest-1.3>`_.
 
 Using high-symmetry builders as models
 --------------------------------------
@@ -28,11 +28,43 @@ tight-binding band structures or construct systems with different/lower
 symmetry. For example in just a few lines we can construct a two-band model that exhibits
 a quantum anomalous spin Hall phase:
 
-.. literalinclude:: ../../code/include/plot_qahe.py
-    :start-after: HIDDEN_BEGIN_model
-    :end-before: HIDDEN_END_model
+.. jupyter-kernel::
+    :id: plot_qahe
+
+.. jupyter-execute::
+    :hide-code:
+
+    # Comprehensive example: quantum anomalous Hall effect
+    # ====================================================
+    #
+    # Physics background
+    # ------------------
+    # + Quantum anomalous Hall effect
+    #
+    # Features highlighted
+    # --------------------
+    # + Use of `kwant.continuum` to discretize a continuum Hamiltonian
+    # + Use of `kwant.operator` to compute local current
+    # + Use of `kwant.plotter.current` to plot local current
+
+    import math
+    import matplotlib.pyplot
+    import kwant
+    import kwant.continuum
+
+.. jupyter-execute:: ../../tutorial/boilerplate.py
+    :hide-code:
+
+.. jupyter-execute::
 
-From: :download:`QAHE example script <../../code/download/plot_qahe.py>`
+    def make_model(a):
+        ham = ("alpha * (k_x * sigma_x - k_y * sigma_y)"
+               "+ (m + beta * kk) * sigma_z"
+               "+ (gamma * kk + U) * sigma_0")
+        subs = {"kk": "k_x**2 + k_y**2"}
+        return kwant.continuum.discretize(ham, locals=subs, grid=a)
+
+From: :jupyter-download-script:`plot_qahe`
 
 See the tutorial: :doc:`../../tutorial/discretize`
 
@@ -71,13 +103,47 @@ The example below shows edge states of a quantum anomalous Hall phase
 of the two-band model shown in the `above section
 <#tools-for-continuum-hamiltonians>`_:
 
-.. literalinclude:: ../../code/include/plot_qahe.py
-    :start-after: HIDDEN_BEGIN_current
-    :end-before: HIDDEN_END_current
+.. jupyter-execute::
+    :hide-code:
+
+    def make_system(model, L):
+        def lead_shape(site):
+            x, y = site.pos / L
+            return abs(y) < 0.5
+
+        # QPC shape: a rectangle with 2 gaussians
+        # etched out of the top and bottom edge.
+        def central_shape(site):
+            x, y = site.pos / L
+            return abs(x) < 3/5 and abs(y) < 0.5 - 0.4 * math.exp(-40 * x**2)
+
+        lead = kwant.Builder(kwant.TranslationalSymmetry(
+            model.lattice.vec((-1, 0))))
+        lead.fill(model, lead_shape, (0, 0))
+
+        syst = kwant.Builder()
+        syst.fill(model, central_shape, (0, 0))
+        syst.attach_lead(lead)
+        syst.attach_lead(lead.reversed())
+
+        return syst.finalized()
+
+    # Set up our model and system, and define the model parameters.
+    params = dict(alpha=0.365, beta=0.686, gamma=0.512, m=-0.01, U=0)
+    model = make_model(1)
+    syst = make_system(model, 70)
+
+    # Calculate the scattering states at energy 'm' coming from the left
+    # lead, and the associated particle current.
+    psi = kwant.wave_function(syst, energy=params['m'], params=params)(0)
+
+.. jupyter-execute::
 
-.. image:: ../../code/figure/plot_qahe_current.*
+    J = kwant.operator.Current(syst).bind(params=params)
+    current = sum(J(p) for p in psi)
+    kwant.plotter.current(syst, current);
 
-From: :download:`QAHE example script <../../code/download/plot_qahe.py>`
+From: :jupyter-download-script:`plot_qahe`
 
 Scattering states with discrete symmetries and conservation laws
 ----------------------------------------------------------------

doc/source/pre/whatsnew/1.4.rst

@@ -338,3 +338,24 @@ Changes in Kwant 1.4.1
   low-level systems.
 - A note about an :ref:`whatsnew13-params-api-change` that ocurred in Kwant
   1.3 was added.
+
+Changes in Kwant 1.4.2
+----------------------
+- Due to bugs in the Qsymm library that required modifying its API, the
+  version of Qsymm that Kwant depends on had to be increased from 1.1.2 to
+  1.2.6.  SInce Qsymm is an optional dependency of Kwant, this
+  backwards-incompatible change only affects Kwant users who use it.
+- Minor bugs were fixed in the KPM module.
+
+Changes in Kwant 1.4.3
+----------------------
+- Builder properly handles Hermitian conjugation of array-like values.
+  Before, if the value was provided not as a true array but, for example, as a
+  list of lists, it was not conjugated, which could lead to generation of a
+  non-Hermitian Hamiltonian matrix without emitting any error.
+- Various maintenance.
+
+Changes in Kwant 1.4.4
+----------------------
+- Ensure compatibility with recent versions of SymPy, matplotlib and Sphinx.
+- Fix current density plotting when sites coincide.

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.
+
+Deprecation of leaving 'norbs' unset for site families
+------------------------------------------------------
+When constructing site families (e.g. lattices) it is now deprecated to
+leave the 'norbs' parameter unset. This will now raise a
+KwantDeprecationWarning and will be disallowed in a future version of
+Kwant. For example, when constructing a square lattice with 1 orbital
+per site, use::
+
+    kwant.lattice.square(norbs=1)
+
+rather than::
+
+    kwant.lattice.square()
+
+
+Plotly for plots
+----------------
+Kwant can now use the `Plotly <https://plotly.com/>`_ library when plotting,
+though matplotlib is still used by default. Using plotly empowers Kwant
+to produce high-quality interactive plots, as well as true 3D support:
+
+.. jupyter-execute::
+    :hide-code:
+
+    import kwant
+    import kwant.plotter
+
+.. jupyter-execute::
+
+    lat = kwant.lattice.cubic(norbs=1)
+    syst = kwant.Builder()
+
+    def disk(r):
+        x, y, z = r
+        return -2 <= z < 2 and 10**2 < x**2 + y**2 < 20**2
+
+    syst[lat.shape(disk, (15, 0, 0))] = 4
+
+    kwant.plotter.set_engine("plotly")
+    kwant.plot(syst);
+
+
+Automatic addition of Peierls phase terms to Builders
+-----------------------------------------------------
+Kwant 1.4 introduced `kwant.physics.magnetic_gauge` for computing Peierls
+phases for arbitrary geometries and for systems with leads. Using this
+functionality requires that the system value functions are equipped to
+take the required Peierls phase parameters, which is not possible when
+you are not in direct control of the value functions (e.g. discretized
+systems). In Kwant 1.5 we have added the missing piece of functionality,
+`kwant.builder.add_peierls_phase`, which properly adds the Peierls phase
+parameters to a Builder's value functions::
+
+    syst = make_system()
+    lead = make_lead()
+    syst.attach_lead(lead)
+    syst.attach_lead(lead.reversed())
+
+    fsyst, phase = kwant.builder.add_peierls_phase(syst)
+
+    def B_syst(pos):
+        return np.exp(-np.sum(pos * pos))
+
+    kwant.smatrix(fsyst, parameters=dict(t=-1, **phase(B_syst, 0, 0)))
+
+
+Improved tutorial building
+--------------------------
+Improving or adding to Kwant's tutorial is now much simpler. Now
+the text and code for each tutorial is kept in the same file, making
+it easy to see where changes need to be made, and images generated by
+the code are inserted directly into the document thanks to the magic of
+`jupyter-sphinx <https://github.com/jupyter/jupyter-sphinx/>`_.
+It has never been easier to get started contributing to Kwant by
+helping us improve our documentation.
+
+We have also updated the docs theme to a more modern sphinx-book-theme.
+
+Discretization onto a Landau level basis
+----------------------------------------
+The Hamiltonian for a system infinite in at least two dimensions and with
+a constant applied magnetic field may be expressed in a basis of Landau levels.
+The momenta in the plane perpendicular to the magnetic field direction are
+written in terms of the Landau level ladder operators:
+
+.. math::
+    k_x = \sqrt{\frac{B}{2}} (a + a^\dagger) \quad\quad
+    k_y = i \sqrt{\frac{B}{2}} (a - a^\dagger)
+
+The Hamiltonian is then expressed in terms of these ladder operators, which
+allows for a straight-forward discretization in the basis of Landau levels,
+provided that the basis is truncated after $N$ levels.
+`kwant.continuum.discretize_landau` makes this procedure simple::
+
+    syst = kwant.continuum.discretize_landau("k_x**2 + k_y**2", N)
+    syst.finalized().hamiltonian_submatrix(params=dict(B=0.5))
+
+`~kwant.continuum.discretize_landau` produces a regular Kwant Builder that
+can be inspected or finalized as usual. 3D Hamiltonians for systems that
+extend into the direction perpendicular to the magnetic field are also
+possible::
+
+    template = kwant.continuum.discretize_landau("k_x**2 + k_y**2 + k_z**2 + V(z)", N)
+
+This will produce a Builder with a single translational symmetry, which can be
+directly finalized, or can be used as a template for e.g. a heterostructure stack
+in the direction of the magnetic field::
+
+    def stack(site):
+        z, = site.pos
+        return 0 <= z < 10
+
+    template = kwant.continuum.discretize_landau("k_x**2 + k_y**2 + k_z**2 + V(z)", N)
+    syst = kwant.Builder()
+    syst.fill(template, stack, (0,))
+
+
+Minimum required versions for some dependencies have increased
+--------------------------------------------------------------
+Kwant now requires at least the following versions:
+
++ Python 3.8
++ numpy 1.18.0
++ scipy 1.3.0
+
+The kwant extensions (plotting, continuum and qsymm) now require at
+least the following versions:
+
++ matplotlib 3.2.2
++ sympy 1.5.1
++ qsymm 1.2.6
+
+These versions (or newer) are available in the latest stable releases
+of Ubuntu and Debian GNU/Linux, with the exception of qsymm, which is
+available on PyPI or Conda forge.
+
+Update of the setup script
+--------------------------
+
+Following the recommendation of py.test, the command ``setup.py test`` is now
+removed. Instead the users should run ``py.test`` directly or use
+``import kwant; kwant.test()``.
+
+Removal of Umfpack support
+--------------------------
+Scipy used to provide a Python interface to the Umfpack library.  This is now
+done by a separate package ``scikit-umfpack``.  Because it is hard for end
+users to obtain this, we have removed built-in support for Umfpack.
+
+Addition of python-mumps wrapper
+--------------------------------
+The Kwant solver relies on the MUMPS library for solving large sparse linear
+systems.  In previous versions this was done using a limited wrapper provided
+by Kwant itself.  In Kwant 1.5 we instead interface with MUMPS using the
+``python-mumps`` package.  Importantly, ``python-mumps`` is available on
+Windows via conda-forge.  The integrated MUMPS wrapper remains in place as a
+fallback if ``python-mumps`` is not available.

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/reference/kwant.builder.rst

@@ -11,7 +11,6 @@ Types
    Builder
    Site
    HoppingKind
-   SimpleSiteFamily
    BuilderLead
    SelfEnergyLead
    ModesLead
@@ -26,3 +25,10 @@ Abstract base classes
    SiteFamily
    Symmetry
    Lead
+
+Functions
+---------
+.. autosummary::
+   :toctree: generated/
+
+   add_peierls_phase

doc/source/reference/kwant.continuum.rst

@@ -11,6 +11,7 @@ Discretizer
     discretize
     discretize_symbolic
     build_discretized
+    discretize_landau
 
 Symbolic helpers
 ----------------
@@ -19,3 +20,11 @@ Symbolic helpers
 
     sympify
     lambdify
+    to_landau_basis
+
+Other
+-----
+.. autosummary::
+    :toctree: generated/
+
+    LandauLattice

doc/source/reference/kwant.rst

@@ -9,21 +9,8 @@ Otherwise, this package has only very limited functionality of its own.
 
 Generic functionality
 ---------------------
-..
-   TODO: Once we depend on Sphinx 1.8, the documentation of __version__ can be
-   put into the "docstring": https://github.com/sphinx-doc/sphinx/issues/344
-
-The version of Kwant is available under the name ``__version__``.
-This string respects `PEP 440 <https://www.python.org/dev/peps/pep-0440/>`_
-and has the following format
-
-- Released version: '1.3.0', '1.3.1', etc.
-- Alpha version: '1.2.0a0', '1.2.0a1', etc.
-- Beta version: '1.1.0b0', '1.1.0b1', etc.
-- Development version (derived from ``git describe --first-parent --dirty``):
-  '1.3.2.dev27+gdecf6893', '1.1.1.dev10+gabcd012.dirty', etc.
-- Development version with incomplete information: 'unknown',
-  'unknown+g0123abc', etc.
+
+.. autodata:: kwant.__version__
 
 .. autosummary::
    :toctree: generated/

doc/source/reference/kwant.solvers.mumps.rst

@@ -3,7 +3,7 @@
 
 .. module:: kwant.solvers.mumps
 
-This solver uses `MUMPS <http://graal.ens-lyon.fr/MUMPS/>`_.  (Only the
+This solver uses `MUMPS <https://graal.ens-lyon.fr/MUMPS/>`_.  (Only the
 sequential, single core version of MUMPS is used.)  MUMPS is a very efficient
 direct sparse solver that can take advantage of memory beyond 3GiB for the
 solution of large problems.  Furthermore, it offers a choice of several

doc/source/tutorial/boilerplate.py

+import matplotlib
+import matplotlib.pyplot
+from matplotlib_inline.backend_inline import set_matplotlib_formats
+
+matplotlib.rcParams['figure.figsize'] = matplotlib.pyplot.figaspect(1) * 2
+set_matplotlib_formats('svg')

doc/source/tutorial/index.rst

@@ -12,4 +12,5 @@ Tutorial: learning Kwant through examples
     plotting
     kpm
     discretize
+    magnetic_field
     faq