doc/source/pre/about.rst

+About Kwant
+===========
+
+.. include:: ../../../README.rst
+   :end-before: See the

doc/source/pre/authors.rst

+.. include:: ../../../AUTHORS.rst

doc/source/pre/citing.rst

+.. include:: ../../../CITING.rst

doc/source/pre/contribute.rst

+.. include:: ../../../CONTRIBUTE.rst

doc/source/pre/index.rst

+Preliminaries
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   about
+   whatsnew/index
+   install
+   authors
+   citing
+   contribute
+   license

doc/source/pre/install.rst

+.. include:: ../../../INSTALL.rst

doc/source/pre/license.rst

+.. include:: ../../../LICENSE.rst

doc/source/pre/whatsnew/0.2.rst

+What's new in Kwant 0.2
+=======================
+
+This article explains the user-visible changes in Kwant 0.2.  Kwant 0.2 was
+released on 29 November 2012.
+
+Improved performance
+--------------------
+This has been the main focus of this release.  Through optimization a level of
+performance has been reached that we consider satisfactory: runs of Kwant for
+mid-sized (100x100 say) systems now typically spend most time in highly
+optimized libraries and not anymore in Python-implemented code.  For large,
+truly performance-critical systems almost all time is now spent in optimized
+libraries.
+
+An important optimization has been replacing NumPy for most uses within Kwant
+by tinyarray.  tinyarray provides a subset of NumPy's functionality in a way
+that is highly optimized for small arrays such as the tags of sites in Kwant.
+
+New MUMPS-based solver
+----------------------
+The code for sparse matrix solvers has been reorganized and a new solver has
+been added next to `kwant.solvers.sparse`: `kwant.solvers.mumps`.  The new
+solver uses the `MUMPS <https://graal.ens-lyon.fr/MUMPS/>`_ software package and
+is much (typically several times) faster than the UMFPACK-based old solver.
+In addition, MUMPS uses considerably less memory for a given system while at
+the same time it is able to take advantage of more than 2 GiB of RAM.
+
+New tutorial dealing with superconductivity
+-------------------------------------------
+:doc:`../../tutorial/superconductors`
+
+New `~kwant.plotter` module
+---------------------------
+`~kwant.plotter` has been rewritten using matplotlib, which allows
+plot post-processing, basic 3D plotting and many other features. Due to the
+possibility to easily modify a matplotlib plot after it has been generated,
+function `~kwant.plotter.plot` has much fewer input parameters, and is less
+flexible than its previous implementation. Its interface is also much more
+similar to that of matplotlib. For the detailed interface and input
+description check `~kwant.plotter.plot` documentation.
+
+The behavior of `~kwant.plotter.plot` with low level systems has changed.
+Arguments of plot which are functions are given site numbers in place of
+`~kwant.builder.Site` objects when plotting a low level system.  This
+provides an easy way to make the appearance of lines and symbols depend on
+computation results.
+
+A new function `~kwant.plotter.map` was implemented. It allows to show a map of
+spatial dependence of a function of a system site (e.g. density of states)
+without showing the sites themselves.
+
+`~kwant.lattice.TranslationalSymmetry` is used differently
+----------------------------------------------------------
+When constructing an instance of `~kwant.lattice.TranslationalSymmetry` a sole
+parameter used to be expected: A sequence of sequences of 1d real space
+vectors.  Now ``TranslationalSymmetry`` can take an arbitrary number of
+parameters, each of them a 1d real space vector.  This reduced the number of
+parantheses necessary in the common case where there is just a single parameter
+
+Example of old usage::
+
+    sym = kwant.TranslationalSymmetry([(-1, 0)])
+
+New usage::
+
+    sym = kwant.TranslationalSymmetry((-1, 0))
+
+Band structure functionality has been moved
+-------------------------------------------
+The functionality that used to be provided by the method ``energies`` of
+`kwant.system.InfiniteSystem` has been moved to the `kwant.physics` package.
+See the documentation of `kwant.physics.Bands` and
+:doc:`../../tutorial/spectrum`.
+
+Calculation of the local density of states
+------------------------------------------
+The new function of sparse solvers `~kwant.solvers.default.ldos`
+allows the calculation of the local density of states.
+
+Calculation of wave functions in the scattering region
+------------------------------------------------------
+(Kwant 0.3 update: ``wave_func`` has been renamed to
+`~kwant.solvers.default.wave_function`.)
+
+The new function of sparse solvers ``wave_func`` allows the calculation of the
+wave function in the scattering region due to any mode of any lead.
+
+Return value of sparse solver
+-----------------------------
+The function `~kwant.solvers.default.solve` of sparse solvers now
+always returns a single instance of ``BlockResult``.  The
+latter has been generalized to include more information for leads defined as
+infinite systems.

