Fermi–Hubbard Utilities
Fermi–Hubbard utilities support Jordan–Wigner Pauli expansions for one-dimensional open chains, mode mappings, dense exact diagonalization, and finite-shot total-magnetic-moment measurements from state-preparation circuits. A chain of length uses qubits.
Constructing a Pauli Hamiltonian
from unitarylab.library.fermi_hubbard.fermi_hubbard_pauli import (
fermi_hubbard_pauli_terms,
fermi_hubbard_pauli,
qubit_site_spin_mapping,
)
terms = fermi_hubbard_pauli_terms(L=2, t=1.0, U=2.0, B=0.1)
expression = fermi_hubbard_pauli(L=2, t=1.0, U=2.0, B=0.1)
print(qubit_site_spin_mapping(2))
print(terms)
print(expression)| Interface | Return value |
|---|---|
fermi_hubbard_pauli_terms(L, t, U, B) | Merged Pauli terms as dict[str, float] |
fermi_hubbard_pauli(L, t, U, B) | Pauli-expression string for downstream tools |
fermi_hubbard_hamiltonian(L, t, U, B) | Hamiltonian-expression string |
qubit_site_spin_mapping(L) | Readable mapping of lattice sites, spins, and qubits |
Modes use an interleaved, site-first order: the spin-up mode at site maps to qubit , and the spin-down mode maps to qubit . L must be a positive integer; t, U, and B must be finite real numbers.
Exact ground state and total spin
from unitarylab.library.fermi_hubbard.pauli_ground_state import pauli_ground_state
ground = pauli_ground_state(expression, max_qubits=8)
print(ground.energy)
print(ground.lowest_energies)
print(ground.magnetic_moment)pauli_ground_state(pauli_expression, *, max_qubits=12) returns GroundStateInfo:
| Field | Description |
|---|---|
energy | Selected ground-state energy |
lowest_energies | Three lowest eigenvalues |
state | Normalized ground-state vector |
magnetic_moment | Exact expectations |
number_of_qubits | Pauli-string width |
The same module provides parse_pauli_expression(), pauli_string_to_matrix(), its alias pauli_expression_to_matrix(), and total_spin_operators(). Pauli expressions require equal-length strings, finite real coefficients, Hermitian operators, and an even number of qubits.
Exact diagonalization stores a dense matrix and has space complexity approximately . max_qubits is a guard threshold; it does not mean larger systems are suitable for dense solution.
Finite-shot magnetic-moment measurement
from unitarylab import Circuit
from unitarylab.library.fermi_hubbard.measure import measure_circuit_magnetic_moment
state_preparation = Circuit(4)
measurement = measure_circuit_magnetic_moment(state_preparation, shots=1000)
print(measurement.magnetic_moment)
print(measurement.standard_errors)
print(measurement.total_shots)The interface uses five measurement settings: XX, YY, XY, YX, and Z. The input must be an even-qubit state-preparation circuit without measurement gates, and shots must be at least 2. MagneticMomentMeasurement contains mx, my, mz, standard_errors, shots_per_setting, number_of_sites, number_of_settings, statevector_reference, statevector_validation_passed, and measurement timing. .magnetic_moment and .total_shots provide summaries.
measure_ground_state_magnetic_moment(filename, shots=...) loads a Python circuit file before measuring. Loading executes the Python code in the file; use only reviewed files from trusted sources. Do not load downloaded or user-uploaded files.