quantum-lattice-models 0.1.5

Small dense quantum lattice Hamiltonians for exact diagonalization and quantum algorithm prototypes.

Quantum Lattice Models

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

Its core scope is model and lattice data: creation or import, validation, construction, metadata preservation, and interchange. Lightweight spectra, observables, entanglement, dynamics, topology, and plotting tools are included when they help users inspect or validate those models; specialized large-scale simulation and workflow execution remain the responsibility of external packages.

PyPI: https://pypi.org/project/quantum-lattice-models/

Website: https://sidrichardsquantum.github.io/Quantum_Lattice_Models/

This repository is organized as an installable package first. The real logic lives in src/quantum_lattice_models/; notebooks, scripts, and examples should stay thin and import the public package API. The top-level quantum_lattice_models API imports directly from focused modules such as spin, tight_binding, hubbard, and topological. quantum_lattice_models.models remains available as a backwards-compatible re-export surface.

Implemented Models

• Transverse-field Ising spin chain
• Longitudinal-field Ising spin chain
• Next-nearest-neighbor Ising spin chain
• Anisotropic Heisenberg spin chain
• XY spin chain
• XXZ spin chain
• Frustrated J1-J2 Heisenberg spin chain
• Two-leg Heisenberg spin ladder
• Truncated Bose-Hubbard chain
• Spinful Fermi-Hubbard chain
• Kitaev-chain Bogoliubov-de Gennes matrix
• Su-Schrieffer-Heeger single-particle tight-binding model
• Rice-Mele single-particle chain
• Generic one-dimensional single-particle tight-binding chain
• Square-lattice single-particle tight-binding model
• Harper-Hofstadter square-lattice model
• Aubry-Andre-Harper quasiperiodic tight-binding chain
• Haldane honeycomb-lattice model
• Triangular-lattice single-particle tight-binding model
• Kagome-lattice single-particle tight-binding model
• User-defined graph/lattice tight-binding models

Spin-chain Hamiltonians are dense qubit-space matrices Tight-binding Hamiltonians are single-particle matrices. This distinction is intentional and explicit. Sparse lattice builders assemble CSR matrices directly; matching dense builders reuse the same construction path to keep both representations consistent.

Versioned ModelSpec and LatticeSpec objects provide portable model parameters and finite-lattice geometry. Specifications can be saved as JSON, validated in a new process, and rebuilt as dense or sparse Hamiltonians. HamiltonianResult keeps the matrix associated with its model, basis, representation, and construction metadata without relying on NumPy subclass attributes.

Model files can be analyzed and exported directly:

quantum-lattice spectrum ssh.json
quantum-lattice export ssh.json --format npz --output ssh-hamiltonian.npz

Models can be filtered and inspected before allocating a matrix:

quantum-lattice models --category spin --sparse --json
quantum-lattice presets --model ssh_model
quantum-lattice dry-run --preset ssh_topological --n-cells 20 --json
quantum-lattice compare trivial.json topological.json --json

Named presets remain ordinary, transparent model specifications:

from quantum_lattice_models import (
    compare_models,
    create_model_from_preset,
    inspect_model,
)

topological = create_model_from_preset("ssh_topological")
trivial = create_model_from_preset("ssh_trivial")
report = inspect_model("transverse_field_ising", n_sites=12)
comparison = compare_models(topological, trivial)

NPZ exports are self-contained and preserve metadata for dense and CSR sparse matrices. NPY exports support dense matrices and write a matching .npy.json metadata sidecar.

Spin models now share a graph-based sparse construction backend. Existing dense builders retain their return types, while matching sparse builders are available with a _sparse suffix. Arbitrary spin graphs can use SpinInteraction, SpinField, and graph_spin_hamiltonian_sparse.

XXZ and Heisenberg chains with equal $XX$ and $YY$ couplings can also be built directly in a fixed total Pauli-$Z$ magnetization sector:

from quantum_lattice_models import xxz_chain_sector

sector = xxz_chain_sector(n_sites=12, magnetization=0, anisotropy=0.8)
H = sector.matrix
print(sector.basis.dimension)

Spin observables and entanglement routines work with both full and fixed-magnetization state vectors without requiring reduced states to be expanded:

from quantum_lattice_models import (
    bipartite_entanglement_entropy,
    site_magnetization_z,
    spin_correlation_matrix,
)
from quantum_lattice_models.spectra import ground_state

