# 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 |

## 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]) |
Modify the onsite energy, e.g. to apply an electric field |

`hopping_energy_modifier` ([is_double, is_complex]) |
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 |

Experimental

`hopping_generator` (name, energy) |
Introduce a new hopping family (with a new `hop_id` ) via a list of index pairs |

## 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]) |
Create a path which connects the given k points |

`Bands` (k_path, energy) |
Band structure along a path in k-space |

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

`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 |