implement lead_paddings attribute

There is nothing that consumes lead_paddings right now, but it will be useful
for plotting and gauge fixing.
Closes #266.

kwant/builder.py

@@ -574,6 +574,10 @@ class BuilderLead(Lead):
         The tight-binding system of a lead.
     interface : list of `Site` instances
         A sorted list of interface sites.
+    padding : list of `Site` instances
+        A sorted list of sites that originate from the lead, have the same
+        onsite Hamiltonian, and are connected by the same hoppings as the lead
+        sites.
 
     Notes
     -----
@@ -586,9 +590,10 @@ class BuilderLead(Lead):
     `BuilderLead` objects with all the information about the leads that are
     attached.
     """
-    def __init__(self, builder, interface):
+    def __init__(self, builder, interface, padding=None):
         self.builder = builder
-        self.interface = tuple(sorted(interface))
+        self.interface = sorted(interface)
+        self.padding = sorted(padding) if padding is not None else []
 
     def finalized(self):
         """Return a `kwant.builder.InfiniteSystem` corresponding to the
@@ -1725,7 +1730,7 @@ class Builder:
                 if sym.which(neighbor)[0] == max_dom:
                     interface.add(neighbor)
 
-        self.leads.append(BuilderLead(lead_builder, tuple(interface)))
+        self.leads.append(BuilderLead(lead_builder, interface, all_added))
         return all_added
 
     def finalized(self):
@@ -1964,6 +1969,7 @@ class FiniteSystem(_FinalizedBuilderMixin, system.FiniteSystem):
         #### Connect leads.
         finalized_leads = []
         lead_interfaces = []
+        lead_paddings = []
         for lead_nr, lead in enumerate(builder.leads):
             try:
                 with warnings.catch_warnings(record=True) as ws:
@@ -1992,6 +1998,16 @@ class FiniteSystem(_FinalizedBuilderMixin, system.FiniteSystem):
 
             lead_interfaces.append(np.array(interface))
 
+            padding = getattr(lead, 'padding', [])
+            # Some padding sites might have been removed after the lead was
+            # attached. Unlike in the case of the interface, this is not a
+            # problem.
+            finalized_padding = [
+                id_by_site[isite] for isite in padding if isite in id_by_site
+            ]
+
+            lead_paddings.append(np.array(finalized_padding))
+
         # Because many onsites/hoppings share the same (value, parameter)
         # pairs, we keep them in a cache so that we only store a given pair
         # in memory *once*. This is a similar idea to interning strings.
@@ -2010,6 +2026,7 @@ class FiniteSystem(_FinalizedBuilderMixin, system.FiniteSystem):
         self.symmetry = builder.symmetry
         self.leads = finalized_leads
         self.lead_interfaces = lead_interfaces
+        self.lead_paddings = lead_paddings
         self._init_discrete_symmetries(builder)
 
 

kwant/system.py

@@ -85,10 +85,15 @@ class FiniteSystem(System, metaclass=abc.ABCMeta):
     lead_interfaces : sequence of sequences of integers
         Each sub-sequence contains the indices of the system sites
         to which the lead is connected.
+    lead_paddings : sequence of sequences of integers
+        Each sub-sequence contains the indices of the system sites
+        that belong to the lead, and therefore have the same onsite as the lead
+        sites, and are connected by the same hoppings as the lead sites.
 
     Notes
     -----
-    The length of ``leads`` must be equal to the length of ``lead_interfaces``.
+    The length of ``leads`` must be equal to the length of ``lead_interfaces``
+    and ``lead_paddings``.
 
     For lead ``n``, the method leads[n].selfenergy must return a square matrix
     whose size is ``sum(len(self.hamiltonian(site, site)) for site in

kwant/tests/test_builder.py

@@ -1357,3 +1357,33 @@ def test_subs():
     # so the signature of 'onsite' is valid.
     sub_syst = syst.substituted(a='sitea')
     assert np.allclose(hamiltonian(sub_syst, sitea=1, b=2, c=3), expected)
+
+
+def test_attach_stores_padding():
+    lat = kwant.lattice.chain()
+    syst = kwant.Builder()
+    syst[lat(0)] = 0
+    lead = kwant.Builder(kwant.TranslationalSymmetry(lat.prim_vecs[0]))
+    lead[lat(0)] = 0
+    lead[lat(1), lat(0)] = 0
+    added_sites = syst.attach_lead(lead, add_cells=2)
+    assert syst.leads[0].padding == sorted(added_sites)
+
+
+def test_finalization_preserves_padding():
+    lat = kwant.lattice.chain()
+    syst = kwant.Builder()
+    for i in range(10):
+        syst[lat(i)] = 0
+
+    lead = kwant.Builder(kwant.TranslationalSymmetry(lat.prim_vecs[0]))
+    lead[lat(0)] = 0
+    lead[lat(0), lat(1)] = 0
+    # We use a low level way to provide a lead to directly check that the
+    # padding is preserved. We also check that the sites that do not belong to
+    # the system don't end up in the padding of the finalized system.
+    padding = [lat(0), lat(3), lat(5), lat(11)]
+    syst.leads.append(kwant.builder.BuilderLead(lead, [lat(0)], padding))
+    syst = syst.finalized()
+    # The order is guaranteed because the paddings are sorted.
+    assert [syst.sites[i] for i in syst.lead_paddings[0]] == padding[:-1]