doc/source/pre/whatsnew/1.2.rst

 What's new in Kwant 1.2
 =======================
 
-This article explains the user-visible changes in Kwant 1.2, released on 9
-December 2015.  Please consult the `full list of changes in Kwant
-<https://gitlab.kwant-project.org/kwant/kwant/compare/v1.2.2...stable>`_ for
-all the changes up to the most recent bugfix release.
+This article explains the user-visible changes in Kwant 1.2.2, released on 9
+December 2015.  See also the `full list of changes up to the most recent bugfix
+release of the 1.2 series
+<https://gitlab.kwant-project.org/kwant/kwant/-/compare/v1.2.2...latest-1.2>`_.
 
 Kwant 1.2 is identical to Kwant 1.1 except that it has been updated to run on
 Python 3.4 and above.  Bugfix releases for the 1.1 and 1.2 series will mirror

doc/source/pre/whatsnew/1.3.rst

+What's new in Kwant 1.3
+=======================
+
+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>`_.
+
+Using high-symmetry builders as models
+--------------------------------------
+Builders now have a `~kwant.builder.Builder.fill` method that fills a builder
+instance with copies of a template builder. This can be used to "cut out"
+shapes from high-symmetry models, or to increase the symmetry period of a lead.
+
+Thus Kwant gains the new concept of a "model".  Models may be created manually,
+or with the new function `kwant.continuum.discretize` (see next paragraph).
+There is also support for finalizing models and e.g. calculating their band
+structure (see `Finalizing builders with multiple translational symmetries`_).
+
+Tools for continuum Hamiltonians
+--------------------------------
+The new sub-package `~kwant.continuum` is a collection of tools for working
+with continuum models and for discretizing them into tight-binding models. It
+aims at providing a handy interface to convert symbolic Hamiltonians into a
+builder with N-D translational symmetry that can be use to calculate
+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:
+
+.. 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: :jupyter-download-script:`plot_qahe`
+
+See the tutorial: :doc:`../../tutorial/discretize`
+
+See the reference documentation: :doc:`../../reference/kwant.continuum`
+
+Calculating charges and currents using the operator module
+----------------------------------------------------------
+Often one may wish to calculate quantities that are defined over sites of
+the system (such as charge density, spin density along some axis etc),
+or over hoppings of the system (such as current or spin current). With
+the introduction of the ``operator`` module it has now become much easier
+to calculate such quantities. To obtain the regular density and current
+everywhere in a system due to a wavefunction ``psi``, one only needs to do
+the following::
+
+    syst = make_system().finalized()
+    psi = kwant.wave_function(syst)(0)[0]
+
+    # create the operators
+    Q = kwant.operator.Density(syst)
+    J = kwant.operator.Current(syst)
+
+    # evaluate the expectation value with the wavefunction
+    q = Q(psi)
+    j = J(psi)
+
+See the tutorial: :doc:`../../tutorial/operators`
+
+Plotting of currents
+--------------------
+Quantities defined on system hoppings (e.g. currents calculated using
+`~kwant.operator.Current`) can be directly plotted as a streamplot over the
+system using `kwant.plotter.current`. This is similar to how
+`kwant.plotter.map` can be used to plot quantities defined on sites.
+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>`_:
+
+.. 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::
+
+    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
+----------------------------------------------------------------
+Given a lead Hamiltonian that has a conservation law, it is now possible to
+construct lead modes that have definite values of the conservation law. This
+is done by declaring projectors that block diagonalize the Hamiltonian before
+the modes are computed. For a Hamiltonian that has one or more of the three
+fundamental discrete symmetries (time-reversal symmetry, particle-hole symmetry
+and chiral symmetry), it is now possible to declare the symmetries in Kwant.
+The symmetries are then used to construct scattering states that are properly
+related by symmetry. The discrete symmetries may be combined with conservation
+laws, such that if different blocks of the Hamiltonian are related by a discrete
+symmetry, the lead modes are computed to reflect this.
+
+See the updated tutorial: :doc:`../../tutorial/superconductors`
+
+Named parameters for value functions
+------------------------------------
+In Kwant < 1.3 whenever Hamiltonian values were provided as functions,
+they all had to take the same extra parameters (after the site(s))
+regardless of whether or not they actually used them at all. For example,
+if we had some onsite potential and a magnetic field that we
+model using the Peierls substitution, we would have to define our value
+functions like so::
+
+    # formally depends on 'B', but 'B' is never used
+    def onsite(site, V, B):
+        return V
+
+    # formally depends on 'V', but 'V' is never used
+    def hopping(site_a, site_b, V, B):
+        return (site_b.pos[1] - site_a.pos[1]) * B
+
+This was because previously extra arguments were provided to the system
+by passing them as a sequence via the ``args`` parameter to various Kwant
+functions (e.g. ``kwant.smatrix`` or ``hamiltonian_submatrix``).
+
+In Kwant 1.3 it is now possible for value functions to depend on different
+parameters, e.g.::
+
+    def onsite(site, V):
+        return V
+
+    def hopping(site_a, site_b, B):
+        return (site_b.pos[1] - site_a.pos[1]) * B
+
+If you make use of this feature then you must in addition pass your arguments
+via the ``params`` parameter. The value provided to ``params`` must
+be a ``dict`` that maps parameter names to values, e.g.::
+
+    kwant.smatrix(syst, params=dict(B=0.1, V=2))
+
+as opposed to the old way::
+
+    kwant.smatrix(syst, args=(2, 0.1))
+
+Passing a dictionary of parameters via ``params`` is now the recommended way
+to provide parameters to the system.
+
+Reference implementation of the kernel polynomial method
+--------------------------------------------------------
+The kernel polynomial method is now implemented within Kwant to obtain the
+density of states or, more generally, the spectral density of a given operator
+acting on a system or Hamiltonian.
+
+See the tutorial: :doc:`../../tutorial/kpm`
+
+See the reference documentation: :doc:`../../reference/kwant.kpm`
+
+Finalizing builders with multiple translational symmetries
+----------------------------------------------------------
+While it remains impossible to finalize a builder with more than a single
+direction of translational symmetry, the ``wraparound`` module has been added
+as a temporary work-around until the above limitation gets lifted.
+
+The function `~kwant.wraparound.wraparound` transforms all (or all but one)
+translational symmetries of a given builder into named momentum parameters
+`k_x`, `k_y`, etc.  This makes it easy to compute transport through systems
+with periodic boundary conditions or across infinite planes.
+
+Plotting the 2-d band structure of graphene is now as straightforward as::
+
+    from matplotlib import pyplot
+    import kwant
+
+    lat = kwant.lattice.honeycomb()
+    sym = kwant.TranslationalSymmetry(lat.vec((1, 0)), lat.vec((0, 1)))
+
+    bulk = kwant.Builder(sym)
+    bulk[ [lat.a(0, 0), lat.b(0, 0)] ] = 0
+    bulk[lat.neighbors()] = 1
+    wrapped = kwant.wraparound.wraparound(bulk).finalized()
+    kwant.wraparound.plot_2d_bands(wrapped)
+
+Consistent ordering of sites in finalized builders
+--------------------------------------------------
+In Python 3 the internal ordering of dictionaries is not deterministic. This
+meant that running a Kwant script twice would produce systems with different
+ordering of sites, which leads to non-reproducible calculations. Now, sites
+in finalized builders are always ordered first by their site family, then by
+their tag.
+
+Coincidentally, this means that you can plot a wavefunction in a simple 1D
+system by just saying::
+
+    lattice_1D = chain()
+    syst = make_system(lattice_1D)
+    h = syst.hamiltonian_submatrix()
+    pyplot.plot(np.eigs(h)[1][0])
+
+attach_lead() can now handle leads with greater than nearest-neighbor hoppings
+------------------------------------------------------------------------------
+When attaching a lead with greater than nearest-neighbor hoppings, the symmetry
+period of the finalized lead is suitably extended and the unit cell size is
+increased.
+
+Pickling support
+----------------
+It is now possible to pickle and unpickle `~kwant.builder.Builder` and
+`~kwant.system.System` instances.
+
+Improved build configuration
+----------------------------
+The name of the build configuration file, ``build.conf`` by default, is now
+configurable with the ``--configfile=PATH`` option to ``setup.py``.  (This
+makes build configuration usable with the ``pip`` tool.)  The build
+configuration as specified in this file is now more general, allowing to
+modify any build parameter for any of the compiled extensions contained in
+Kwant.  See the :ref:`Installation instructions <build-configuration>` for
+details.
+
+Builder.neighbors() respects symmetries
+---------------------------------------
+Given a site, the method `~kwant.builder.Builder.neighbors` of
+`~kwant.builder.Builder` returns an iterator over sites that are connected by a
+hopping to the provided site.  This is in contrast to previous versions of
+Kwant, where the neighbors were yielded not of the provided site, but of it's
+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,9 @@ What's new in Kwant
 ===================
 
 .. toctree::
