Software Open Access

pybinding v0.9.4: a Python package for tight-binding calculations

Moldovan, Dean; Anđelković, Miša; Peeters, Francois

Pybinding is a Python package for numerical tight-binding calculations in solid state physics. The main features include:

  • Declarative model construction - The user just needs to describe what the model should be, but not how to build it. Pybinding will take care of the numerical details of building the Hamiltonian matrix so users can concentrate on the physics, i.e. the quantum properties of the model.

  • Fast compute - Pybinding's implementation of the kernel polynomial method allows for very fast calculation of various physical properties of tight-binding systems. Exact diagonalization is also available through the use of scipy's eigenvalue solvers. The framework is very flexible and allows the addition of user-defined computation routines.

  • Result analysis and visualization - The package contains utility functions for post-processing the raw result data. The included plotting functions are tailored for tight-binding problems to help visualize the model structure and to make sense of the results.

The code interface is written in Python with the aim to be as user-friendly and flexible as possible. Under the hood, C++11 is used to accelerate demanding tasks to deliver high performance with low memory usage.

See the documentation for more details:


Changelog for version 0.9

  • Added support for Kwant v1.3.x and improved Model.tokwant() exporting of multi-orbital models.

Updated requirements

  • This version includes extensive internal improvements and raises the minimum requirements for installation. Starting with this release, only Python >= 3.5 is supported. Newer versions of the scientific Python packages are also required: numpy >= 1.12, scipy >= 0.19 and matplotlib >= 2.0.

  • On Linux, the minimum compiler requirements have also been increased to get access to C++14 for the core of the library. To compile from source, you'll need GCC >= 5.0 or clang >= 3.5.

Multi-orbital models

  • Improved support for models with multiple orbitals, spins and any additional degrees of freedom. These can now be specified simply by inputting a matrix as the onsite or hopping term (instead of a scalar value). For more details, see the "Multi-orbital models" section of the documentation.

  • Lifted all limits on the number of sublattices and hoppings which can be defined in a Lattice object. The previous version was limited to a maximum of 128 onsite and hopping terms per unit cell (but those could be repeated an unlimited number of times to form a complete system). All restrictions are now removed so that the unit cell size is only limited by available memory. In addition, the memory usage of the internal system format has been reduced.

  • Added a 3-band model of group 6 transition metal dichalcogenides to the Material Repository. The available TMDs include: MoS2, WS2, MoSe2, WSe2, MoTe2, WTe2. These are all monolayers.

Composite shapes

  • Complicated system geometries can now be created easily by composing multiple simple shapes. This is done using set operations, e.g. unions, intersections, etc. A complete guide for this functionality is available in the "Composite shapes" section of the documentation.

Kernel polynomial method

  • The KPM implementation has been revised and significantly expanded. A guide and several examples are available in the "Kernel polynomial method" section of the documentation (part 9 of the Tutorial). For a complete overview of the available methods and kernels, see the chebyshev section of the API reference.

  • New builtin computation methods include the stochastically-evaluated density of states (DOS) and electrical conductivity (using the Kubo-Bastin approach).

  • The new low-level interface produces KPM expansion moments which allows users to create their own KPM-based computation routines.

  • The performance of various KPM computations has been significantly improved for CPUs with AVX support (~1.5x speedup on average, but also up to 2x in some cases with complex numbers).

  • Added a method for calculating spatial LDOS using KPM. See the "Kernel Polynomial Method" tutorial page and the KPM.calc_spatial_ldos API reference.

  • Improved single-threaded performance of KPM.calc_dos by ~2x by switching to a more efficient vectorization method. (Multiple random starter vectors are now computed simultaneously and accelerated using SIMD intrinsics.)

  • Various KPM methods now take advantage of multiple threads. This improves performance depending on the number of cores on the target machine. (However, for large systems performance is limited by RAM bandwidth, not necessarily core count.)

  • LDOS calculations for multiple orbitals also take advantage of the same vectorization and multi-threading improvements. Single-orbital LDOS does not benefit from this but it has received its own modest performance tweaks.

  • Long running KPM calculation now have a progress indicator and estimated completion time.


  • Added the and pb.load() convenience functions for getting result objects into/out of files. The data is saved in a compressed binary format (Python's builtin pickle format with protocol 4 and gzip). Loaded files can be immediately plotted: result = pb.load("file.pbz") and then result.plot() to see the data.

  • The eigenvalue solvers now have a calc_ldos method for computing the local density of states as a function of energy (in addition to the existing calc_spatial_ldos).

  • Improved plotting of Lattice objects. The view can now be rotated by passing the axis="xz" argument, or any other combination of x, y and z to define the plotting plane.

Deprecations and breaking changes

  • Added Lattice.add_aliases() method. The old Lattice.add_sublattice(..., alias=name) way of creating aliases is deprecated.

  • The greens module has been deprecated. This functionality is now covered by the KPM methods.

  • The internal storage format of the Lattice and System classes has been revised. This shouldn't affect most users who don't need access to the low-level data.

General improvements and bug fixes

  • StructureMap can now be sliced using a shape. E.g. s = pb.rectangle(5, 5); smap2 = smap[s] which returns a smaller structure map cut down to the given shape.

  • Plotting the structure of large or periodic systems is slightly faster now.

  • Added 2D periodic supercells to the "Shape and symmetry" section of the tutorial.

  • Added a few more examples to the "Plotting guide" (view rotation, separating sites and hoppings and composing multiple plots).

  • Fixed broken documentation links when using the online search function.

  • Fixed slow Hamiltonian build when hopping generators are used.

This work was supported by the Flemish Science Foundation (FWO-Vl) and the Methusalem Funding of the Flemish Government.
Files (632.5 kB)
Name Size
632.5 kB Download
All versions This version
Views 683362
Downloads 2314
Data volume 13.9 MB8.9 MB
Unique views 617328
Unique downloads 2014


Cite as