diff --git a/doc/source/pre/whatsnew/1.1.rst b/doc/source/pre/whatsnew/1.1.rst index 6e9a4fd90d11fa23bd69e8b9a2cb0d2630cd16e5..c53199844f416d8491deae5d831aa99d6beb22a6 100644 --- a/doc/source/pre/whatsnew/1.1.rst +++ b/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. diff --git a/kwant/builder.py b/kwant/builder.py index 70558dc761da3ee36e26769d022da331d0d7c090..e59bc7e20ce6cca5da43d8030198e73072492d3d 100644 --- a/kwant/builder.py +++ b/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.