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.

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


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.


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 this list.


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.


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]


leads (list of Lead instances) The leads that are attached to the system.


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

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

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


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.


added_sites : list of Site objects that were added to the system.



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.


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.


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.


Return an iterator over all dangling sites.


Return the number of neighbors of a site.


Keep deleting dangling sites until none are left.


Expand a general key into an iterator over simple keys.


key : builder key (see notes)

The key to be expanded


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


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.


added_sites : list of Site objects that were added to the system.



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


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


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


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


finalized_system : kwant.system.FiniteSystem

If there is no symmetry.

finalized_system : kwant.system.InfiniteSystem

If a symmetry is present.


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.


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


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


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


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.


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


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


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.

Previous topic

3.2. kwant.builder – High-level construction of systems

Next topic


This Page