Model Registry and CLI Workflows

Model. This notebook uses the model registry rather than focusing on one Hamiltonian. The registry summarizes available builders, categories, basis conventions, dimension scaling, return types, default parameters, and short descriptions.

Typical uses. Programmatic model discovery, documentation tables, quick CLI checks, and choosing an appropriate small-system testbed.

Parameters. Registry rows expose name, category, basis, dimension, return_type, description, and defaults. The CLI accepts model-specific options such as --n-sites, --n-cells, --n-rows, --n-cols, --hopping, and --flux.

Useful plots. Use registry-selected builders with plot_lattice_spectrum; use CLI plot for quick PNG output.

from quantum_lattice_models.registry import get_model_info, list_models, model_table

print("Registered models")
print("category      | model")
print("---           | ---")
for name in list_models():
    info = get_model_info(name)
    print(f"{info.category:<13s} | {name}")

info = get_model_info("ssh_model")
print("\nSSH model metadata")
print(f"  basis:       {info.basis}")
print(f"  dimension:   {info.dimension}")
print(f"  return type: {info.return_type}")
print(f"  defaults:    {info.defaults}")

Registered models
category      | model
---           | ---
tight_binding | aubry_andre_harper_chain
hubbard       | bose_hubbard_chain
hubbard       | bose_hubbard_chain_sparse
hubbard       | fermi_hubbard_chain
hubbard       | fermi_hubbard_chain_sparse
topological   | haldane_honeycomb_lattice
topological   | haldane_honeycomb_lattice_sparse
topological   | harper_hofstadter_square_lattice
topological   | harper_hofstadter_square_lattice_sparse
spin          | heisenberg_chain
spin          | heisenberg_ladder
spin          | j1_j2_heisenberg_chain
tight_binding | kagome_lattice_tight_binding
tight_binding | kagome_lattice_tight_binding_sparse
topological   | kitaev_chain_bdg
spin          | longitudinal_field_ising
spin          | next_nearest_neighbor_ising
tight_binding | rice_mele_model
tight_binding | square_lattice_tight_binding
tight_binding | square_lattice_tight_binding_sparse
tight_binding | ssh_model
tight_binding | tight_binding_chain
tight_binding | tight_binding_chain_sparse
spin          | transverse_field_ising
tight_binding | triangular_lattice_tight_binding
tight_binding | triangular_lattice_tight_binding_sparse
spin          | xxz_chain
spin          | xy_chain

SSH model metadata
  basis:       single particle
  dimension:   2*n_cells
  return type: LatticeHamiltonian
  defaults:    {'n_cells': 8, 't1': 0.5, 't2': 1.0}

rows = model_table()
headers = ["name", "category", "basis", "dimension", "return_type"]
print(" | ".join(headers))
print(" | ".join(["---"] * len(headers)))
for row in rows:
    print(" | ".join(str(row[key]) for key in headers))

name | category | basis | dimension | return_type
--- | --- | --- | --- | ---
transverse_field_ising | spin | qubit | 2**n_sites | DenseHamiltonian
longitudinal_field_ising | spin | qubit | 2**n_sites | DenseHamiltonian
next_nearest_neighbor_ising | spin | qubit | 2**n_sites | DenseHamiltonian
heisenberg_chain | spin | qubit | 2**n_sites | DenseHamiltonian
xy_chain | spin | qubit | 2**n_sites | DenseHamiltonian
xxz_chain | spin | qubit | 2**n_sites | DenseHamiltonian
j1_j2_heisenberg_chain | spin | qubit | 2**n_sites | DenseHamiltonian
heisenberg_ladder | spin | qubit | 2**(2*n_rungs) | DenseHamiltonian
bose_hubbard_chain | hubbard | truncated boson occupation | (max_occupancy+1)**n_sites | LatticeHamiltonian
bose_hubbard_chain_sparse | hubbard | truncated boson occupation | (max_occupancy+1)**n_sites | scipy.sparse.csr_matrix
fermi_hubbard_chain | hubbard | spinful fermion occupation | 2**(2*n_sites) | LatticeHamiltonian
fermi_hubbard_chain_sparse | hubbard | spinful fermion occupation | 2**(2*n_sites) | scipy.sparse.csr_matrix
ssh_model | tight_binding | single particle | 2*n_cells | LatticeHamiltonian
rice_mele_model | tight_binding | single particle | 2*n_cells | LatticeHamiltonian
tight_binding_chain | tight_binding | single particle | n_sites | LatticeHamiltonian
tight_binding_chain_sparse | tight_binding | single particle | n_sites | scipy.sparse.csr_matrix
square_lattice_tight_binding | tight_binding | single particle | n_rows*n_cols | LatticeHamiltonian
square_lattice_tight_binding_sparse | tight_binding | single particle | n_rows*n_cols | scipy.sparse.csr_matrix
aubry_andre_harper_chain | tight_binding | single particle | n_sites | LatticeHamiltonian
triangular_lattice_tight_binding | tight_binding | single particle | n_rows*n_cols | LatticeHamiltonian
triangular_lattice_tight_binding_sparse | tight_binding | single particle | n_rows*n_cols | scipy.sparse.csr_matrix
kagome_lattice_tight_binding | tight_binding | single particle | 3*n_rows*n_cols | LatticeHamiltonian
kagome_lattice_tight_binding_sparse | tight_binding | single particle | 3*n_rows*n_cols | scipy.sparse.csr_matrix
harper_hofstadter_square_lattice | topological | single particle | n_rows*n_cols | LatticeHamiltonian
harper_hofstadter_square_lattice_sparse | topological | single particle | n_rows*n_cols | scipy.sparse.csr_matrix
kitaev_chain_bdg | topological | Nambu single particle | 2*n_sites | LatticeHamiltonian
haldane_honeycomb_lattice | topological | single particle | 2*n_rows*n_cols | LatticeHamiltonian
haldane_honeycomb_lattice_sparse | topological | single particle | 2*n_rows*n_cols | scipy.sparse.csr_matrix

CLI examples to run in a terminal after installing the package:

quantum-lattice models
quantum-lattice spectrum --model ssh_model --n-cells 8
quantum-lattice plot --model harper_hofstadter_square_lattice --n-rows 4 --n-cols 4 --flux 0.25 --output images/hofstadter_cli.png