+    1.5
+    1.4
+    1.3
     1.2
     1.1
     1.0

doc/source/reference/index.rst

@@ -11,8 +11,24 @@ The following modules of Kwant are used directly most frequently.
    kwant.lattice
    kwant.plotter
    kwant.solvers
+   kwant.operator
    kwant.physics
 
+Other modules
+=============
+
+The following modules provide functionality for special applications.
+
+.. toctree::
+   :maxdepth: 1
+
+   kwant.digest
+   kwant.rmt
+   kwant.kpm
+   kwant.continuum
+   kwant.wraparound
+   kwant.qsymm
+
 Modules mainly for internal use
 ===============================
 
@@ -25,14 +41,3 @@ internally by Kwant itself or by advanced users.
    kwant.system
    kwant.graph
    kwant.linalg
-
-Miscellaneous modules
-=====================
-
-The following modules provide functionality for special applications.
-
-.. toctree::
-   :maxdepth: 1
-
-   kwant.digest
-   kwant.rmt

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

+:mod:`kwant.continuum` -- Tools for continuum systems
+=====================================================
+
+.. module:: kwant.continuum
+
+Discretizer
+-----------
+.. autosummary::
+    :toctree: generated/
+
+    discretize
+    discretize_symbolic
+    build_discretized
+    discretize_landau
+
+Symbolic helpers
+----------------
+.. autosummary::
+    :toctree: generated/
+
+    sympify
+    lambdify
+    to_landau_basis
+
+Other
+-----
+.. autosummary::
+    :toctree: generated/
+
+    LandauLattice