_, state = ground_state(H)
magnetization = site_magnetization_z(state, 12, basis=sector.basis)
correlations = spin_correlation_matrix(state, 12, basis=sector.basis, connected=True)
entropy = bipartite_entanglement_entropy(
    state, 12, subsystem=range(6), basis=sector.basis
)

Why Lattice Models Matter

Small lattice Hamiltonians are useful because they are concrete, inspectable testbeds. They connect physics intuition to numerical linear algebra, and they give quantum algorithm researchers controlled problems for VQE, QPE, QSVT, spectral transforms, quantum walks, and simulation workflows.

This package does not claim quantum advantage. It provides honest small-system tools for exact diagonalization, prototyping, teaching, and notebook-first experiments.

Installation

From a local checkout:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Minimal runtime dependencies are numpy, scipy, and matplotlib.

PennyLane export is optional:

pip install -e ".[pennylane]"

Notebook support is optional:

python -m pip install -e ".[notebooks]"
python -m ipykernel install --user --name quantum-lattice-models --display-name "Quantum Lattice Models"

Quickstart

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

from quantum_lattice_models.models import ssh_model, ssh_edge_state_localizations
from quantum_lattice_models.spectra import eigensystem

H = ssh_model(n_cells=8, t1=0.5, t2=1.0, periodic=False)
values, vectors = eigensystem(H)
weights = ssh_edge_state_localizations(vectors, n_cells=8, edge_cells=2)

User-Defined Lattices

Users can build custom single-particle tight-binding models without adding a new function to the package:

from quantum_lattice_models import Lattice, TightBindingModel

lattice = Lattice(
    positions=[(0.0, 0.0), (1.0, 0.0), (0.5, 0.8)],
    bonds=[(0, 1), (1, 2, 0.25j), (2, 0)],
)

H = TightBindingModel(lattice).hamiltonian(hopping=1.0, onsite=[0.0, 0.1, 0.0])

Two-item bonds use -hopping as the matrix element. Three-item bonds use the third value directly, which allows complex hoppings and Peierls phases.

Custom builders can also be registered for discovery in notebooks and the CLI:

from quantum_lattice_models.registry import register_model

register_model(
    "my_model",
    category="user",
    basis="single particle",
    dimension="n_sites",
    return_type="LatticeHamiltonian",
    description="My custom tight-binding model",
    builder=my_builder,
    defaults={"n_sites": 4},
)

The plotting helpers can use lattice position metadata directly:

from quantum_lattice_models.plotting import plot_lattice_graph, plot_lattice_state
from quantum_lattice_models.spectra import eigensystem

plot_lattice_graph(H, show_colorbar=True)
values, vectors = eigensystem(H)
plot_lattice_state(H, vectors[:, 0])

Repository Structure

src/quantum_lattice_models/  Package source
tests/                       Pytest test suite
examples/                    Command-line examples that save plots
notebooks/                   Thin-client exploratory notebooks
README.md                    Project overview
CHANGELOG.md                 Release notes
ROADMAP.md                   Planned capabilities and engineering priorities
VALIDATION.md                Scientific reference checks and diagnostics
USAGE.md                     API examples
THEORY.md                    Shared theory, basis, and numerical conventions
docs/models/                 Per-model Markdown references and generated HTML
RESULTS.md                   Generated results
SCHEMA.md                    Portable schema and compatibility policy
IMPORTING.md                 CSV, GraphML, and transformation workflow

Future capabilities and their recommended implementation order are documented in ROADMAP.md. Portable fields and compatibility guarantees are documented in SCHEMA.md, with import and transformation examples in IMPORTING.md. Implemented analytic checks and the model-validation matrix are documented in VALIDATION.md. Concise equations, variables, examples, and cautions for each model family are available in the model reference.

Key package modules:

spin.py                      Dense spin-chain and ladder builders
tight_binding.py             Single-particle tight-binding builders
hubbard.py                   Bose-Hubbard and Fermi-Hubbard builders
topological.py               Haldane, Hofstadter, and Kitaev builders
geometry.py                  Coordinate helpers for plotting
lattice.py                   User-defined lattice containers and custom builders
interchange.py               CSV, NetworkX, and GraphML adapters
transformations.py           Immutable lattice transformations
diagnostics.py               Matrix and pre-build resource diagnostics
comparison.py                Model parameter, matrix, spectrum, and gap comparison
registry.py                  Structured model metadata
specs.py                     Versioned portable model and lattice specifications
storage.py                   Metadata-preserving NPY and NPZ persistence
cli.py                       quantum-lattice command-line entry point
models.py                    Backwards-compatible re-export layer

