API Reference

This detailed reference lists all the classes and functions contained in the package. If you are just looking to get started, read the Tutorial first.

The Lattice describes the unit cell of a crystal, while the Model is used to build up a larger system by translating the unit cell to fill a certain shape or symmetry. The model builds the Hamiltonian matrix by applying fields and other modifier parameters.

Lattice(a1[, a2, a3])

Unit cell of a Bravais lattice, the basic building block of a tight-binding model

Model(lattice, *args)

Builds a Hamiltonian from lattice, shape, symmetry and modifier parameters

Shapes

The geometry of a finite-sized system can be defined using the Polygon class (2D only) or using FreeformShape (1 to 3 dimensions). A few common shapes are included in the package and listed below. These predefined shapes are just functions which configure and return a shape class object.

Building blocks

Polygon(vertices)

Shape defined by a list of vertices in a 2D plane

FreeformShape(contains, width[, center])

Shape in 1 to 3 dimensions, defined by a function and a bounding box

CompositeShape(shape1, shape2, op)

A composition of 2 shapes using some operator (and, or, xor...)

Predefined shapes

circle(radius[, center])

A circle in the xy plane

line(a, b)

A line shape intended for 1D lattices or to specify leads for 2D lattices

primitive([a1, a2, a3])

Follow the primitive lattice shape -- just repeat the unit cell a number of times

rectangle(x[, y])

A rectangle in the xy plane

regular_polygon(num_sides, radius[, angle])

A polygon shape where all sides have equal length

Symmetry

translational_symmetry([a1, a2, a3])

Simple translational symmetry in, the form of \(e^{i \vec k \cdot \vec r}\).

Modifiers

The following decorators are used to create functions which express some feature of a tight-binding model, such as various fields, defects or geometric deformations.

Decorators

site_state_modifier([min_neighbors])

Modify the state (valid or invalid) of lattice sites, e.g. to create vacancies.

site_position_modifier()

Modify the position of lattice sites, e.g. to apply geometric deformations.

onsite_energy_modifier([is_double, phase])

Modify the onsite energy, e.g. to apply an electric field.

hopping_energy_modifier([is_double, ...])

Modify the hopping energy, e.g. to apply a magnetic field.

Predefined modifiers

constant_potential(magnitude)

Apply a constant onsite energy to every lattice site

force_double_precision()

Forces the model to use double precision even if that's not require by any modifier

force_complex_numbers()

Forces the model to use complex numbers even if that's not require by any modifier

force_phase()

Forces the model to add the phase so that eigenvectors have the right phase

Generators

The following decorators are used to create functions which add features to a tight-binding model, such as hoppings and sites.

Decorators

hopping_generator(name, energy)

Introduce a new hopping family (with a new hop_id) via a list of index pairs

site_generator(name, energy)

Introduce a new site family (with a new sub_id) via a list of site positions

Compute

After a Model is constructed, computational routines can be applied to determine various physical properties. The following submodules contain functions for exact diagonalization as well as some approximative compute methods. Follow the links below for details.

solver

Eigensolvers with a few extra computation methods

chebyshev

Computations based on Chebyshev polynomial expansion

Experimental

parallel

Multi-threaded functions for parameter sweeps

Results

Result objects are usually produced by compute functions, but they are also used to express certain model properties. They hold data and offer postprocessing and plotting methods specifically adapted to the nature of the physical properties (i.e. the stored data).

The utility functions pb.save() and pb.load() can be used to efficiently store entire result objects into files. The information about the kind of physical property is saved along with the raw data, i.e. executing result = pb.load("data_file.pbz") followed by result.plot() will work and present the appropriate figure.

save(obj, file)

Save an object to a compressed file

load(file)

Load an object from a compressed file

make_path(k0, k1, *ks[, step, point_labels])

Create a path which connects the given k points

Path(array, point_indices[, point_labels])

A ndarray which represents a path connecting certain points

Bands(k_path, energy)

Band structure along a path in k-space

Wavefunction(bands, wavefunction[, ...])

FatBands(bands, data[, labels])

Band structure with data per k-point, like SOC or pDOS

Eigenvalues(eigenvalues[, probability])

Hamiltonian eigenvalues with optional probability map

Series(variable, data[, labels])

A series of data points determined by a common relation, i.e. \(y = f(x)\).

SpatialMap(data, positions[, sublattices])

Represents some spatially dependent property: data mapped to site positions

StructureMap(data, sites, hoppings[, boundaries])

A subclass of SpatialMap that also includes hoppings between sites

Sweep(x, y, data[, labels, tags])

2D parameter sweep with x and y 1D array parameters and data 2D array result

NDSweep(variables, data[, labels, tags])

ND parameter sweep

SpatialLDOS(data, energy, structure)

Holds the results of KPM.calc_spatial_ldos()

Positions(x, y, z)

Named tuple of arrays

make_area(k0, k1[, k_origin, step, point_labels])

Create an area of k-point between k0 and k1, starting from k_origin.

BandsArea(k_area, energy)

Band structure alond an area in k-space

WavefunctionArea(bands, wavefunction[, ...])

FatBandsArea(bands, data[, labels])

Band structure with data per k-point, like SOC or pDOS

Disentangle(overlap_matrix)

Components

The following submodules contain classes and functions which are not meant to created manually, but they are components of other classes (e.g. Model) so they are used regularly (even if indirectly).

system

Structural information and utilities

leads

Lead interface for scattering models

Miscellaneous

constants

A few useful physical constants

pltutils

Collection of utility functions for matplotlib

support.alias