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.
