From 7842e412208c472290cce8cd9b2b88c278d8b4db Mon Sep 17 00:00:00 2001
From: Joseph Weston <joseph.weston08@gmail.com>
Date: Mon, 4 Dec 2017 13:29:56 +0100
Subject: [PATCH] clarify link between mode velocity and symmetry direction
Previously the fact that the positive direction of mode
velocity is determined by the translational symmetry vector
of the system was not made clear in the relevant docstrings.
Closes #143.
---
doc/source/tutorial/faq.rst | 7 ++++++-
kwant/physics/leads.py | 3 +++
kwant/solvers/common.py | 18 ++++++++++++++----
3 files changed, 23 insertions(+), 5 deletions(-)
diff --git a/doc/source/tutorial/faq.rst b/doc/source/tutorial/faq.rst
index 3833f474..1022bf03 100644
--- a/doc/source/tutorial/faq.rst
+++ b/doc/source/tutorial/faq.rst
@@ -434,7 +434,12 @@ Scattering states calculated using `~kwant.solvers.default.wave_function` are re
same order as the "incoming" modes of `~kwant.system.InfiniteSystem.modes`.
Kwant considers that the translational symmetry of a lead points "towards
infinity" (*not* towards the system) which means that the incoming modes are
-those that have *negative* velocities:
+those that have *negative* velocities.
+
+This means that for a lead attached on the left of a scattering region (with
+symmetry vector $(-1, 0)$, for example), the
+positive $k$ direction (when inspecting the lead's band structure) actually
+corresponds to the *negative* $x$ direction.
How does Kwant order components of an individual wavefunction?
diff --git a/kwant/physics/leads.py b/kwant/physics/leads.py
index 61883c43..222ad0eb 100644
--- a/kwant/physics/leads.py
+++ b/kwant/physics/leads.py
@@ -135,6 +135,9 @@ class PropagatingModes:
velocity, `k` is momentum and `conserved_quantity` is the conservation
law eigenvalue.
+ In the above, the positive velocity and momentum directions are defined
+ with respect to the translational symmetry direction of the system.
+
The first dimension of `wave_functions` corresponds to the orbitals of all
the sites in a unit cell, the second one to the number of the mode. Each
mode is normalized to carry unit current. If several modes have the same
diff --git a/kwant/solvers/common.py b/kwant/solvers/common.py
index f5f6197e..fbe88b69 100644
--- a/kwant/solvers/common.py
+++ b/kwant/solvers/common.py
@@ -570,13 +570,23 @@ class SparseSolver(metaclass=abc.ABCMeta):
Notes
-----
-
The returned object can be itself called like a function. Given a lead
number, it returns a 2d NumPy array that contains the wave function
within the scattering region due to each incoming mode of the given
- lead. Index 0 is the mode number, index 1 is the orbital number. The
- modes appear in the same order as incoming modes in
- `kwant.physics.modes`.
+ lead. Index 0 is the mode number, index 1 is the orbital number.
+
+ The modes appear in the same order as the negative velocity modes in
+ `kwant.physics.PropagatingModes`. In Kwant's convention leads are attached
+ so that their translational symmetry points *away* from the scattering
+ region::
+
+ left lead SR right lead
+ /---------\ /---\ /---------\
+ ...-3-2-1-0-X-X-X-0-1-2-3-...
+
+ This means that incoming modes (coming from infinity towards the
+ scattering region) have *negative* velocity with respect to the
+ lead's symmetry direction.
Examples
--------
--
GitLab