Builder.attach_lead: add option add_cells

doc/source/pre/whatsnew/1.1.rst

@@ -10,3 +10,31 @@ Kwant's convention is that momenta are positive in the direction of
 `~kwant.physics.modes` did respect this convention, the momenta read off the
 band structure as given by `~kwant.physics.Bands` had the wrong sign.  This has
 been fixed now.
+
+New option ``add_cells`` of `~kwant.builder.Builder.attach_lead`
+----------------------------------------------------------------
+Before actually attaching a lead to a builder, the method
+`~kwant.builder.Builder.attach_lead` of `~kwant.builder.Builder` prepares a
+"nice" interface by adding "missing" sites such that the first unit cell of the
+lead is completely connected with the system under construction.  These sites
+and their hoppings are taken over from the lead.
+
+By setting the new option ``add_cells``, ``attach_lead`` can now be told to add
+*in* *addition* any number of complete unit cells of the lead to the system
+before attaching it.  Among other things, this can be useful for
+
+- controlling the hopping between the lead and the system (Leads are always
+  attached with their inter-unit-cell hopping to the system, but absorbing one
+  lead unit cell into the system allows to control this),
+
+- creating a buffer for long range disorder present in the system to die away
+  before the translation-invariant lead begins.
+
+To support these applications, ``attach_lead`` now returns a list of all the
+sites that have been added to the system.  Creating a buffer for disorder can
+be thus done as follows::
+
+    sys[sys.attach_lead(lead, add_cells=10)] = onsite
+
+Note how we set the onsite Hamiltonians of the sites that have been added to
+the value used in the system.

kwant/builder.py

@@ -989,7 +989,7 @@ class Builder(object):
         self.leads.extend(other_sys.leads)
         return self
 
-    def attach_lead(self, lead_builder, origin=None):
+    def attach_lead(self, lead_builder, origin=None, add_cells=0):
         """Attach a lead to the builder, possibly adding missing sites.
 
         Parameters
@@ -1000,6 +1000,13 @@ class Builder(object):
             The site which should belong to a domain where the lead should
             begin. It is used to attach a lead inside the system, e.g. to an
             inner radius of a ring.
+        add_cells : int
+            Number of complete unit cells of the lead to be added to the system
+            *after* the missing sites have been added.
+
+        Returns
+        -------
+            added_sites : list of `Site` objects that were added to the system.
 
         Raises
         ------
@@ -1013,6 +1020,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.
         """
+        if add_cells < 0 or int(add_cells) != add_cells:
+            raise ValueError('add_cells must be an integer >= 0.')
+
         sym = lead_builder.symmetry
         H = lead_builder.H
 
@@ -1054,12 +1064,13 @@ class Builder(object):
         if len(all_doms) == 0:
             raise ValueError('Builder does not intersect with the lead,'
                              ' this lead cannot be attached.')
-        max_dom = max(all_doms)
+        max_dom = max(all_doms) + add_cells
         min_dom = min(all_doms)
         del all_doms
 
         interface = set()
         added = set()
+        all_added = []
         # Initialize flood-fill: create the outermost sites.
         for site in H:
             for neighbor in lead_builder.neighbors(site):
@@ -1069,6 +1080,7 @@ class Builder(object):
                         self[neighbor] = lead_builder[neighbor]
                         added.add(neighbor)
                     interface.add(neighbor)
+        all_added.extend(added)
 
         # Do flood-fill.
         covered = True
@@ -1093,9 +1105,10 @@ class Builder(object):
                         covered = True
                     self[site_new, site] = lead_builder[site_new, site]
             added = added2
+            all_added.extend(added)
 
         self.leads.append(BuilderLead(lead_builder, tuple(interface)))
-        return len(self.leads) - 1
+        return all_added
 
     def finalized(self):
         """Return a finalized (=usable with solvers) copy of the system.