kwant.builder.Builder

class kwant.builder.Builder(symmetry=None, *, conservation_law=None, time_reversal=None, particle_hole=None, chiral=None)

Bases: object

A tight binding system defined on a graph.

An alias exists for this common name: kwant.Builder.

This is one of the central types in Kwant. It is used to construct tight binding systems in a flexible way.

The nodes of the graph are Site instances. The edges, i.e. the hoppings, are pairs (2-tuples) of sites. Each node and each edge has a value associated with it. The values associated with nodes are interpreted as on-site Hamiltonians, the ones associated with edges as hopping integrals.

To make the graph accessible in a way that is natural within the Python language it is exposed as a mapping (much like a built-in Python dictionary). Keys are sites or hoppings. Values are 2d arrays (e.g. NumPy or Tinyarray) or numbers (interpreted as 1 by 1 matrices).

Parameters:

• symmetry (Symmetry or None) – The spatial symmetry of the system.

• conservation_law (2D array, dictionary, function, or None) – An onsite operator with integer eigenvalues that commutes with the Hamiltonian. The ascending order of eigenvalues corresponds to the selected ordering of the Hamiltonian subblocks. If a dict is given, it maps from site families to such matrices. If a function is given it must take the same arguments as the onsite Hamiltonian functions of the system and return the onsite matrix.

• time_reversal (scalar, 2D array, dictionary, function, or None) – The unitary part of the onsite time-reversal symmetry operator. Same format as that of conservation_law.

• particle_hole (scalar, 2D array, dictionary, function, or None) – The unitary part of the onsite particle-hole symmetry operator. Same format as that of conservation_law.

• chiral (2D array, dictionary, function or None) – The unitary part of the onsite chiral symmetry operator. Same format as that of conservation_law.

Notes

Values can be also functions that receive the site or the hopping (passed to the function as two sites) and possibly additional arguments and are expected to return a valid value. This allows to define systems quickly, to modify them without reconstructing, and to save memory for many-orbital models.

In addition to simple keys (single sites and hoppings) more powerful keys are possible as well that allow to manipulate multiple sites/hoppings in a single operation. Such keys are internally expanded into a sequence of simple keys by using the method Builder.expand. For example, syst[general_key] = value is equivalent to

for simple_key in syst.expand(general_key):
    syst[simple_key] = value

Builder instances automatically ensure that every hopping is Hermitian, so that if builder[a, b] has been set, there is no need to set builder[b, a].

Builder instances can be made to automatically respect a Symmetry that is passed to them during creation. The behavior of builders with a symmetry is slightly more sophisticated: all keys are mapped to the fundamental domain of the symmetry before storing them. This may produce confusing results when neighbors of a site are queried.

The method attach_lead works only if the sites affected by them have tags which are sequences of integers. It makes sense only when these sites live on a regular lattice, like the ones provided by kwant.lattice.

Attaching a lead manually (without the use of attach_lead) amounts to creating a Lead object and appending it to the list of leads accessbile as the leads attribute.

conservation_law, time_reversal, particle_hole, and chiral affect the basis in which scattering modes derived from the builder are expressed - see DiscreteSymmetry for details.

Warning

If functions are used to set values in a builder with a symmetry, then they must satisfy the same symmetry. There is (currently) no check and wrong results will be the consequence of a misbehaving function.

leads

The leads that are attached to the system.

Type:

list of Lead instances

Examples

Define a site.

>>> builder[site] = value

Print the value of a site.

>>> print(builder[site])

Define a hopping.

>>> builder[site1, site2] = value

Delete a site.

>>> del builder[site3]

Detach the last lead. (This does not remove the sites that were added to the scattering region by attach_lead.)

>>> del builder.leads[-1]

Methods

attach_lead(lead_builder, origin=None, add_cells=0)

Attach a lead to the builder, possibly adding missing sites.

This method first adds sites from ‘lead_builder’ until the interface where the lead will attach is “smooth”. Then it appends the ‘lead_builder’ and the interface sites as a BuilderLead to the ‘leads’ of this builder.

Parameters:

• lead_builder (Builder with 1D translational symmetry) – Builder of the lead which has to be attached.

• origin (Site) – 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

Return type:

list of Site objects that were added to the system.

Raises:

ValueError – If lead_builder does not have proper symmetry, has hoppings with range of more than one lead unit cell, or if it is not completely interrupted by the system.

Notes

This method is not fool-proof, i.e. if it raises an error, there is no guarantee that the system stayed unaltered.

The system must “interrupt” the lead that is being attached. This means that for each site in the lead that has a hopping to a neighbnoring unit cell there must be at least one site in the system that is an image of the lead site under the action of the lead’s translational symmetry. In order to interrupt the lead, the system must contain sites from the same site family as the sites in the lead. Below are three examples of leads being attached to systems:

