SUMMARY

This is a Python library to compute quantum-lattice tight-binding models in different dimensionalities.

INSTALLATION

With pip (release version)

pip install --upgrade pyqula

Manual installation (most recent version)

Clone the Github repository with

git clone https://github.com/joselado/pyqula

and add the "pyqula/src" path to your Python script with

import sys
sys.path.append(PATH_TO_PYQULA+"/src")

Recommended library versions

These are the recommended versions of several required libraries

• numpy 1.26.4
• numba 0.60.0
• scipy 1.13.1

Tutorials

Jupyter notebooks with tutorials can be found in the links below

From the "Advanced Quantum Materials course at Aalto University 2025"

• Electronic structure theory
• Topological band structure theory
• The Quantum Hall state
• Superconductivity and Majorana physics
• Interactions and magnetism
• Excitations and defects in quantum materials

From the Jyvaskyla Summer School 2022

• Electronic structure
• Superconductivity
• Magnetism
• Moire physics
• Topological matter

FUNCTIONALITIES

Single particle Hamiltonians

• Spinless, spinful and Nambu basis for orbitals
• Full non-collinear electron and Nambu formalism
• Include magnetism, spin-orbit coupling and superconductivity
• Band structures with state-resolved expectation values
• Momentum-resolved spectral functions
• Local and full operator-resolved density of states
• 0d, 1d, 2d and 3d tight binding models
• Electronic structure unfolding in supercells

Interacting mean-field Hamiltonians

• Selfconsistent mean-field calculations with local/non-local interactions
• Both collinear and non-collinear formalism
• Anomalous mean-field for non-collinear superconductors
• Full selfconsistency with all Wick terms for non-collinear superconductors
• Constrained and unconstrained mean-field calculations
• Automatic identification of order parameters for symmetry broken states
• Hermitian and non-Hermitian mean-field calculations
• Random phase approximation many-body response functions

Topological characterization

• Berry phases, Berry curvatures, Chern numbers and Z2 invariants
• Operator-resolved Chern numbers and Berry density
• Frequency resolved topological density
• Spatially resolved topological flux
• Real-space Chern density for amorphous systems
• Wilson loop and Green's function formalism

Spectral functions

• Spectral functions in infinite geometries
• Surface spectral functions for semi-infinite systems
• Interfacial spectral function in semi-infinite junctions
• Single impurities in infinite systems
• Green's function renormalization algorithm
• Operator and momentum resolved spectral functions

Chebyshev kernel polynomial based-algorithms

• Local and full spectral functions
• Non-local correlators and Green's functions
• Locally resolved expectation values
• Operator resolved spectral functions
• Reaching system sizes up to 10000000 atoms on a single-core laptop

Quantum transport

• Metal-metal transport
• Metal-superconductor transport
• Fully non-collinear Nambu basis
• Non-equilibrium Green's function formalism
• Operator-resolved transport
• Differential decay rate
• Tunneling and contact scanning probe spectroscopy

EXAMPLES

A variety of examples can be found in pyqula/examples. Short examples are shown below

Band structure of a Kagome lattice

from pyqula import geometry
g = geometry.kagome_lattice() # get the geometry object
h = g.get_hamiltonian() # get the Hamiltonian object
(k,e) = h.get_bands() # compute the band structure

Valley-resolved band structure of a honeycomb superlattice

from pyqula import geometry
g = geometry.honeycomb_lattice() # get the geometry object
g = g.get_supercell(7) # create a supercell
h = g.get_hamiltonian() # get the Hamiltonian object
(k,e,v) = h.get_bands(operator="valley") # compute the band structure

Interaction-driven spin-singlet superconductivity

from pyqula import geometry
import numpy as np
g = geometry.triangular_lattice() # geometry of a triangular lattice
h = g.get_hamiltonian()  # get the Hamiltonian
h.setup_nambu_spinor() # setup the Nambu form of the Hamiltonian
h = h.get_mean_field_hamiltonian(U=-1.0,filling=0.15,mf="swave") # perform SCF
# electron spectral-function
h.get_kdos_bands(operator="electron",nk=400,energies=np.linspace(-1.0,1.0,100))