doc/source/pre/whatsnew/1.0.rst

+What's new in Kwant 1.0
+=======================
+
+This article explains the new features in Kwant 1.0 compared to Kwant 0.2.
+Kwant 1.0 was released on 9 September 2013.  Please consult the `full list of
+changes in Kwant <https://gitlab.kwant-project.org/kwant/kwant/-/commits/v1.0.5>`_
+for all the changes up to the most recent bugfix release.
+
+
+Lattice and shape improvements
+------------------------------
+Lattices now have a method `~kwant.lattice.Polyatomic.neighbors`,
+which calculates all the n-th shortest possible hoppings on this lattice.  This
+replaces the ``nearest`` attribute that some lattices used to have.
+
+`~kwant.lattice.Polyatomic.shape` uses an improved flood-fill algorithm, making
+it work better on narrow ribbons (which were sometimes buggy before with
+non-square lattices). Additionally, it was made symmetry-aware: If
+`~kwant.lattice.Polyatomic.shape` is used with a lead, the shape does not have
+to be limited along the lead direction anymore.  In fact, if the shape function
+does not have the same symmetry as the lead, the result may be unexpected, so
+it is highly recommended to use shape functions that have the same symmetry as
+the lead.
+
+`~kwant.lattice.Monatomic.closest` now returns an exact, and not approximate
+closest point. A new method `~kwant.lattice.Monatomic.n_closest` was added,
+which returns the n closest lattice points.
+
+``possible_hoppings`` replaced by `~kwant.builder.HoppingKind`
+--------------------------------------------------------------
+The `~kwant.builder.Builder` method ``possible_hoppings`` has been rendered
+obsolete.  Where previously one would have had ::
+
+    for kind in lat.nearest:
+        syst[syst.possible_hoppings(*kind)] = t
+
+now it suffices to write ::
+
+    syst[lat.neighbors()] = t
+
+This is possible because `~kwant.builder.Builder` now accepts *functions* as
+keys in addition to `~kwant.builder.Site` objects and tuples of them
+(hoppings).  These functions are expected to yield either sites or hoppings,
+when given a builder instance as the sole argument. The use of such keys is to
+implement sets of sites or hoppings that depend on what is already present in
+the builder, such as `~kwant.builder.HoppingKind`.  In the above example,
+``lat.neighbors()`` is a list of ``HoppingKind`` objects.
+
+Some renames
+------------
+* site groups are now called site families.  This affects all the names that
+  used to contain "group" or "groups".
+* lead slices are now referred to as lead cells:  This affects all names that
+  used to contain "slice" or "slices" in the context of leads.
+* ``self_energy`` has been renamed to ``selfenergy`` in all cases, most notably
+  in `kwant.physics.selfenergy`.
+* ``wave_func`` has been renamed to `~kwant.solvers.default.wave_function`,
+* ``MonatomicLattice`` has been renamed to `~kwant.lattice.Monatomic`,
+* ``PolyatomicLattice`` has been renamed to `~kwant.lattice.Polyatomic`.
+* ``solve`` was split into two functions: `~kwant.solvers.default.smatrix`, and
+  `~kwant.solvers.default.greens_function`. The former calculates the
+  scattering matrix, the latter the retarded Green's function between the sites
+  adjacent to the leads. It is temporarily not possible to mix self-energy and
+  modes leads within the same system.
+* The object that contained the results, ``BlockResult`` was also split into
+  `~kwant.solvers.common.SMatrix` and `~kwant.solvers.common.GreensFunction`.
+
+Band structure plots
+--------------------
+A convenience function `~kwant.plotter.bands` for quick plotting of band
+structure was implemented.
+
+Immutable site families
+-----------------------
+In order to make naming more consistent, ``kwant.make_lattice`` was renamed and
+can be found now as `kwant.lattice.general`. Classes ``Chain``, ``Square``,
+and ``Honeycomb`` from `~kwant.lattice` were made functions
+`~kwant.lattice.chain`, `~kwant.lattice.square`, and
+`~kwant.lattice.honeycomb`.
+
+In previous versions if one executed ``a = kwant.lattice.square(); b =
+kwant.lattice.square()`` then ``a`` and ``b`` were actually different
+lattices. This often led to confusions in more convoluted use cases, so this
+behavior was changed. Now two site families created with the same parameters
+are actually indistinguishable by Kwant. If it is desired to make two site
+families which have the same geometry, but mean different things, as for
+instance in :doc:`../../tutorial/superconductors`, then the ``name`` argument has to
+be used when creating a lattice, e.g. ``a = kwant.lattice.square(name='a'); b =
+kwant.lattice.square(name='b')``.
+
+Parameters to Hamiltonian
+-------------------------
+Kwant now allows the Hamiltonian matrix elements to be described with functions
+that depend on an arbitrary number of parameters in addition to the sites on
+which they are defined.
+
+Previously, functions defining the Hamiltonian matrix elements had to have the
+following prototypes::
+
+    def onsite(site):
+        ...
+
+    def hopping(site1, site2):
+        ...
+
+If the Hamiltonian elements need to depend on some other external parameters
+(e.g. magnetic field) then those had to be provided by some other means than
+regular function parameters (e.g. global variables).
+
+Now the value functions may accept arbitrary arguments after the `Site`
+arguments.  These extra arguments can be specified when
+`~kwant.solvers.default.smatrix` is called by setting the arguments:
+
+args
+    A tuple of values to be passed as the positional arguments to the
+    Hamiltonian value functions (not including the `Site` arguments).
+
+For example, if the hopping and onsite Hamiltonian value functions have
+the following prototype::
+
+    def onsite(site, t, B, pot):
+        ...
+
+    def hopping(site1, site2, t, B, pot):
+        ...
+
+then the values of ``t``, ``B`` and ``pot`` for which to solve the system can be
+passed to `~kwant.solvers.default.smatrix` like this::
+
+    kwant.smatrix(syst, energy,
+                  args=(2., 3., 4.))
+
+With many parameters it can be less error-prone to collect all of them into a
+single object and pass this object as the single argument.  Such a parameter
+collection could be a dictionary, or a class instance, for example::
+
+    class SimpleNamespace(object):
+        def __init__(self, **kwargs):
+            self.__dict__.update(kwargs)
+    # With Python >= 3.3 we can have instead:
+    # from types import SimpleNamespace
+
+    def onsite(site, p):
+        return p.mu * ...
+
+    def hopping(site1, site2, p):
+        return p.t * exp(-1j * p.B * ...)
+
+    params = SimpleNamespace(t=1, mu=2)
+    for params.B in B_values:
+        kwant.smatrix(syst, energy, args=[params])
+
+Arguments can be passed in an equivalent way to
+`~kwant.solvers.default.wave_function`,
+`~kwant.system.System.hamiltonian_submatrix`, etc.
+
+Calculation of modes separated from solving
+-------------------------------------------
+The interface that solvers expect from leads attached to a
+`~kwant.system.FiniteSystem` has been simplified and codified (see there).
+Similar to self-energy, calculation of modes is now the lead's own
+responsibility.
+
+The new class `~kwant.builder.ModesLead` allows to attach leads that have a
+custom way of calculating their modes (e.g. ideal leads) directly to a
+`~kwant.builder.Builder`.
+
+Modes or self-energies can now be precomputed before passing the system to a
+solver, using the method `~kwant.system.FiniteSystem.precalculate`. This may
+save time, when the linear system has to be solved many times with the same
+lead parameters.
+
+Change of the modes and lead_info format
+----------------------------------------
+The function `~kwant.physics.modes` now returns two objects:
+`~kwant.physics.PropagatingModes` and `~kwant.physics.StabilizedModes`.  The
+first one contains the wave functions of all the propagating modes in real
+space, as well as their velocities and momenta.  All these quantities were
+previously not directly available.  The second object contains the propagating
+and evanescent modes in the compressed format expected by the sparse solver
+(previously this was the sole output of `~kwant.physics.modes`).  Accordingly,
+the ``lead_info`` attribute of `~kwant.solvers.common.SMatrix` contains the
+real space information about the modes in the leads (a list of
+`~kwant.physics.PropagatingModes` objects).
+
+New module for random-access random numbers
+-------------------------------------------
+The module `kwant.digest` provides functions that given some input compute a
+"random" output that depends on the input in a (cryptographically) intractable
+way.  This functionality is useful for introducing disorder, e.g.::
+
+    def onsite(site):
+        return 0.3 * kwant.digest.gauss(repr(site)) + 4
+
+New module for random matrix theory Hamiltonians
+------------------------------------------------
+The module `kwant.rmt` supports the creation of random matrix theory
+Hamiltonians.
+
+Improved plotting functionality
+-------------------------------
+The plotting functionality has been extended. By default, symbols and lines in
+plots are now relative to the system coordinates, i.e. will scale accordingly
+if different zoom-levels are used. Different styles for representing sites and
+hoppings are now possible. 3D plotting has been made more efficient.