Notebooks as Thin Clients

Notebooks should import from quantum_lattice_models rather than defining their own model logic. A notebook can choose parameters, run spectra, plot results, and tell a story. The package should remain the source of truth.

Current notebooks, numbered in the recommended learning order:

• notebooks/01_ising_spin_chains.ipynb
• notebooks/02_spin_observables_and_correlations.ipynb
• notebooks/03_spin_chain_model_comparison.ipynb
• notebooks/04_heisenberg_ladder_spectrum.ipynb
• notebooks/05_hubbard_exact_diagonalization.ipynb
• notebooks/06_ssh_rice_mele_comparison.ipynb
• notebooks/07_boundary_conditions_and_finite_size.ipynb
• notebooks/08_aubry_andre_localization.ipynb
• notebooks/09_kitaev_bdg_symmetry.ipynb
• notebooks/10_hofstadter_flux_sweep.ipynb
• notebooks/11_haldane_kagome_lattices.ipynb
• notebooks/12_custom_lattice_workflow.ipynb
• notebooks/13_hamiltonian_structure_gallery.ipynb
• notebooks/14_sparse_dense_scaling.ipynb
• notebooks/15_pennylane_export.ipynb
• notebooks/16_model_registry_and_cli.ipynb
• notebooks/17_cli_plot_walkthrough.ipynb

Development

Use the virtual environment for examples, notebooks, tests, and packaging commands. The standard local checks are:

make format
make lint
make test

The Makefile runs Black one file at a time to avoid multi-file formatter stalls observed in some Codespace environments. Before a release, also run Ruff across the full repository so notebook code cells are checked:

python -m ruff check .
python -m pytest -q

Install .[pennylane] before the test command to exercise the optional PennyLane export test instead of skipping it.

Publishing a release

Pushing a tag such as v0.1.3 runs .github/workflows/publish.yml. The workflow verifies that the tag matches the version in pyproject.toml, runs the release checks, builds the wheel and source distribution, and publishes them to PyPI.

Configure a PyPI Trusted Publisher for this repository before pushing the first release tag:

• Owner: SidRichardsQuantum
• Repository: Quantum_Lattice_Models
• Workflow filename: publish.yml
• Environment name: pypi

No PyPI API token is required. The GitHub pypi environment can optionally require manual approval before publication.

Limitations / Truth Contract

• Dense spin-chain matrices have dimension $2^{N}\times2^{N}$ for $N$ sites.
• These tools are for small systems, education, exact diagonalization, and research prototypes.
• SSH, Rice-Mele, square, Harper-Hofstadter, Haldane, triangular, kagome, and generic tight-binding builders return single-particle matrices, not many-body Fock-space Hamiltonians.
• The Bose-Hubbard builder uses a truncated local occupation basis.
• The Fermi-Hubbard builder uses a dense occupation-number basis with explicit fermionic signs.
• The Kitaev-chain builder returns a Bogoliubov-de Gennes matrix, not a many-body Hamiltonian.
• Sparse builders are available for selected tight-binding and Hubbard chains, but exact diagonalization remains a small-system workflow.
• PennyLane is optional and only used when explicitly installed.
• The project is a backend for experiments, not a benchmark suite proving speedup or quantum advantage.

---

Support development

If this repository is useful for research, learning, or experimentation, you can support continued development via GitHub Sponsors:

https://github.com/sponsors/SidRichardsQuantum

Sponsorship helps support ongoing work on open-source implementations of quantum algorithms, including improvements to documentation, reproducible workflows, and example notebooks.

Support helps maintain and expand practical tooling for variational quantum methods, quantum simulation workflows, and related experimentation.

Citation

Sid Richards (2026)

Unified Variational and Phase-Estimation Quantum Simulation Suite

Author

Sid Richards

• LinkedIn: sid-richards-21374b30b
• GitHub: SidRichardsQuantum

License

MIT. See LICENSE.