doc/source/reference/kwant.graph.rst

@@ -76,19 +76,8 @@ Graph types
    Graph
    CGraph
 
-Graph algorithms
-----------------
-.. autosummary::
-   :toctree: generated/
-
-   slice
-   make_undirected
-   remove_duplicates
-   induced_subgraph
-   print_graph
-
 Other
 -----
-+--------------+------------------------------------------+
-| `gint_dtype` | Data type used for graph nodes and edges |
-+--------------+------------------------------------------+
++----------------+------------------------------------------+
+| ``gint_dtype`` | Data type used for graph nodes and edges |
++----------------+------------------------------------------+

doc/source/reference/kwant.kpm.rst

+:mod:`kwant.kpm` -- Kernel Polynomial Method
+============================================
+
+.. automodule:: kwant.kpm
+   :members:
+   :special-members:
+   :exclude-members: __weakref__, __init__

doc/source/reference/kwant.lattice.rst

@@ -20,6 +20,7 @@ Library of lattices
 
    chain
    square
+   cubic
    triangular
    honeycomb
    kagome

doc/source/reference/kwant.operator.rst

+:mod:`kwant.operator` -- Operators and Observables
+==================================================
+
+.. module:: kwant.operator
+
+Observables
+-----------
+.. autosummary::
+   :toctree: generated/
+   :template: autosummary/functor.rst
+
+   Density
+   Current
+   Source

doc/source/reference/kwant.physics.rst

@@ -14,3 +14,19 @@ Leads
    two_terminal_shotnoise
    PropagatingModes
    StabilizedModes
+
+Symmetry
+--------
+.. autosummary::
+   :toctree: generated/
+
+   DiscreteSymmetry
+
+Computation of magnetic field gauge
+-----------------------------------
+
+.. autosummary::
+   :toctree: generated/
+   :template: autosummary/functor.rst
+
+   magnetic_gauge

doc/source/reference/kwant.plotter.rst

@@ -4,20 +4,27 @@
 .. module:: kwant.plotter
 
 
-Plotting routine
-----------------
+Plotting routines
+-----------------
 .. autosummary::
    :toctree: generated/
 
    plot
    map
+   density
+   current
    bands
+   spectrum
+   streamplot
+   scalarplot
 
-Data-generating functions
--------------------------
+Helper functions
+----------------
 .. autosummary::
    :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.solvers.sparse.rst

@@ -4,7 +4,7 @@
 .. module:: kwant.solvers.sparse
 
 This solver uses SciPy's `scipy.sparse.linalg
-<http://docs.scipy.org/doc/scipy/reference/sparse.linalg.html>`_.  The
+<https://docs.scipy.org/doc/scipy/reference/sparse.linalg.html>`_.  The
 interface is identical to that of the :mod:`default solver
 <kwant.solvers.default>`.
 

doc/source/reference/kwant.system.rst

 :mod:`kwant.system` -- Low-level interface of systems
 *****************************************************
 
-.. currentmodule:: kwant.system
+.. automodule:: kwant.system
 
 This module is the binding link between constructing tight-binding systems and
 doing calculations with these systems.  It defines the interface which any
@@ -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/reference/kwant.wraparound.rst

+:mod:`kwant.wraparound` -- Wrapping around translational symmetries
+===================================================================
+.. module:: kwant.wraparound
+.. autosummary::
+   :toctree: generated/
+
+   wraparound
+   plot_2d_bands