kwant.builder.Builder

class kwant.builder.Builder(symmetry=None)

Bases: object

A tight binding system defined on a graph.

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 symmetry of the system.

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, sys[general_key] = value is equivalent to

for simple_key in sys.expand(general_key):
    sys[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. First of all, it is implicitly assumed throughout Kwant that every function assigned as a value to a builder with a symmetry possesses the same symmetry. Secondly, 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.

builder0 += builder1 adds all the sites, hoppings, and leads of builder1 to builder0. Sites and hoppings present in both systems are overwritten by those in builder1. The leads of builder1 are appended to the leads of the system being extended.

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.

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]

Methods

attach_lead(lead_builder, origin=None)

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

Returns the lead number (integer) of the attached lead.

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.

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 returns an error, there is no guarantee that the system stayed unaltered.

The lead numbering starts from zero and increments from there, i.e. the leads are numbered in the order in which they are attached.

dangling()

Return an iterator over all dangling sites.

degree(site)

Return the number of neighbors of a site.

eradicate_dangling()

Keep deleting dangling sites until none are left.

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. sys[key] = value or del sys[key]).

finalized()

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

Returns:

finalized_system : kwant.system.FiniteSystem

If there is no symmetry.

finalized_system : kwant.system.InfiniteSystem

If a symmetry is present.

Notes

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

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.

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).