From a260454428a3a1d3bba940542e6143f1bbb6b8ab Mon Sep 17 00:00:00 2001
From: Joseph Weston <joseph.weston@cea.fr>
Date: Thu, 5 Mar 2015 12:46:22 +0100
Subject: [PATCH] add explicit documentation on lead numbering
It was not previously made explicit anywhere in the docs on how
the leads were numbered. This commit adds a line to the docstring
of `kwant.builder.Builder.attach_lead` which explains the meaning
of the return value. It also adds a few lines to the first tutorial
explaining the numbering.
---
doc/source/tutorial/tutorial1.rst | 9 ++++++---
kwant/builder.py | 5 +++++
2 files changed, 11 insertions(+), 3 deletions(-)
diff --git a/doc/source/tutorial/tutorial1.rst b/doc/source/tutorial/tutorial1.rst
index 3b7cfa02..872a8170 100644
--- a/doc/source/tutorial/tutorial1.rst
+++ b/doc/source/tutorial/tutorial1.rst
@@ -165,8 +165,9 @@ isolated, infinite is attached at the correct position using
:start-after: #HIDDEN_BEGIN_fskr
:end-before: #HIDDEN_END_fskr
-More details about attaching leads can be found in the tutorial
-:ref:`tutorial-abring`.
+This call returns the lead number which will be used to refer to the lead when
+computing transmissions (further down in this tutorial). More details about
+attaching leads can be found in the tutorial :ref:`tutorial-abring`.
We also want to add a lead on the right side. The only difference to
the left lead is that the vector of the translational
@@ -216,7 +217,9 @@ We use ``kwant.smatrix`` which is a short name for
`kwant.solvers.default`. ``kwant.smatrix`` computes the scattering matrix
``smatrix`` solving a sparse linear system. ``smatrix`` itself allows to
directly compute the total transmission probability from lead 0 to lead 1 as
-``smatrix.transmission(1, 0)``.
+``smatrix.transmission(1, 0)``. The numbering used to refer to the leads here
+is the same as the numbering assigned by the call to
+`kwant.builder.Builder.attach_lead` earlier in the tutorial.
Finally we can use `matplotlib` to make a plot of the computed data
(although writing to file and using an external viewer such as
diff --git a/kwant/builder.py b/kwant/builder.py
index ca20a63a..320613af 100644
--- a/kwant/builder.py
+++ b/kwant/builder.py
@@ -964,6 +964,8 @@ class Builder(object):
def attach_lead(self, lead_builder, origin=None):
"""Attach a lead to the builder, possibly adding missing sites.
+ Returns the lead number (integer) of the attached lead.
+
Parameters
----------
lead_builder : `Builder` with 1D translational symmetry
@@ -984,6 +986,9 @@ class Builder(object):
-----
This method is not fool-proof, i.e. if it returns an error, there is
no guarantee that the system stayed unaltered.
+
+ The lead numbering starts from zero and increments from there, i.e.
+ the leads are numbered in the order in which they are attached.
"""
sym = lead_builder.symmetry
H = lead_builder.H
--
GitLab