kwant.builder.Symmetry

class kwant.builder.Symmetry

Bases: object

Abstract base class for spatial symmetries.

Many physical systems possess a discrete spatial symmetry, which results in special properties of these systems. This class is the standard way to describe discrete spatial symmetries in Kwant. An instance of this class can be passed to a Builder instance at its creation. The most important kind of symmetry is translational symmetry, used to define scattering leads.

Each symmetry has a fundamental domain – a set of sites and hoppings, generating all the possible sites and hoppings upon action of symmetry group elements. A class derived from Symmetry has to implement mapping of any site or hopping into the fundamental domain, applying a symmetry group element to a site or a hopping, and a method which to determine the group element bringing some site from the fundamental domain to the requested one. Additionally, it has to have a property num_directions returning the number of independent symmetry group generators (number of elementary periods for translational symmetry).

A ValueError must be raised by the symmetry class whenever a symmetry is used together with sites whose site family is not compatible with it. A typical example of this is when the vector defining a translational symmetry is not a lattice vector.

The type of the domain objects as handled by the methods of this class is not specified. The only requirement is that it must support the unary minus operation. The reference implementation of to_fd() is hence self.act(-self.which(a), a, b).

Methods

abstract act(element, a, b=None)

Act with a symmetry group element on a site or hopping.

abstract has_subgroup(other)

Test whether self has the subgroup other…

or, in other words, whether other is a subgroup of self. The reason why this is the abstract method (and not is_subgroup) is that in general it’s not possible for a subgroup to know its supergroups.

in_fd(site)

Tell whether site lies within the fundamental domain.

abstract subgroup(*generators)

Return the subgroup generated by a sequence of group elements.

to_fd(a, b=None)

Map a site or hopping to the fundamental domain.

If b is None, return a site equivalent to a within the fundamental domain. Otherwise, return a hopping equivalent to (a, b) but where the first element belongs to the fundamental domain.

Equivalent to self.act(-self.which(a), a, b).

abstract which(site)

Calculate the domain of the site.

Return the group element whose action on a certain site from the fundamental domain will result in the given site.

Attributes

num_directions

Number of elementary periods of the symmetry.