doc/source/pre/whatsnew/1.1.rst

+What's new in Kwant 1.1
+=======================
+
+This article explains the user-visible changes in Kwant 1.1.0, released on 21
+October 2015.  See also the `full list of changes up to the most recent bugfix
+release of the 1.1 series
+<https://gitlab.kwant-project.org/kwant/kwant/-/compare/v1.1.0...latest-1.1>`_.
+
+Harmonize `~kwant.physics.Bands` with `~kwant.physics.modes`
+------------------------------------------------------------
+Kwant's convention is that momenta are positive in the direction of
+`~kwant.lattice.TranslationalSymmetry`.  While the momenta returned by
+`~kwant.physics.modes` did respect this convention, the momenta read off the
+band structure as given by `~kwant.physics.Bands` had the wrong sign.  This has
+been fixed now.
+
+New option ``add_cells`` of `~kwant.builder.Builder.attach_lead`
+----------------------------------------------------------------
+Before actually attaching a lead to a builder, the method
+`~kwant.builder.Builder.attach_lead` of `~kwant.builder.Builder` prepares a
+"nice" interface by adding "missing" sites such that the first unit cell of the
+lead is completely connected with the system under construction.  These sites
+and their hoppings are taken over from the lead.
+
+By setting the new option ``add_cells``, ``attach_lead`` can now be told to add
+*in* *addition* any number of complete unit cells of the lead to the system
+before attaching it.  Among other things, this can be useful for
+
+- controlling the hopping between the lead and the system (Leads are always
+  attached with their inter-unit-cell hopping to the system, but absorbing one
+  lead unit cell into the system allows to control this),
+
+- creating a buffer for long range disorder present in the system to die away
+  before the translation-invariant lead begins.
+
+To support these applications, ``attach_lead`` now returns a list of all the
+sites that have been added to the system.  Creating a buffer for disorder can
+be thus done as follows::
+
+    syst[syst.attach_lead(lead, add_cells=10)] = onsite
+
+Note how we set the onsite Hamiltonians of the sites that have been added to
+the value used in the system.
+
+New method ``conductance_matrix``
+---------------------------------
+`~kwant.solvers.common.SMatrix` and `~kwant.solvers.common.GreensFunction`
+have each gained a method ``conductance_matrix`` that returns the matrix
+:math:`G` such that :math:`I = GV` where :math:`I` and :math:`V` are,
+respectively, the vectors of currents and voltages for all the leads.  This
+matrix is useful for calculating non-local resistances. See Section 2.4 of the
+book by S. Datta.
+
+Deduction of transmission probabilities
+---------------------------------------
+If `~kwant.solvers.common.smatrix` or `~kwant.solvers.common.greens_function`
+have been called with ``check_hermicity=True`` (on by default) and a restricted
+number of leads in the ``out_leads`` and ``in_leads`` parameters, calls to
+``transmission`` and ``conductance_matrix`` will work whenever it is possible
+to deduce the result from current conservation.
+
+This allows leaving out one lead (preferably the widest) from ``out_leads``
+and ``in_leads``, and still to calculate all transmission probabilities.
+Doing so has been measured to speed up computations by 20% in some
+cases.
+
+Clearer error messages
+----------------------
+The error messages (exceptions) that appear when the Kwant interface is used incorrectly have been improved in many cases.  For example, if instead of ::
+
+    builder[lattice(0, 1)] = 1
+
+one writes ::
+
+    builder[(0, 1)] = 1
+
+the error message will be more helpful now.
+
+Please continue reporting confusing error messages on the Kwant mailing list.
+
+New option ``pos_transform`` of `kwant.plotter.map`
+----------------------------------------------------------------
+This option which already existed for `kwant.plotter.plot` is now also
+available for `kwant.plotter.map`.

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.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
+each other, i.e. 1.1.3 and 1.2.3 will fix the same bugs.
+
+Starting with Kwant 1.2, all Kwant development will target Python 3.  We plan,
+however, to maintain Python 2 support with the 1.1 series for several years.
+
+
+How to upgrade Kwant scripts to Python 3
+----------------------------------------
+Even though the interface and functionality of Kwant remain unchanged between
+versions 1.1 and 1.2, scripts using Kwant need to be updated to Python 3.
+This can be done by running the `automatic conversion tool
+<https://docs.python.org/3/library/2to3.html>`_ on the command line::
+
+    2to3 -w example.py
+
+(The above command will rename the original file to ``example.py.bak``.)  The
+necessary changes are typically only superficial, as described in `What’s New
+In Python 3.0 <https://docs.python.org/3/whatsnew/3.0.html>`_.

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/index.rst

