simplify lead construction in the tutorial examples

doc/source/images/ab_ring.py.diff

@@ -28,7 +28,7 @@
          return exp(1j * phi)
  
      def crosses_branchcut(hop):
-@@ -82,6 +84,50 @@
+@@ -78,6 +80,50 @@
      return sys
  
  
@@ -79,7 +79,7 @@
  def plot_conductance(sys, energy, fluxes):
      # compute conductance
  
-@@ -91,18 +137,29 @@
+@@ -87,18 +133,29 @@
          smatrix = kwant.solve(sys, energy, kwargs={'phi': flux})
          data.append(smatrix.transmission(1, 0))
  
@@ -114,7 +114,7 @@
  
      # Finalize the system.
      sys = sys.finalized()
-@@ -112,6 +169,15 @@
+@@ -108,6 +165,15 @@
                                                  for i in xrange(100)])
  
  

doc/source/images/quantum_well.py.diff

@@ -8,7 +8,7 @@
  
  
  def make_system(a=1, t=1.0, W=10, L=30, L_well=10):
-@@ -61,19 +62,25 @@
+@@ -52,19 +53,25 @@
          smatrix = kwant.solve(sys, energy, kwargs={'pot': -welldepth})
          data.append(smatrix.transmission(1, 0))
  

doc/source/images/quantum_wire.py.diff

@@ -8,22 +8,21 @@
  
  # First, define the tight-binding system
  
-@@ -72,8 +73,9 @@
- sys.attach_lead(lead1)
+@@ -65,7 +66,9 @@
+ sys.attach_lead(right_lead)
  
  # Plot it, to make sure it's OK
--
 -kwant.plot(sys)
 +size = (_defs.figwidth_in, 0.3 * _defs.figwidth_in)
 +kwant.plot(sys, file="quantum_wire_sys.pdf", fig_size=size, dpi=_defs.dpi)
 +kwant.plot(sys, file="quantum_wire_sys.png", fig_size=size, dpi=_defs.dpi)
  
  # Finalize the system
+ sys = sys.finalized()
+@@ -86,8 +89,13 @@
  
-@@ -97,8 +99,13 @@
  # Use matplotlib to write output
  # We should see conductance steps
- 
 -pyplot.figure()
 +fig = pyplot.figure()
  pyplot.plot(energies, data)

doc/source/images/spin_orbit.py.diff

@@ -8,7 +8,7 @@
  
  # define Pauli-matrices for convenience
  sigma_0 = tinyarray.array([[1, 0], [0, 1]])
-@@ -73,19 +74,24 @@
+@@ -67,19 +68,24 @@
          smatrix = kwant.solve(sys, energy)
          data.append(smatrix.transmission(1, 0))
  

doc/source/tutorial/ab_ring.py

@@ -68,25 +68,21 @@ def make_system(a=1, t=1.0, W=10, r1=10, r2=20):
     #### Define the leads. ####
     # left lead
 #HIDDEN_BEGIN_qwgr
-    sym_lead0 = kwant.TranslationalSymmetry((-a, 0))
-    lead0 = kwant.Builder(sym_lead0)
+    sym_lead = kwant.TranslationalSymmetry((-a, 0))
+    lead = kwant.Builder(sym_lead)
 
     def lead_shape(pos):
         (x, y) = pos
         return (-1 < x < 1) and (-W / 2 < y < W / 2)
 
-    lead0[lat.shape(lead_shape, (0, 0))] = 4 * t
-    lead0[lat.nearest] = -t
+    lead[lat.shape(lead_shape, (0, 0))] = 4 * t
+    lead[lat.nearest] = -t
 #HIDDEN_END_qwgr
 
-    # Then the lead to the right
-    # [again, obtained using reversed()]
-    lead1 = lead0.reversed()
-
     #### Attach the leads and return the system. ####
 #HIDDEN_BEGIN_skbz
-    sys.attach_lead(lead0)
-    sys.attach_lead(lead1)
+    sys.attach_lead(lead)
+    sys.attach_lead(lead.reversed())
 #HIDDEN_END_skbz
 
     return sys

doc/source/tutorial/quantum_well.py

@@ -38,21 +38,12 @@ def make_system(a=1, t=1.0, W=10, L=30, L_well=10):
     sys[lat.nearest] = -t
 #HIDDEN_END_coid
 