Interaction driven non-unitary spin-triplet superconductor

import numpy as np
from pyqula import geometry
g = geometry.triangular_lattice() # generate the geometry
h = g.get_hamiltonian() # create Hamiltonian of the system
h.add_exchange([0.,0.,1.]) # add exchange field
h.setup_nambu_spinor() # initialize the Nambu basis
# perform a superconducting non-collinear mean-field calculation
h = h.get_mean_field_hamiltonian(V1=-1.0,filling=0.3,mf="random")
# compute the non-unitarity of the spin-triplet superconducting d-vector
d = h.get_dvector_non_unitarity() # non-unitarity of spin-triplet
# electron spectral-function
h.get_kdos_bands(operator="electron",nk=400,energies=np.linspace(-2.0,2.0,400))

Mean-field with local interactions of a zigzag honeycomb ribbon

from pyqula import geometry
g = geometry.honeycomb_zigzag_ribbon(10) # create geometry of a zigzag ribbon
h = g.get_hamiltonian() # create hamiltonian of the system
h = h.get_mean_field_hamiltonian(U=1.0,filling=0.5,mf="ferro")
(k,e,sz) = h.get_bands(operator="sz") # calculate band structure

Non-collinear mean-field with local interactions of a square lattice

from pyqula import geometry
g = geometry.square_lattice() # geometry of a square lattice
g = g.get_supercell([2,2]) # generate a 2x2 supercell
h = g.get_hamiltonian() # create hamiltonian of the system
h.add_zeeman([0.,0.,0.1]) # add out-of-plane Zeeman field
h = h.get_mean_field_hamiltonian(U=2.0,filling=0.5,mf="random") # perform SCF
(k,e,c) = h.get_bands(operator="sz") # calculate band structure
m = h.get_magnetization() # get the magnetization

Interaction-induced non-collinear magnetism in a defective square lattice with spin-orbit coupling

from pyqula import geometry
g = geometry.square_lattice() # geometry of a square lattice
g = g.get_supercell([7,7]) # generate a 7x7 supercell
g = g.remove(i=g.get_central()[0]) # remove the central site
h = g.get_hamiltonian() # create hamiltonian of the system
h.add_rashba(.4) # add Rashba spin-orbit coupling
h = h.get_mean_field_hamiltonian(U=2.0,filling=0.5,mf="random") # perform SCF
(k,e,c) = h.get_bands(operator="sz") # calculate band structure
m = h.get_magnetization() # get the magnetization

RPA many-body response function in an antiferromagnet

from pyqula import geometry ; import numpy as np
g = geometry.bisquare_ribbon(2) # square bipartite ribbon
h = g.get_hamiltonian() # generate Hamiltonian
h = h.get_mean_field_hamiltonian(U=3.,mf="antiferro",filling=0.5) # perform SCF
qs = np.linspace(0.,.5,50) # qvectors
energies=np.linspace(.0,1.6,400) # energies

chimap = [] # storage for the results
for q in qs: # loop over qvectors
    es,chis = h.get_spinchi_ladder(q=q,energies=energies) # compute RPA tensor
    cs = [np.trace(c).imag for c in chis] # imaginary part of the trace
    chimap.append(cs) # store 

RPA many-body response function in a ferromagnet

from pyqula import geometry ; import numpy as np
g = geometry.lieb_ribbon(2) # Lieb lattice ribbon
h = g.get_hamiltonian() # generate Hamiltonian
h = h.get_mean_field_hamiltonian(U=3.,mf="ferro",filling=0.5) # perform SCF
qs = np.linspace(0.,.5,50) # qvectors
energies=np.linspace(.0,1.,400) # energies

chimap = [] # storage for the results
for q in qs: # loop over qvectors
    es,chis = h.get_spinchi_ladder(