CLI Plot Walkthrough

Model. This notebook demonstrates the quantum-lattice command-line interface. The CLI builds package models, prints spectra, and saves spectrum plots.

Typical uses. Quick smoke tests, reproducible command-line figures, simple generated artifacts for docs, and examples that do not require writing a Python script.

Parameters. --model selects a registered builder. Common options include --n-sites, --n-cells, --n-rows, --n-cols, --hopping, --flux, and --output.

Useful plots. CLI-generated PNG spectra saved under results/notebooks/ or images/.

import subprocess
import sys
from pathlib import Path

output_dir = Path("results/notebooks")
output_dir.mkdir(parents=True, exist_ok=True)

models = subprocess.run(
    [sys.executable, "-m", "quantum_lattice_models.cli", "models"],
    check=True,
    capture_output=True,
    text=True,
)
print("First registry lines:")
print(chr(10).join(models.stdout.splitlines()[:8]))

First registry lines:
aubry_andre_harper_chain	tight_binding	n_sites	Aubry-Andre-Harper quasiperiodic chain
bose_hubbard_chain	hubbard	(max_occupancy+1)**n_sites	Truncated Bose-Hubbard chain
bose_hubbard_chain_sparse	hubbard	(max_occupancy+1)**n_sites	Sparse truncated Bose-Hubbard chain
fermi_hubbard_chain	hubbard	2**(2*n_sites)	Spinful Fermi-Hubbard chain
fermi_hubbard_chain_sparse	hubbard	2**(2*n_sites)	Sparse spinful Fermi-Hubbard chain
haldane_honeycomb_lattice	topological	2*n_rows*n_cols	Finite Haldane honeycomb lattice
haldane_honeycomb_lattice_sparse	topological	2*n_rows*n_cols	Sparse finite Haldane honeycomb lattice
harper_hofstadter_square_lattice	topological	n_rows*n_cols	Harper-Hofstadter square lattice

spectrum = subprocess.run(
    [
        sys.executable,
        "-m",
        "quantum_lattice_models.cli",
        "spectrum",
        "--model",
        "ssh_model",
        "--n-cells",
        "4",
    ],
    check=True,
    capture_output=True,
    text=True,
)
energies = [float(line) for line in spectrum.stdout.splitlines() if line.strip()]
print("SSH spectrum from CLI")
print("index | energy")
print("--- | ---")
for index, energy in enumerate(energies):
    print(f"{index:>5d} | {energy: .6f}")

SSH spectrum from CLI
index | energy
--- | ---
    0 | -1.413419
    1 | -1.166123
    2 | -0.800098
    3 | -0.047394
    4 |  0.047394
    5 |  0.800098
    6 |  1.166123
    7 |  1.413419

plot_path = output_dir / "cli_hofstadter_spectrum.png"
plot = subprocess.run(
    [
        sys.executable,
        "-m",
        "quantum_lattice_models.cli",
        "plot",
        "--model",
        "harper_hofstadter_square_lattice",
        "--n-rows",
        "4",
        "--n-cols",
        "4",
        "--flux",
        "0.25",
        "--output",
        str(plot_path),
    ],
    check=True,
    capture_output=True,
    text=True,
)
print(plot.stdout.strip())
print("exists:", plot_path.exists())

results/notebooks/cli_hofstadter_spectrum.png
exists: True