-    #### Define the leads. ####
-    # First the lead to the left, ...
-    sym_lead0 = kwant.TranslationalSymmetry((-a, 0))
-    lead0 = kwant.Builder(sym_lead0)
-
-    lead0[(lat(0, j) for j in xrange(W))] = 4 * t
-    lead0[lat.nearest] = -t
-
-    # ... then the lead to the right.  We use a method that returns a copy of
-    # `lead0` with its direction reversed.
-    lead1 = lead0.reversed()
-
-    #### Attach the leads and return the finalized system. ####
-    sys.attach_lead(lead0)
-    sys.attach_lead(lead1)
+    #### Define and attach the leads. ####
+    lead = kwant.Builder(kwant.TranslationalSymmetry((-a, 0)))
+    lead[(lat(0, j) for j in xrange(W))] = 4 * t
+    lead[lat.nearest] = -t
+    sys.attach_lead(lead)
+    sys.attach_lead(lead.reversed())
 
     return sys
 

doc/source/tutorial/quantum_wire.py

@@ -45,62 +45,52 @@ for i in xrange(L):
             sys[lat(i, j), lat(i - 1, j)] = -t
 #HIDDEN_END_zfvr
 
-# Then, define the leads:
+# Then, define and attach the leads:
 
 # First the lead to the left
-
 # (Note: TranslationalSymmetry takes a real-space vector)
 #HIDDEN_BEGIN_xcmc
-sym_lead0 = kwant.TranslationalSymmetry((-a, 0))
-lead0 = kwant.Builder(sym_lead0)
+sym_left_lead = kwant.TranslationalSymmetry((-a, 0))
+left_lead = kwant.Builder(sym_left_lead)
 #HIDDEN_END_xcmc
 
 #HIDDEN_BEGIN_ndez
 for j in xrange(W):
-    lead0[lat(0, j)] = 4 * t
-
+    left_lead[lat(0, j)] = 4 * t
     if j > 0:
-        lead0[lat(0, j), lat(0, j - 1)] = -t
-
-    lead0[lat(1, j), lat(0, j)] = -t
+        left_lead[lat(0, j), lat(0, j - 1)] = -t
+    left_lead[lat(1, j), lat(0, j)] = -t
 #HIDDEN_END_ndez
 
+#HIDDEN_BEGIN_fskr
+sys.attach_lead(left_lead)
+#HIDDEN_END_fskr
+
 # Then the lead to the right
 #HIDDEN_BEGIN_xhqc
-
-sym_lead1 = kwant.TranslationalSymmetry((a, 0))
-lead1 = kwant.Builder(sym_lead1)
+sym_right_lead = kwant.TranslationalSymmetry((a, 0))
+right_lead = kwant.Builder(sym_right_lead)
 
 for j in xrange(W):
-    lead1[lat(0, j)] = 4 * t
-
+    right_lead[lat(0, j)] = 4 * t
     if j > 0:
-        lead1[lat(0, j), lat(0, j - 1)] = -t
+        right_lead[lat(0, j), lat(0, j - 1)] = -t
+    right_lead[lat(1, j), lat(0, j)] = -t
 
-    lead1[lat(1, j), lat(0, j)] = -t
+sys.attach_lead(right_lead)
 #HIDDEN_END_xhqc
 
-# Then attach the leads to the system
-
-#HIDDEN_BEGIN_fskr
-sys.attach_lead(lead0)
-sys.attach_lead(lead1)
-#HIDDEN_END_fskr
-
 # Plot it, to make sure it's OK
-
 #HIDDEN_BEGIN_wsgh
 kwant.plot(sys)
 #HIDDEN_END_wsgh
 
 # Finalize the system
-
 #HIDDEN_BEGIN_dngj
 sys = sys.finalized()
 #HIDDEN_END_dngj
 
 # Now that we have the system, we can compute conductance
-
 #HIDDEN_BEGIN_buzn
 energies = []
 data = []
@@ -119,7 +109,6 @@ for ie in xrange(100):
 # Use matplotlib to write output
 # We should see conductance steps
 #HIDDEN_BEGIN_lliv
-
 pyplot.figure()
 pyplot.plot(energies, data)
 pyplot.xlabel("energy [t]")

doc/source/tutorial/quantum_wire_revisited.py

@@ -32,27 +32,18 @@ def make_system(a=1, t=1.0, W=10, L=30):
     sys[lat.nearest] = -t
 #HIDDEN_END_nooi
 
