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.
