Commit 66104ecf authored by Christoph Groth's avatar Christoph Groth
Browse files

add summary to 1.4 whatsnew and rearrange items accordingly

parent 6be2107a
......@@ -5,78 +5,64 @@ 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).
Value functions may no longer take unnamed arguments
----------------------------------------------------
The system parameter (``args`` and ``params``) handling of Kwant has been
rewritten following 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 (as explained in the following section) and faster. For this
reason, value functions may no longer accept ``*args`` or ``**kwargs``.
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:
* `Value functions may no longer take unnamed arguments`_.
* `Value functions may no longer have default values for parameters`_.
.. _whatsnew14-magnetic:
If you are using such functions, we recommend that you replace them by named
parameters.
Value functions may no longer have default values for parameters
----------------------------------------------------------------
Using value functions with default values for parameters can be
problematic, especially when re-using value functions between simulations.
When parameters have default values it is easy to forget that such a
parameter exists at all, because it is not necessary to provide them explicitly
to functions that use the Kwant system. This means that other value functions
might be introduced that also depend on the same parameter,
but in an inconsistent way (e.g. a parameter 'phi' that is a superconducting
phase in one value function, but a peierls phase in another). This leads
to bugs that are confusing and hard to track down.
For this reason value functions may no longer have default values for paramters.
Concretely this means that the following no longer works::
syst = kwant.Builder()
# Parameter 't' has a default value of 1
def onsite(site, V, t=1):
return V = 2 * t
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(site_a, site_b, t=1):
return -t
import numpy as np
import kwant
syst[...] = onsite
syst[...] = hopping
def hopping(a, b, t, peierls):
return -t * peierls(a, b)
# Raises ValueError
syst = make_system(hopping)
lead = make_lead(hopping).substituted(peierls='peierls_lead')
syst.attach_lead(lead)
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))
gauge = kwant.physics.magnetic_gauge(syst)
Note that this allows to override defaults as well as to add additional
parameters.
def B_syst(pos):
return np.exp(-np.sum(pos * pos))
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.
# B_syst in scattering region, 0 in lead.
# Ensure that the fields match at the system/lead interface!
peierls_syst, peierls_lead = gauge(B_syst, 0)
Minimum required versions for some dependencies have increased
--------------------------------------------------------------
Kwant now requires at least the following versions:
params = dict(t=1, peierls=peierls_syst, peierls_lead=peierls_lead)
kwant.hamiltonian_submatrix(syst, params=params)
+ Python 3.5
+ numpy 0.11.0
+ scipy 0.17.0
+ matplotlib 1.5.1
Note that the API for this functionality is provisional, and may be
revised in a future version of Kwant.
These versions (or newer) are available in the latest stable releases
of Ubuntu and Debian GNU/Linux.
.. _whatsnew14-kpm-conductivity:
Conductivity calculations using `kwant.kpm.conductivity`
--------------------------------------------------------
......@@ -90,17 +76,7 @@ potentials at finite temperature::
conductivities = [sigma_xy(mu=mu, temperature=0.1)
for mu in np.linspace(0, 4)]
`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)
.. _whatsnew14-qsymm:
Integration with Qsymm library
------------------------------
......@@ -136,40 +112,7 @@ and vice versa, and for working with continuum Hamiltonians (such as would be us
This integration requires separately installing Qsymm, which is available on the
`Python Package Index <https://pypi.org/project/qsymm/>`_.
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::
import numpy as np
import kwant
def hopping(a, b, t, peierls):
return -t * peierls(a, b)
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)
def B_syst(pos):
return np.exp(-np.sum(pos * pos))
# B_syst in scattering region, 0 in lead.
# Ensure that the fields match at the system/lead interface!
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-parameters:
System parameter substitution
-----------------------------
......@@ -248,27 +191,7 @@ a dictionary using ``params``::
Providing ``args`` will be removed in a future Kwant version.
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.
.. _whatsnew14-density-plots:
Interpolated density plots
--------------------------
......@@ -304,6 +227,115 @@ 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.
Value functions may no longer take unnamed arguments
----------------------------------------------------
The system parameter (``args`` and ``params``) handling of Kwant has been
rewritten following 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 (as explained in the following section) and faster. For this
reason, value functions may no longer accept ``*args`` or ``**kwargs``.
If you are using such functions, we recommend that you replace them by named
parameters.
Value functions may no longer have default values for parameters
----------------------------------------------------------------
Using value functions with default values for parameters can be
problematic, especially when re-using value functions between simulations.
When parameters have default values it is easy to forget that such a
parameter exists at all, because it is not necessary to provide them explicitly
to functions that use the Kwant system. This means that other value functions
might be introduced that also depend on the same parameter,
but in an inconsistent way (e.g. a parameter 'phi' that is a superconducting
phase in one value function, but a peierls phase in another). This leads
to bugs that are confusing and hard to track down.
For this reason value functions may no longer have default values for paramters.
Concretely this means that the following no longer works::
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
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment