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:: ../../tutorial/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::
+
+    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: :download:`QAHE example script <../../tutorial/plot_qahe.py>`
+From: :jupyter-download-script:`plot_qahe`
 
 See the tutorial: :doc:`../../tutorial/discretize`
 
@@ -52,8 +84,8 @@ the following::
     psi = kwant.wave_function(syst)(0)[0]
 
     # create the operators
-    Q = kwant.physics.LocalOperator(syst)
-    J = kwant.physics.Current(syst)
+    Q = kwant.operator.Density(syst)
+    J = kwant.operator.Current(syst)
 
     # evaluate the expectation value with the wavefunction
     q = Q(psi)
@@ -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:: ../../tutorial/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))
 
-.. image:: ../../images/plot_qahe_current.*
+        syst = kwant.Builder()
+        syst.fill(model, central_shape, (0, 0))
+        syst.attach_lead(lead)
+        syst.attach_lead(lead.reversed())
 
-From: :download:`QAHE example script <../../tutorial/plot_qahe.py>`
+        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::
+
+    J = kwant.operator.Current(syst).bind(params=params)
+    current = sum(J(p) for p in psi)
+    kwant.plotter.current(syst, current);
+
+From: :jupyter-download-script:`plot_qahe`
 
 Scattering states with discrete symmetries and conservation laws
 ----------------------------------------------------------------
@@ -219,3 +285,10 @@ image in the fundamental domain.
 
 This change is documented here for completeness.  We expect that the vast
 majority of users of Kwant will not be affected by it.
+
+ .. _whatsnew13-params-api-change:
+
+API change that affects low-level systems
+-----------------------------------------
+The `~kwant.system.System.hamiltonian` method of low-level systems must now accept a
+`params` keyword parameter.

doc/source/pre/whatsnew/1.4.rst

