What’s new in Kwant 1.4

This article explains the user-visible changes in Kwant 1.4.0. See also the full list of changes up to the most recent bugfix release of the 1.4 series.

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

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 \(σ_{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)]

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,

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.

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:

import numpy as np
import kwant

def hopping(a, b, t, peierls):
    return -t * peierls(a, b)

syst = make_system(hopping)
lead = make_lead(hopping).substituted(peierls='peierls_lead')
syst = syst.finalized()

gauge = kwant.physics.magnetic_gauge(syst)

def B_syst(pos):
   return np.exp(-np.sum(pos * pos))

# B_syst in scattering region, 0 in lead.
# Ensure that the fields match at the system/lead interface!
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.

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 = syst.finalized()

kwant.smatrix(syst, params=dict(V_dot=0, V_lead=1))

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 density can be more informative that map when plotting systems with many sites, where it is not important to see the individual contribution from each site.

Value functions may no longer have default values for parameters

Using value functions with default values for parameters can be problematic, especially when re-using value functions between simulations. When parameters have default values it is easy to forget that such a parameter exists at all, because it is not necessary to provide them explicitly to functions that use the Kwant system. This means that other value functions might be introduced that also depend on the same parameter, but in an inconsistent way (e.g. a parameter ‘phi’ that is a superconducting phase in one value function, but a peierls phase in another). This leads to bugs that are confusing and hard to track down.

For this reason value functions may no longer have default values for paramters. Concretely this means that the following no longer works:

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.

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 = syst.finalized()

# naming the arguments makes things clear!
kwant.smatrix(syst, params=dict(magnetic_field=0.5, voltage=1,

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

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.

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 FiniteSystem for details.

Configurable maximum velocity in stream plots

The function streamplot has got a new option vmax. Note that this option is not available in current. In order to use it, one has to call streamplot directly as shown in the docstring of current.

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:

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

Improved heuristic for colorscale limits in kwant.plotter.map

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