-    #### Define the leads. ####
-    # First the lead to the left, ...
-    # (Note: TranslationalSymmetry takes a real-space vector)
+    #### Define and attach the leads. ####
+    # Construct the left lead.
 #HIDDEN_BEGIN_iepx
-    sym_lead0 = kwant.TranslationalSymmetry((-a, 0))
-    lead0 = kwant.Builder(sym_lead0)
-
-    lead0[(lat(0, j) for j in xrange(W))] = 4 * t
-    lead0[lat.nearest] = -t
+    lead = kwant.Builder(kwant.TranslationalSymmetry((-a, 0)))
+    lead[(lat(0, j) for j in xrange(W))] = 4 * t
+    lead[lat.nearest] = -t
 #HIDDEN_END_iepx
 
-    # ... then the lead to the right.  We use a method that returns a copy of
-    # `lead0` with its direction reversed.
-#HIDDEN_BEGIN_xkdo
-    lead1 = lead0.reversed()
-#HIDDEN_END_xkdo
-
-    #### Attach the leads and return the system. ####
+    # Attach the left lead and its reversed copy.
 #HIDDEN_BEGIN_yxot
-    sys.attach_lead(lead0)
-    sys.attach_lead(lead1)
+    sys.attach_lead(lead)
+    sys.attach_lead(lead.reversed())
 
     return sys
 #HIDDEN_END_yxot

doc/source/tutorial/spin_orbit.py

@@ -48,28 +48,22 @@ def make_system(a=1, t=1.0, alpha=0.5, e_z=0.08, W=10, L=30):
         1j * alpha * sigma_x
 #HIDDEN_END_uxrm
 
-    #### Define the leads. ####
-    # left lead
-    sym_lead0 = kwant.TranslationalSymmetry((-a, 0))
-    lead0 = kwant.Builder(sym_lead0)
+    #### Define the left lead. ####
+    lead = kwant.Builder(kwant.TranslationalSymmetry((-a, 0)))
 
 #HIDDEN_BEGIN_yliu
-    lead0[(lat(0, j) for j in xrange(W))] = 4 * t * sigma_0 + e_z * sigma_z
+    lead[(lat(0, j) for j in xrange(W))] = 4 * t * sigma_0 + e_z * sigma_z
     # hoppings in x-direction
-    lead0[kwant.builder.HoppingKind((1, 0), lat, lat)] = -t * sigma_0 - \
+    lead[kwant.builder.HoppingKind((1, 0), lat, lat)] = -t * sigma_0 - \
         1j * alpha * sigma_y
     # hoppings in y-directions
-    lead0[kwant.builder.HoppingKind((0, 1), lat, lat)] = -t * sigma_0 + \
+    lead[kwant.builder.HoppingKind((0, 1), lat, lat)] = -t * sigma_0 + \
         1j * alpha * sigma_x
 #HIDDEN_END_yliu
 
-    # Then the lead to the right
-    # (again, obtained using reverse()
-    lead1 = lead0.reversed()
-
     #### Attach the leads and return the finalized system. ####
-    sys.attach_lead(lead0)
-    sys.attach_lead(lead1)
+    sys.attach_lead(lead)
+    sys.attach_lead(lead.reversed())
 
     return sys
 

doc/source/tutorial/tutorial1.rst

@@ -73,11 +73,11 @@ system must have a translational symmetry:
     :start-after: #HIDDEN_BEGIN_xcmc
     :end-before: #HIDDEN_END_xcmc
 