+What's new in Kwant 1.4
+=======================
+
+This article explains the user-visible changes in Kwant 1.4.0.  Subsequently,
+the user-visible changes for each maintenance release of the 1.4.x series are
+listed (if there were any).
+
+Summary: release highlights
+---------------------------
+* Adding magnetic field to systems, even in complicated cases, is now specially
+  :ref:`supported <whatsnew14-magnetic>`.
+* The :ref:`KPM module can now calculate conductivities
+  <whatsnew14-kpm-conductivity>`.
+* The `Qsymm library <https://gitlab.kwant-project.org/qt/qsymm>`_ for
+  Hamiltonian symmetry analysis has been :ref:`integrated <whatsnew14-qsymm>`.
+* The handling of system parameters has been :ref:`improved
+  <whatsnew14-parameters>` and optimized.
+* Plotting has been improved, most notably through the addition of a :ref:`routine
+  that plots densities with interpolation <whatsnew14-density-plots>`.
+* :ref:`Installing Kwant on Windows <whatsnew14-windows>` is now much easier
+  thanks to Conda packages.
+
+Backwards-incompatible changes:
+
+* `Restrictions on value functions when named parameters are given`_
+
+.. _whatsnew14-magnetic:
+
+Automatic Peierls phase calculation
+-----------------------------------
+When defining systems with orbital magnetic fields it is often cumbersome to
+manually calculate the phases required by the Peierls substitution, and to
+ensure that the chosen gauge is consistent across the whole system
+(this is especially true for systems with leads that point in different
+directions). This release introduces `kwant.physics.magnetic_gauge`,
+which calculates the Peierls phases for you::
+
+  def hopping(a, b, t, peierls):
+      return -t * peierls(a, b)
+
+  def B_syst(pos):
+     return np.exp(-np.sum(pos * pos))
+
+  syst = make_system(hopping)
+  lead = make_lead(hopping).substituted(peierls='peierls_lead')
+  syst.attach_lead(lead)
+  syst = syst.finalized()
+
+  gauge = kwant.physics.magnetic_gauge(syst)
+
+  # B_syst in scattering region, 0 in lead.
+  peierls_syst, peierls_lead = gauge(B_syst, 0)
+
+  params = dict(t=1, peierls=peierls_syst, peierls_lead=peierls_lead)
+  kwant.hamiltonian_submatrix(syst, params=params)
+
+Note that the API for this functionality is provisional, and may be
+revised in a future version of Kwant.
+
+.. _whatsnew14-kpm-conductivity:
+
+Conductivity calculations using `kwant.kpm.conductivity`
+--------------------------------------------------------
+Kwant now has the ability to calculate conductivities using a combination of
+the Kernel Polynomial Method and the Kubo-Bastin relation.
+The following example calculates :math:`σ_{xy}` for various chemical
+potentials at finite temperature::
+
+  syst = make_system().finalized()
+  sigma_xy = kwant.kpm.conductivity(syst, alpha='x', beta='y')
+  conductivities = [sigma_xy(mu=mu, temperature=0.1)
+                    for mu in np.linspace(0, 4)]
+
+.. _whatsnew14-qsymm:
+
+Integration with Qsymm library
+------------------------------
+Kwant now contains an integration with the Qsymm library for analysing
+model symmetries. This functionality is available under ``kwant.qsymm``.
+Here is an example for extracting the symmetry group of a graphene system::
+
+    import numpy as np
+    import kwant
+    import kwant.qsymm
+
+    s_0 = np.eye(2)
+
+    lat = kwant.lattice.honeycomb(norbs=[1, 1])
+    sym = kwant.TranslationalSymmetry(lat.vec((1, 0)), lat.vec((0, 1)))
+
+    graphene = kwant.Builder(sym)
+    graphene[[lat.a(0, 0), lat.b(0, 0)]] = 0
+    graphene[lat.neighbors()] = 1
+
+    symmetry_generators = kwant.qsymm.find_builder_symmetries(graphene)
+
+    # Let's find what the chiral symmetry looks like
+
+    def is_chiral(g):
+      return g.antisymmetry and not g.conjugate and np.allclose(g.R, s_0)
+
+    print(next(g for g in symmetry_generators if is_chiral(g)))
+
+``kwant.qsymm`` also contains functionality for converting Qsymm models to Kwant Builders,
+and vice versa, and for working with continuum Hamiltonians (such as would be used with
+``kwant.continuum``).
+This integration requires separately installing Qsymm, which is available on the
+`Python Package Index <https://pypi.org/project/qsymm/>`_.
+
+.. _whatsnew14-parameters:
+
+System parameter substitution
+-----------------------------
+After the introduction of ``Builder.fill`` it has become possible to construct
+Kwant systems by first creating a "model" system with high symmetry and then
+filling a lower symmetry system with this model. Often, however, one wants
+to use different parameter values in different parts of a system. In
+previous versions of Kwant this was difficult to achieve.
+
+Builders now have a method ``substituted`` that makes it easy to substitute
+different names for parameters. For example if a builder ``model``
+has a parameter ``V``, and one wishes to have different values for ``V`` in
+the scattering region and leads, one could do the following::
+
+   syst = kwant.Builder()
+   syst.fill(model.substituted(V='V_dot'), ...))
+
+   lead = kwant.Builder()
+   lead.fill(model.substituted(V='V_lead'), ...)
+
+   syst.attach_lead(lead)
+   syst = syst.finalized()
+
+   kwant.smatrix(syst, params=dict(V_dot=0, V_lead=1))
+
+System parameters can now be inspected
+--------------------------------------
+In modern Kwant the preferred way to pass arguments to your models
+is by *name*, using a dictionary and ``params``::
+
+  def onsite(site, magnetic_field, voltage):
+      return magnetic_field * sigma_z + voltage * sigma_0
+
+  def lead_onsite(site, lead_voltage):
+      return lead_voltage * sigma_0
+
+  syst = make_system(onsite)
+  syst.attach_lead(make_lead(lead_onsite))
+  syst = syst.finalized()
+
+  # naming the arguments makes things clear!
+  kwant.smatrix(syst, params=dict(magnetic_field=0.5, voltage=1,
+                                  lead_voltage=0.2))
+
+This is a much clearer and less error prone than passing arguments by
+*position* using ``args``, as was required in older versions of Kwant.
+In this version of Kwant we introduce the ``parameters`` attribute of
+*finalized systems*, which allows inspection of the names of the
+parameters that the system (and its leads) expects::
+
+  >>> syst.parameters
+  frozenset({'magnetic_field', 'voltage'})
+  >>> syst.leads[0].parameters
+  frozenset({'V_lead'})
+
+This is a provisional API that may be changed in a future version of Kwant.
+
+Passing system arguments via ``args`` is deprecated in favor of ``params``
+--------------------------------------------------------------------------
+It is now deprecated to pass arguments to systems by providing the
+``args`` parameter (in ``kwant.smatrix`` and elsewhere). Passing arguments
+via ``args`` is error prone and requires that all value functions take the
+same formal parameters, even if they do not depend on all of them. The
+preferred way of passing parameters to Kwant systems is by passing
+a dictionary using ``params``::
+
+  def onsite(site, magnetic_field, voltage):
+    return magnetic_field * sigma_z + voltage * sigma_0
+
+  syst = make_system(onsite).finalized()
+
+  kwant.smatrix(syst, params=dict(magnetic_field=0.5, voltage=0.2))
+
+  # Compare this to the deprecated 'args'
+  kwant.smatrix(syst, args=(0.5, 0.2))
+
+Providing ``args`` will be removed in a future Kwant version.
+
+.. _whatsnew14-density-plots:
+
+Interpolated density plots
+--------------------------
+A new function, `kwant.plotter.density`, has been added that can be used to
+visualize a density defined over the sites of a Kwant system. This convolves
+the "discrete" density (defined over the system sites) with a "bump" function
+in realspace. The output of `~kwant.plotter.density` can be more informative
+that `~kwant.plotter.map` when plotting systems with many sites, where it is
+not important to see the individual contribution from each site.
+
+Configurable maximum velocity in stream plots
+---------------------------------------------
+The function `~kwant.plotter.streamplot` has got a new option ``vmax``.  Note
+that this option is not available in `~kwant.plotter.current`.  In order to use
+it, one has to call ``streamplot`` directly as shown in the docstring of
+``current``.
+
+Improved heuristic for colorscale limits in `kwant.plotter.map`
+---------------------------------------------------------------
+Previously `~kwant.plotter.map` would set the limits for the color scale
+to the extrema of the data being plotted when ``vmin`` and ``vmax`` were
+not provided. This is the behaviour of ``matplotlib.imshow``. When the data
+to be plotted has very sharp and high peaks this would mean that most of the
+data would appear near the bottom of the color scale, and all of the features
+would be washed out by the presence of the peak. Now `~kwant.plotter.map`
+employs a heuristic for setting the colorscale when there are outliers,
+and will emit a warning when this is detected.
+
+Sites from different families are plotted in different colors by default
+------------------------------------------------------------------------
+Previously `kwant.plotter.plot` would plot all sites in black. Now sites from
+different families are plotted in different colors, which improves the
+default plotting style. You can still customize the site coloring using
+the ``site_color`` parameter, as before.
+
+`kwant.physics.Bands` can optionally return eigenvectors and velocities
+-----------------------------------------------------------------------
+`kwant.physics.Bands` now takes extra parameters that allow it to
+return the mode eigenvectors, and also the derivatives of the dispersion
+relation (up to second order) using the Hellman-Feynman relation::
+
+  syst = make_system().finalized()
+
+  bands = kwant.physics.Bands(syst)
+  (energies, velocities, vectors) = bands(k=0, derivative_order=1,
+                                          return_eigenvectors=True)
+
+Finalized Builders keep track of which sites were added when attaching leads
+----------------------------------------------------------------------------
+When attaching leads to an irregularly shaped scattering region, Kwant adds
+sites in order to make the interface with the leads "smooth". Previously,
+the information of which sites were added was not inspectable after finalization.
+Now the sites that were added from each lead are available in the ``lead_paddings``
+attribute. See the documentation for `~kwant.builder.FiniteSystem` for details.
+
+`kwant.continuum.discretize` can be used with rectangular lattices
+------------------------------------------------------------------
+Previously the discretizer could only be used with lattices with the same
+lattice constant in all directions. Now it is possible to pass rectangular
+lattices to the discretizer::
+
+  kwant.continuum.discretize(
+    'k_x**2 + k_y**2',
+    grid=kwant.lattice.general([(1, 0), (0, 2]),
+  )
+
+This is useful when you need a finer discretization step in some spatial
+directions, and a coarser one in others.
+
+Restrictions on value functions when named parameters are given
+---------------------------------------------------------------
+New restrictions apply to how value functions may accept arguments, when named
+parameters are given through ``params``.  (Nothing changes when the now
+deprcated ``args`` mechanism is used).  The restrictions follow the principle
+that each value function must take a clearly specified set of named parameters.
+This allows to make the parameter handling less error-prone and faster.
+
+In particular, when ``params`` is used, it is no longer possible for value
+functions to
+- take ``*args`` or ``**kwargs``,
+- take keyword-only parameters,
+- have default parameters for arguments.
+
+As an example, the following snippet no longer works because it uses default
+values::
+
+  syst = kwant.Builder()
+
+  # Parameter 't' has a default value of 1
+  def onsite(site, V, t=1):
+    return V = 2 * t
+
+  def hopping(site_a, site_b, t=1):
+    return -t
+
+  syst[...] = onsite
+  syst[...] = hopping
+
+  # Raises ValueError
+  syst = syst.finalized()
+
+As a solution, simply remove the default values and always provide ``t``.
+To deal with many parameters, the following idiom may be useful::
+
+  defaults = dict(a=0, b=1, c=2, d=3)
+  ...
+  smatrix = kwant.smatrix(syst, E, params=dict(defaults, d=4, e=5))
+
+Note that this allows to override defaults as well as to add additional
+parameters.
+
+.. _whatsnew14-windows:
+
+Installation on Microsoft Windows is available via Conda
+--------------------------------------------------------
+Kwant is now packaged for the Conda package manager on Windows, and using
+Conda is the preferred method for installing Kwant on that platform.
+Please refer to the
+`installation section <https://kwant-project.org/install#microsoft-windows>`_
+of the Kwant website for details.
+Currently the MUMPS solver is not available for the Windows version of the
+Conda package; we hope to include MUMPS support in a later patch release.
+
+Minimum required versions for some dependencies have increased
+--------------------------------------------------------------
+Kwant now requires at least the following versions:
+
++ Python 3.5
++ numpy 0.11.0
++ scipy 0.17.0
++ matplotlib 1.5.1
+
+These versions (or newer) are available in the latest stable releases
+of Ubuntu and Debian GNU/Linux.
+
+Changes in Kwant 1.4.1
+----------------------
+- The list of user-visible changes was rearranged to emphasize
+  backwards-incompatible changes by moving them to the top of the list.
+- Restrictions on value functions no longer apply when the old ``args``
+  mechanism is used, this restores most of the backwards compatibility with
+  previous Kwant versions: `Restrictions on value functions when named
+  parameters are given`_.
+- The ``args`` parameter passing mechanism works again with
+  `~kwant.wraparound`-treated systems.  Some restriction continue to appply,
+  notably it is not possible to use ``wraparound`` with value functions that
+  take ``*args`` or ``*kwargs``.
+- Kwant no longer requires the existence of a `parameters` attribute for
+  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,8 @@ What's new in Kwant
 ===================
 
 .. toctree::
+    1.5
+    1.4
     1.3
     1.2
     1.1

doc/source/reference/index.rst

@@ -27,6 +27,7 @@ The following modules provide functionality for special applications.
    kwant.kpm
    kwant.continuum
    kwant.wraparound
+   kwant.qsymm
 
 Modules mainly for internal use
 ===============================

doc/source/reference/kwant.builder.rst

@@ -11,10 +11,11 @@ Types
    Builder
    Site
    HoppingKind
-   SimpleSiteFamily
    BuilderLead
    SelfEnergyLead
    ModesLead
+   FiniteSystem
+   InfiniteSystem
 
 Abstract base classes
 ---------------------
@@ -24,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.graph.rst

@@ -76,17 +76,6 @@ Graph types
    Graph
    CGraph
 
-Graph algorithms
-----------------
-.. autosummary::
-   :toctree: generated/
-
-   slice
-   make_undirected
-   remove_duplicates
-   induced_subgraph
-   print_graph
-
 Other
 -----
 +----------------+------------------------------------------+

doc/source/reference/kwant.kpm.rst

@@ -4,4 +4,4 @@
 .. automodule:: kwant.kpm
    :members:
    :special-members:
-   :exclude-members: __weakref__
+   :exclude-members: __weakref__, __init__

doc/source/reference/kwant.physics.rst

@@ -21,3 +21,12 @@ Symmetry
    :toctree: generated/
 
    DiscreteSymmetry
+
+Computation of magnetic field gauge
+-----------------------------------
+
+.. autosummary::
+   :toctree: generated/
+   :template: autosummary/functor.rst
+
+   magnetic_gauge

doc/source/reference/kwant.plotter.rst

@@ -11,10 +11,12 @@ Plotting routines
 
    plot
    map
+   density
    current
    bands
    spectrum
    streamplot
+   scalarplot
 
 Helper functions
 ----------------
@@ -22,6 +24,7 @@ Helper functions
    :toctree: generated/
 
    interpolate_current
+   interpolate_density
    sys_leads_sites
    sys_leads_hoppings
    sys_leads_pos

doc/source/reference/kwant.qsymm.rst

+:mod:`kwant.qsymm` -- Integration with `Qsymm <https://gitlab.kwant-project.org/qt/qsymm>`_
+===========================================================================================
+
+.. automodule:: kwant.qsymm
+   :members:
+   :special-members:
+   :exclude-members: __weakref__

doc/source/reference/kwant.rst

@@ -9,7 +9,8 @@ Otherwise, this package has only very limited functionality of its own.
 
 Generic functionality
 ---------------------
-The version of Kwant is available under the name ``__version__``.
+
+.. 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/reference/kwant.system.rst

@@ -14,6 +14,11 @@ Any system which is provided to a solver should be derived from the appropriate
 class in this module, and every solver can assume that its input corresponds to
 the interface defined here.
 
+In practice, very often Kwant systems are finalized
+`builders <kwant.builder.Builder>` (i.e.
+`kwant.builder.FiniteSystem` or `kwant.builder.InfiniteSystem`) and offer some
+additional attributes.
+
 .. autosummary::
    :toctree: generated/
 

doc/source/tutorial/README

-Note for Kwant developers
--------------------------
-
-Say you have modified SCRIPT.py in this directory.  Make sure that the tutorial
-image generation patches still apply by deleting doc/source/images/SCRIPT.py
-and running ``make doc/source/images/SCRIPT.py`` in doc.  Now examine the newly
-created doc/source/images/SCRIPT.py.  If you do not like the result or the
-patch did not apply, edit doc/source/images/SCRIPT.py until you like it.  You
-can run `make html` during your edits to check things.  Finally, even if you
-did not edit the script, execute generate-diffs.sh in doc/source/images.  If
-the patches applied cleanly the diff files will usually stay unchanged.

doc/source/tutorial/ab_ring.py

-# 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
-
-
-#HIDDEN_BEGIN_eusz
-def make_system(a=1, t=1.0, W=10, r1=10, r2=20):
-    # 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)
-#HIDDEN_END_eusz
-
-    # and add the corresponding lattice points using the `shape`-function
-#HIDDEN_BEGIN_lcak
-    syst[lat.shape(ring, (0, r1 + 1))] = 4 * t
-    syst[lat.neighbors()] = -t
-#HIDDEN_END_lcak
-
-    # 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.
-#HIDDEN_BEGIN_lvkt
-    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
-#HIDDEN_END_lvkt
-
-    #### Define the leads. ####
-    # left lead
-#HIDDEN_BEGIN_qwgr
-    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
-#HIDDEN_END_qwgr
-
-    #### Attach the leads and return the system. ####
-#HIDDEN_BEGIN_skbz
-    syst.attach_lead(lead)
-    syst.attach_lead(lead.reversed())
-#HIDDEN_END_skbz
-
-    return syst
-
-
-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, args=[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()
-
-
-def main():
-    syst = make_system()
-
-    # Check that the system looks as intended.
-    kwant.plot(syst)
-
-    # Finalize the system.
-    syst = syst.finalized()
-
-    # We should see a conductance that is periodic with the flux quantum
-    plot_conductance(syst, energy=0.15, fluxes=[0.01 * i * 3 * 2 * pi
-                                                for i in range(100)])
-
-
-# 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()

doc/source/tutorial/band_structure.py

-# 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
-
-#HIDDEN_BEGIN_zxip
-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
-#HIDDEN_END_zxip
-
-
-#HIDDEN_BEGIN_pejz
-def main():
-    lead = make_lead().finalized()
-    kwant.plotter.bands(lead, show=False)
-    pyplot.xlabel("momentum [(lattice constant)^-1]")
-    pyplot.ylabel("energy [t]")
-    pyplot.show()
-#HIDDEN_END_pejz
-
-
-# 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()

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/closed_system.py

-# 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
-import kwant
-
-# For eigenvalue computation
-#HIDDEN_BEGIN_tibv
-import scipy.sparse.linalg as sla
-#HIDDEN_END_tibv
-
-# For plotting
-from matplotlib import pyplot
-
-
-def make_system(a=1, t=1.0, r=10):
-    # Start with an empty tight-binding system and a single square lattice.
-    # `a` is the lattice constant (by default set to 1 for simplicity).
-
-#HIDDEN_BEGIN_qlyd
-    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=0):
-        # 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
-#HIDDEN_END_qlyd
-
-
-#HIDDEN_BEGIN_yvri
-def plot_spectrum(syst, Bfields):
-
-    # In the following, we compute the spectrum of the quantum dot
-    # using dense matrix methods. This works in this toy example, as
-    # the system is tiny. In a real example, one would want to use
-    # sparse matrix methods
-
-    energies = []
-    for B in Bfields:
-        # Obtain the Hamiltonian as a dense matrix
-        ham_mat = syst.hamiltonian_submatrix(args=[B], sparse=True)
-
-        # we only calculate the 15 lowest eigenvalues
-        ev = sla.eigsh(ham_mat, k=15, which='SM', return_eigenvectors=False)
-
-        energies.append(ev)
-
-    pyplot.figure()
-    pyplot.plot(Bfields, energies)
-    pyplot.xlabel("magnetic field [arbitrary units]")
-    pyplot.ylabel("energy [t]")
-    pyplot.show()
-#HIDDEN_END_yvri
-
-
-#HIDDEN_BEGIN_wave
-def plot_wave_function(syst):
-    # Calculate the wave functions in the system.
-    ham_mat = syst.hamiltonian_submatrix(sparse=True)
-    evecs = sla.eigsh(ham_mat, k=20, which='SM')[1]
-
-    # Plot the probability density of the 10th eigenmode.
-    kwant.plotter.map(syst, np.abs(evecs[:, 9])**2,
-                      colorbar=False, oversampling=1)
-#HIDDEN_END_wave
-
-
-#HIDDEN_BEGIN_current
-def plot_current(syst):
-    # Calculate the wave functions in the system.
-    ham_mat = syst.hamiltonian_submatrix(sparse=True)
-    evecs = sla.eigsh(ham_mat, k=20, which='SM')[1]
-
-    # Calculate and plot the local current of the 10th eigenmode.
-    J = kwant.operator.Current(syst)
-    current = J(evecs[:, 9])
-    kwant.plotter.current(syst, current, colorbar=False)
-#HIDDEN_END_current
-
-
-def main():
-    syst = make_system()
-
-    # Check that the system looks as intended.
-    kwant.plot(syst)
-
-    # Finalize the system.
-    syst = syst.finalized()
-
-    # The following try-clause can be removed once SciPy 0.9 becomes uncommon.
-    try:
-        # 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)])
-
-        # 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)
-        plot_current(syst)
-    except ValueError as e:
-        if e.message == "Input matrix is not real-valued.":
-            print("The calculation of eigenvalues failed because of a bug in SciPy 0.9.")
-            print("Please upgrade to a newer version of SciPy.")
-        else:
-            raise
-
-
-# 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()