Exact diagonalization and quantum simulation testbeds

Quantum Lattice Models

A lightweight, package-first Python library for constructing, analyzing, plotting, and exporting small lattice Hamiltonians used in physics workflows and quantum algorithm research prototypes.

Read the Docs GitHub PyPI Portfolio

Implemented models

Small systems with explicit Hamiltonians

The package keeps model construction, spectra, observables, plotting, and export helpers in importable modules under src/quantum_lattice_models/.

Transverse-Field Ising Chain

Construct dense qubit-space matrices with nearest-neighbor ZZ coupling, transverse fields, longitudinal fields, and next-nearest-neighbor Ising variants.

Spin Chain Exact Diagonalization VQE Testbed

Heisenberg Ladder

Build two-leg spin ladders with independent leg and rung couplings for compact quasi-one-dimensional benchmarks.

Spin Ladder Rung Coupling Dense ED

Hubbard Chains

Use truncated Bose-Hubbard chains and spinful Fermi-Hubbard occupation-basis Hamiltonians for small interacting lattices.

Bose-Hubbard Fermi-Hubbard Occupation Basis

Anisotropic Heisenberg Chain

Build XX, YY, and ZZ coupled spin chains with optional longitudinal field terms.

Heisenberg Spin Physics Observables

XY and XXZ Chains

Use compact spin-chain builders for anisotropic exchange, transverse fields, and XXZ Heisenberg specializations.

XY XXZ Spin Gaps

J1-J2 Heisenberg Chain

Add next-nearest-neighbor Heisenberg interactions for a small frustrated spin-chain benchmark.

Frustration NNN Coupling Dense Pauli Terms

SSH Model

Study SSH, Rice-Mele, and Kitaev-chain single-particle or BdG matrices for compact topological-chain examples.

Topology Edge Modes BdG

Generic Tight-Binding Chain

Create one-dimensional single-particle hopping matrices with scalar or site-resolved onsite potentials.

Single Particle Spectra Quantum Walks

Topological and Frustrated Lattices

Build Harper-Hofstadter square lattices, Haldane honeycomb models, triangular lattices, kagome lattices, and AAH chains.

Hofstadter Haldane Kagome Quasiperiodic

Published package

Installable Python tooling

Runtime dependencies are intentionally small: numpy, scipy, and matplotlib. PennyLane export is optional.

Install from PyPI

Use the published package for examples, notebooks, and scripts.

pip install quantum-lattice-models PyPI

Install from source

Use editable mode when developing the package or running tests.

python -m pip install -e ".[dev]" Source

Optional PennyLane export

Convert dense Hamiltonians into PennyLane-compatible terms.

python -m pip install -e ".[pennylane]" Quickstart

Quickstart

Import the package API

from quantum_lattice_models.models import transverse_field_ising
from quantum_lattice_models.spectra import ground_energy, spectral_gap

H = transverse_field_ising(n_sites=4, j=1.0, h=0.5, periodic=False)

print(H.shape)
print(ground_energy(H))
print(spectral_gap(H))

Generated examples

Reference plots from command-line examples

Each script under examples/ imports the package and saves a PNG under images/, keeping notebooks and scripts as thin clients of the public API.

Transverse-field Ising spectrum plot — Transverse-field Ising spectrum

Heisenberg chain density plot — Heisenberg spectral density

SSH edge-state localization plot — SSH edge-state localization

Tight-binding spectrum plot — Tight-binding spectrum

Rice-Mele finite-chain spectrum plot — Rice-Mele spectrum

Harper-Hofstadter flux spectrum plot — Hofstadter flux spectrum

Truncated Bose-Hubbard spectrum plot — Bose-Hubbard spectrum

Finite Haldane honeycomb spectrum plot — Haldane spectrum

Kagome lattice graph connectivity plot — Kagome graph

Executed notebooks

Rendered notebook workflows

The notebooks are executed with saved outputs and exported to HTML under docs/notebooks/. They include printed spectra, parameter summaries, tables, and generated plots.

Spin-chain workflows

Ising variants and Heisenberg ladder spectra with gap sweeps.

notebooks/ising_spin_chains.ipynb HTML

Topological chains

SSH/Rice-Mele edge localization and Kitaev BdG particle-hole symmetry.

notebooks/kitaev_bdg_symmetry.ipynb HTML

Flux and lattice geometry

Hofstadter flux sweep plus Haldane, triangular, and kagome graphs.

notebooks/hofstadter_flux_sweep.ipynb HTML

Hubbard and sparse workflows

Dense/sparse exact diagonalization and sparse scaling summaries.

notebooks/hubbard_exact_diagonalization.ipynb HTML

Registry and CLI

Model registry table and command-line plot walkthrough.

notebooks/model_registry_and_cli.ipynb HTML

Notebook-generated Ising spectra — Ising notebook spectra

Notebook-generated Kitaev BdG spectrum — Kitaev BdG notebook

Notebook-generated Hofstadter flux sweep — Hofstadter notebook sweep

Notebook-generated sparse dense scaling summary — Sparse scaling notebook

Documentation and source

Read the project materials

The repository documents practical usage, model conventions, and the package's truth contract for small-system exact diagonalization. The notebook tree provides thin-client workflows for spin chains, SSH/Rice-Mele, Hofstadter sweeps, Hubbard models, and finite topological lattices.

Overview Usage Theory Results Notebooks