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