Quantum Lattice Models

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 outputs from command-line examples

Each script under examples/ imports the package and produces a focused figure or portable artifact, keeping notebooks and scripts as thin clients of the public API.

Spin, fermionic-mode, and graph-spin interaction diagrams — Physical-system interaction graphs

Heisenberg chain density plot — Heisenberg density: n=5, J=1.0, field=0.2

SSH edge-state localization plot — SSH edge state: 12 cells, t₁=0.4, t₂=1.0

Imported external matrix magnitude and phase — External matrix import and inspection

Harper-Hofstadter flux spectrum plot — Finite Hofstadter spectrum: 8×8, 121 flux values

Kagome lattice graph connectivity plot — Kagome: 2×3 cells with sublattice colors

Haldane Hamiltonian magnitude and phase matrices — Haldane matrix magnitude and hopping phase

Model reference

Equations, conventions, variables, and package use

Each model family has a concise reference page covering its structure, Hamiltonian, basis, scaling, generated parameter table, Python and CLI use, validation status, and computational cautions. Shared foundations remain in the general theory guide.

General theory and conventions

Shared bases, Pauli normalization, hopping signs, boundaries, sparse matrices, and exact diagonalization.

THEORY.md Theory

Complete model index

Spin, Hubbard, tight-binding, topological, and custom-lattice model references.

docs/models/ Browse models

Scientific validation matrix

Analytic limits, symmetry checks, dense/sparse comparisons, and associated tests.

VALIDATION.md Validation

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. The numeric prefixes define the recommended learning order.

01. Ising spin chains

TFIM, longitudinal, and next-nearest-neighbor spectra.

notebooks/01_ising_spin_chains.ipynb HTML

02. Spin observables

Magnetization, correlations, and finite-size gap sweeps.

notebooks/02_spin_observables_and_correlations.ipynb HTML

03. Spin-model comparison

XY, XXZ, and J1-J2 spectra and parameter sweeps.

notebooks/03_spin_chain_model_comparison.ipynb HTML

04. Heisenberg ladder

Ladder spectrum, density of states, and rung-coupling gap.

notebooks/04_heisenberg_ladder_spectrum.ipynb HTML

05. Hubbard exact diagonalization

Bose/Fermi dense and sparse low-energy workflows.

notebooks/05_hubbard_exact_diagonalization.ipynb HTML

06. SSH and Rice-Mele

Finite spectra and near-zero edge localization.

notebooks/06_ssh_rice_mele_comparison.ipynb HTML

07. Boundaries and finite size

Open/periodic SSH states and TFIM size scaling.

notebooks/07_boundary_conditions_and_finite_size.ipynb HTML

08. Aubry-André localization

IPR crossover and representative localized states.

notebooks/08_aubry_andre_localization.ipynb HTML

09. Kitaev BdG symmetry

Particle-hole pairing and chemical-potential gap sweep.

notebooks/09_kitaev_bdg_symmetry.ipynb HTML

10. Hofstadter flux sweep

Fixed-flux geometry and finite-lattice butterfly.

notebooks/10_hofstadter_flux_sweep.ipynb HTML

11. Haldane, triangular, and kagome

Two-dimensional spectra and lattice connectivity.

notebooks/11_haldane_kagome_lattices.ipynb HTML

12. Custom lattice workflow

Complex bonds, dense/sparse agreement, and registration.

notebooks/12_custom_lattice_workflow.ipynb HTML

13. Hamiltonian structure gallery

Magnitude patterns and complex hopping phases.

notebooks/13_hamiltonian_structure_gallery.ipynb HTML

14. Sparse and dense scaling

Matrix density, storage reduction, and solver agreement.

notebooks/14_sparse_dense_scaling.ipynb HTML

15. PennyLane export

Pauli-term conversion and matrix-level validation.

notebooks/15_pennylane_export.ipynb HTML

16. Registry, portable files, and CLI workflows

Model discovery, portable specifications, spectra, plots, and artifact bundles.

notebooks/16_model_registry_and_cli.ipynb HTML

17. Portable physical-system records

Local degrees, basis mappings, interactions, and diagrams.

notebooks/17_portable_physical_system_records.ipynb HTML

18. Model import, export, and bundles

JSON lifecycle, external matrices, and deterministic artifacts.

notebooks/18_model_import_export_and_bundles.ipynb HTML

19. Graph-spin model workflow

Mixed-axis interactions, fields, sparse reconstruction, and observables.

notebooks/19_graph_spin_model_workflow.ipynb HTML

20. Fixed-magnetization spin sectors

Reduced dimensions, block validation, observables, and entanglement.

notebooks/20_fixed_magnetization_spin_sectors.ipynb HTML

21. Lattice import and transformations

CSV interchange, defects, boundaries, disorder, and provenance.

notebooks/21_lattice_import_and_transformations.ipynb HTML

22. Portable model intake workflow

Creation, description, linting, transformation, round-trip reconstruction, and export.

notebooks/22_model_intake_workflow.ipynb HTML

Notebook-generated Ising spectra — Ising notebook spectra

Notebook-generated spin observable sweep — Spin observables and correlations

Notebook-generated Aubry-Andre localization sweep — Aubry-André localization

Notebook-generated Hamiltonian structure gallery — Hamiltonian structure gallery

Notebook-generated physical-system interaction diagrams — Portable physical-system records

Notebook-generated sector dimension scaling — Fixed-magnetization sectors

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, portable physical data, graph-spin systems, reduced sectors, interchange, and finite topological lattices.

Overview Usage Theory Model Reference Capabilities Public API Results Notebooks