Successful           Successful          Unsuccessful
----------           ----------          ------------
Lead   System        Lead   System        Lead  System
x-  …      o         x   …                x-  …
|          |         |                    |
x-  …    o-o         x-  …    o-o         x-  …  o-o
|        | |         |        | |         |      | |
x-  …  o-o-o         x-  …  o-o-o         x-  …  o-o

The second case succeeds, as even though the top site has no image in the system, because the top site has no hoppings to sites in other unit cells.

Sites may be added to the system when the lead is attached, so that the interface to the lead is “smooth”. Below we show the system after having attached a lead. The ‘x’ symbols in the system indicate the added sites:

Lead   System        Lead   System
x-  …  x-x-o         x   …  x
|      | | |         |      |
x-  …  x-o-o         x-  …  x-o-o
|      | | |         |      | | |
x-  …  o-o-o         x-  …  o-o-o

closest(pos)

Return the site that is closest to the given position.

This function takes into account the symmetry of the builder. It is assumed that the symmetry is a translational symmetry.

This function executes in a time proportional to the number of sites, so it is not efficient for large builders. It is especially slow for builders with a symmetry, but such systems often contain only a limited number of sites.

dangling()

Return an iterator over all dangling sites.

Sites are considered as dangling when less than two hoppings lead to them.

degree(site)

Return the number of neighbors of a site.

eradicate_dangling()

Keep deleting dangling sites until none are left.

Sites are considered as dangling when less than two hoppings lead to them.

expand(key)

Expand a general key into an iterator over simple keys.

Parameters:

key (builder key (see notes)) – The key to be expanded

Notes

Keys are (recursively):

• Simple keys: sites or 2-tuples of sites (=hoppings).

• Any (non-tuple) iterable of keys, e.g. a list or a generator expression.

• Any function that returns a key when passed a builder as sole argument, e.g. a HoppingKind instance or the function returned by shape.

This method is internally used to expand the keys when getting or deleting items of a builder (i.e. syst[key] = value or del syst[key]).

fill(template, shape, start, *, max_sites=10000000)

Populate builder using another one as a template.

Starting from one or multiple sites, traverse the graph of the template builder and copy sites and hoppings to the target builder. The traversal stops at sites that are already present in the target and on sites that are not inside the provided shape.

This function takes into account translational symmetry. As such, typically the template will have a higher symmetry than the target.

Newly added sites are connected by hoppings to sites that were already present. This facilitates construction of a system by a series of calls to ‘fill’.

Parameters:

• template (Builder instance) – The builder used as the template. The symmetry of the target builder must be a subgroup of the symmetry of the template.

• shape (callable) – A boolean function of site returning whether the site should be added to the target builder or not. The shape must be compatible with the symmetry of the target builder.

• start (Site instance or iterable thereof or iterable of numbers) – The site(s) at which the the flood-fill starts. If start is an iterable of numbers, the starting site will be template.closest(start).

• max_sites (positive number) – The maximal number of sites that may be added before RuntimeError is raised. Used to prevent using up all memory.

Returns:

added_sites

Return type:

list of Site objects that were added to the system.

Raises:

• ValueError – If the symmetry of the target isn’t a subgroup of the template symmetry.

• RuntimeError – If more than max_sites sites are to be added. The target builder will be left in an unusable state.

Notes

This function uses a flood-fill algorithm. If the template builder consists of disconnected parts, the fill will stop at their boundaries.

finalized()

Return a finalized (=usable with solvers) copy of the system.

Returns:

• finalized_system (kwant.builder.FiniteSystem) – If there is no symmetry.

• finalized_system (kwant.builder.InfiniteSystem) – If a symmetry is present.

Notes

This method does not modify the Builder instance for which it is called.

Upon finalization, it is implicitly assumed that every function assigned as a value to a builder with a symmetry possesses the same symmetry.

Attached leads are also finalized and will be present in the finalized system to be returned.

Currently, only Builder instances without or with a 1D translational Symmetry can be finalized.

hopping_value_pairs()

Return an iterator over all (hopping, value) pairs.

hoppings()

Return an iterator over all Builder hoppings.

The hoppings that are returned belong to the fundamental domain of the Builder symmetry, and are not necessarily the ones that were set initially (but always the equivalent ones).

neighbors(site)

Return an iterator over all neighbors of a site.

Technical note: This method respects the symmetry of the builder, i.e. the returned sites are really connected to the given site (and not to its image in the fundamental domain).

reversed()

Return a shallow copy of the builder with the symmetry reversed.

This method can be used to attach the same infinite system as lead from two opposite sides. It requires a builder to which an infinite symmetry is associated.

site_value_pairs()

Return an iterator over all (site, value) pairs.

sites()

Return a read-only set over all sites.

The sites that are returned belong to the fundamental domain of the Builder symmetry, and are not necessarily the ones that were set initially (but always the equivalent ones).

substituted(**subs)

Return a copy of this Builder with modified parameter names.

update(other)

Update builder from other.

All sites and hoppings of other, together with their values, are written to self, overwriting already existing sites and hoppings. The leads of other are appended to the leads of the system being updated.

This method requires that both builders share the same symmetry.