tweak workflow script, brag more in index :)

content/index.txt

@@ -24,11 +24,11 @@ summarized as follows:
     :width: 90%
 
 Kwant was designed to be easy to use: for example the program that generates
-the right panel of the image above is only 42 lines long. Kwant is also
-accessible for people without expertise in numerics. To aid that, it is
-provided along with a detailed hand-on `tutorial </doc/1.0/tutorial/>`_ and the
-Kwant `paper </paper>`_, which describes the guiding principles underlying its
-design.
+the right panel of the image above is only 42 lines long (including detailed
+comments). Kwant is also accessible for people without expertise in
+numerics. To aid that, it is provided along with a detailed hand-on `tutorial
+</doc/1.0/tutorial/>`_ and the Kwant `paper </paper>`_, which describes the
+guiding principles underlying its design.
 
 Examples of the use of Kwant
 ----------------------------

content/kwant_workflow.py

@@ -3,40 +3,40 @@ import matplotlib.pyplot as pyplot
 from scipy import misc
 import numpy as np
 
-# shape.png is an image containing the system shape colored in black.
+# shape.png is an image containing the system shape colored in black.  Here we
+# read the image from this file, create an empty scattering region, and add to
+# it the sites with coordinates of pixels that we encounter in the image.
 im = misc.imread('shape.png')[:, :, 0]
-w, h = im.T.shape
-
 sys = kwant.Builder()
 lat = kwant.lattice.square()
-
 for pos in np.argwhere(im != 255):
     sys[lat(pos[1], -pos[0])] = 4
 
-def make_wire_shape(period, center, r, ymin, ymax):
+def wire_shape(period, center, r, ymin, ymax):
+    """Return sites from a bounded segment of an infinite wire."""
     direction = np.array(period / np.linalg.norm(period))
     def wire_shape(pos):
-        rel_pos = pos - np.array(center)
+        rel_pos = center - pos
         projection = direction * np.dot(direction, rel_pos) - rel_pos
         return sum(projection**2) <= r**2 and ymin < pos[1] < ymax
+    return lat.shape(wire_shape, center)
 
-    return wire_shape
-
+# Directions of the leads, positions of the centers of the lead segments to be
+# attached, and the boundaries of these segments in y-directions.
 wire_dir = [(-1., -1.), (3., -4.), (2., 4.)]
-wire_center = [(h/2 - 50, -w/2 + 50), (h/2, -w/2 + 180),
-               (h/2 + 30, -w/2 + 200)]
+wire_center = [(166, -236), (216, -106), (246, -86)]
 ylims = [(-400, -200), (-440, -100), (-100, 60)]
 
+# Add segments of leads to the scattering region, and attach leads themselves.
 for direction, center, ylim in zip(wire_dir, wire_center, ylims):
-    sys[lat.shape(make_wire_shape(direction, center, 50, *ylim), center)] = 4
+    sys[wire_shape(direction, np.array(center), 50, *ylim)] = 4
     lead = kwant.Builder(kwant.TranslationalSymmetry(direction))
     lead[lat.wire(center, 50)] = 4
     lead[lat.neighbors()] = -1
     sys.attach_lead(lead)
 
+# Finally add hoppings to the system, get its wave function, and plot.
 sys[lat.neighbors()] = -1
-
 sys = sys.finalized()
-
 wfs = kwant.wave_function(sys, energy=0.14)(0)[0]
 kwant.plotter.map(sys, abs(wfs), oversampling=1, cmap="PuBu")