-Here, the `~kwant.builder.Builder` takes a translational symmetry as the
-optional parameter. Note that the (real-space) vector ``(-a, 0)`` defining the
-translational symmetry must point in a direction *away* from the scattering
-region, *into* the lead -- hence, lead 0 [#]_ will be the left lead, extending
-to infinity to the left.
+Here, the `~kwant.builder.Builder` takes a
+`~kwant.lattice.TranslationalSymmetry` as the optional parameter. Note that the
+(real-space) vector ``(-a, 0)`` defining the translational symmetry must point
+in a direction *away* from the scattering region, *into* the lead -- hence, lead
+0 [#]_ will be the left lead, extending to infinity to the left.
 
 For the lead itself it is enough to add the points of one unit cell as well
 as the hoppings inside one unit cell and to the next unit cell of the lead.
@@ -89,7 +89,15 @@ simply a vertical line of points:
     :end-before: #HIDDEN_END_ndez
 
 Note that here it doesn't matter if you add the hoppings to the next or the
-previous unit cell -- the translational symmetry takes care of that.
+previous unit cell -- the translational symmetry takes care of that.  The
+isolated, infinite is attached at the correct position using
+
+.. literalinclude:: quantum_wire.py
+    :start-after: #HIDDEN_BEGIN_fskr
+    :end-before: #HIDDEN_END_fskr
+
+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
@@ -102,17 +110,7 @@ symmetry must point to the right, the remaining code is the same:
 Note that here we added points with x-coordinate 0, just as for the left lead.
 You might object that the right lead should be placed `L`
 (or `L+1`?) points to the right with respect to the left lead. In fact,
-you do not need to worry about that. The `~kwant.builder.Builder` with
-`~kwant.lattice.TranslationalSymmetry` represents a lead which is
-infinitely extended. These isolated, infinite leads can then be simply
-attached at the right position using:
-
-.. literalinclude:: quantum_wire.py
-    :start-after: #HIDDEN_BEGIN_fskr
-    :end-before: #HIDDEN_END_fskr
-
-More details about attaching leads can be found in the tutorial
-:ref:`tutorial-abring`.
+you do not need to worry about that.
 
 Now we have finished building our system! We plot it, to make sure we didn't
 make any mistakes:
@@ -323,48 +321,37 @@ matrix elements at once. More detailed example of using
 `~kwant.builder.HoppingKind` directly will be provided in
 :ref:`tutorial_spinorbit`.
 
-The leads can be constructed in an analogous way:
+The left lead is constructed in an analogous way:
 
 .. literalinclude:: quantum_wire_revisited.py
     :start-after: #HIDDEN_BEGIN_iepx
     :end-before: #HIDDEN_END_iepx
 
-Note that in the previous example, we essentially used the same code
-for the right and the left lead, the only difference was the direction
-of the translational symmetry vector. The
-`~kwant.builder.Builder` used for the lead provides a method
-`~kwant.builder.Builder.reversed` that returns a copy of the
-lead, but with it's translational vector reversed.  This can thus be
-used to obtain a lead pointing in the opposite direction, i.e. makes a
-right lead from a left lead:
-
-.. literalinclude:: quantum_wire_revisited.py
-    :start-after: #HIDDEN_BEGIN_xkdo
-    :end-before: #HIDDEN_END_xkdo
-
-The remainder of the code is identical to the previous example
-(except for a bit of reorganization into functions):
+The previous example duplicated almost identical code for the left and
+the right lead.  The only difference was the direction of the translational
+symmetry vector.  Here, we only construct the left lead, and use the method
+`~kwant.builder.Builder.reversed` of `~kwant.builder.Builder` to obtain a copy
+of a lead pointing in the opposite direction.  Both leads are attached as
+before and the finished system returned:
 
 .. literalinclude:: quantum_wire_revisited.py
     :start-after: #HIDDEN_BEGIN_yxot
     :end-before: #HIDDEN_END_yxot
 
-and
+The remainder of the script has been organized into two functions.  One for the
+plotting of the conductance.
 
 .. literalinclude:: quantum_wire_revisited.py
     :start-after: #HIDDEN_BEGIN_ayuk
     :end-before: #HIDDEN_END_ayuk
 
-Finally, we use a python trick to make our example usable both
-as a script, as well as allowing it to be imported as a module.
-We collect all statements that should be executed in the script
-in a ``main``-function:
+And one ``main`` function.
 
 .. literalinclude:: quantum_wire_revisited.py
     :start-after: #HIDDEN_BEGIN_cjel
     :end-before: #HIDDEN_END_cjel
 
-Finally, we use the following python construct [#]_ that executes
+Finally, we use the following standard Python construct [#]_ to execute
 ``main`` if the program is used as a script (i.e. executed as
 ``python tutorial1b.py``):
 
@@ -372,8 +359,8 @@ Finally, we use the following python construct [#]_ that executes
     :start-after: #HIDDEN_BEGIN_ypbj
     :end-before: #HIDDEN_END_ypbj
 
-If the example however is imported using ``import tutorial1b``,
-``main`` is not executed automatically. Instead, you can execute it
+If the example, however, is imported inside Python using ``import tutorial1b``,
+``main`` is not executed automatically.  Instead, you can execute it
 manually using ``tutorial1b.main()``.  On the other hand, you also
 have access to the other functions, ``make_system`` and
 ``plot_conductance``, and can thus play with the parameters.