+What's new in Kwant
+===================
+
+.. toctree::
+    1.5
+    1.4
+    1.3
+    1.2
+    1.1
+    1.0
+    0.2

doc/source/readme.rst

-.. include:: ../../README.txt

doc/source/reference/index.rst

-Reference guide
-===============
+Core modules
+============
 
-In the following, all kwant modules appear in the order of decreasing end-user
-relevance.
+The following modules of Kwant are used directly most frequently.
 
 .. toctree::
    :maxdepth: 1
@@ -12,8 +11,33 @@ relevance.
    kwant.lattice
    kwant.plotter
    kwant.solvers
-   kwant.run
+   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
+===============================
+
+The following modules contain functionality that is most often used only
+internally by Kwant itself or by advanced users.
+
+.. toctree::
+   :maxdepth: 1
+
    kwant.system
    kwant.graph
-   kwant.physics
    kwant.linalg

doc/source/reference/kwant.builder.rst

@@ -10,15 +10,25 @@ Types
 
    Builder
    Site
-   SimpleSiteGroup
+   HoppingKind
    BuilderLead
-   SelfEnergy
+   SelfEnergyLead
+   ModesLead
+   FiniteSystem
+   InfiniteSystem
 
 Abstract base classes
 ---------------------
 .. autosummary::
    :toctree: generated/
 
-   SiteGroup
+   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