Circuit library (qlb_port)
qlb_port — port Quantum Lattice Boltzmann (QLB) operators to emulated quantum circuits.
A small, self-contained toolkit for compiling the unit operators of the QLB Dirac solver into gate circuits and verifying them against their classical matrices on a qiskit-aer (GPU) backend.
Layout
- operators.pythe QLB unit operators as NumPy matrices (single source of truth,
kept consistent with
dirac_qlb_solvervia a test).- backend.pyqiskit-aer helpers (GPU-first) — circuit unitary, statevector apply,
fidelity metrics.
- port.pythe general “unitary -> verified circuit” harness plus convenience
builders for the QLB rotation and collision operators.
- streaming.pythe QLB +/-1 lattice shift as a controlled increment/decrement on a
position register.
sweep.py : assemble rotation + collision + streaming into a full 1D sub-step. potential.py : position-dependent potential (impurity scattering) as a phase oracle
(massless) or a position-multiplexed collision (massive).
- twod.pycompose x- and y-sweeps on two position registers (2D graphene,
including oblique-incidence Klein tunneling through a barrier).
- threed.pycompose x-, y-, z-sweeps on three position registers (3D Dirac,
free propagation and planar-barrier Klein tunneling).
test_port.py : validation — every ported operator must match its target to ~1e-9.
Environment
Requires the HPC module qiskit/aer-gpu (qiskit-aer-gpu). Load it with:
module load qiskit/aer-gpu
Quick start
from qlb_port import operators as ops from qlb_port.port import port_and_verify
r = port_and_verify(ops.X_ROTATION, label=”x-rotation”) print(r[“fidelity”], r[“cx”], r[“depth”])
Operators
The QLB unit operators as NumPy matrices: the Dirac / Pauli matrices, the fixed rotations, the collision, and the classical streaming permutation used as a reference.
QLB unit operators as NumPy matrices (single source of truth for the porting layer).
The QLB Dirac time step is a sequence of per-axis sub-steps, each of the form
rotate (R^-1) -> collide (Q_hat) -> stream (+/-1 shift) -> rotate back (R)
acting on a 4-component spinor (= 2 qubits). The portable, gate-level unit operators are therefore small and exact:
ROTATIONS R in {X, Z} — fixed 2-qubit unitaries (Y = I).
COLLISION Q_hat(m,g) — a parameterized 2-qubit unitary, a_hat I - i b_hat ALPHA_Y.
- STREAMING — a per-component +/-1 lattice shift (position-register
operator; handled in a later module).
These definitions match dirac_qlb_solver exactly (see test_port.py::test_consistency).
Representation (Dellar 2011): the spatial streaming matrices are {ALPHA_X, BETA, ALPHA_Z}
and the mass/collision term acts along ALPHA_Y; these four form a mutually anticommuting
Dirac set. The x-rotation X = S @ Z, with S = exp(-i (pi/4) Sigma_y) the spinor rotation
mapping the z streaming axis onto x, diagonalizes ALPHA_X and preserves the collision
structure (X^-1 Q_hat X = Q).
- qlb_port.operators.streaming_signs(axis)[source]
Per-spinor-component lattice shift (+/-1) for a sweep along axis.
- qlb_port.operators.collision_coefficients(m_tilde, g_tilde=0.0)[source]
Return the QLB collision coefficients (a_hat, b_hat).
Omega = m_tilde^2 - g_tilde^2 D = 1 + Omega/4 - i g_tilde a_hat = (1 - Omega/4) / D (diagonal / phase factor) b_hat = m_tilde / D (mass coupling; 0 for massless)
They satisfy |a_hat|^2 + |b_hat|^2 = 1, so the collision is unitary. Here m_tilde and g_tilde are the (already per-sweep-rescaled) dimensionless mass and potential couplings.
- qlb_port.operators.collision_operator(m_tilde, g_tilde=0.0)[source]
Standard-frame collision unitary Q_hat = a_hat I - i b_hat ALPHA_Y.
This is the operator applied on the spinor (2 qubits) for a site with the given local mass and potential couplings. In the characteristic frame of a sweep it becomes a_hat I - i b_hat (R^-1 ALPHA_Y R) (see collision_operator_char).
- qlb_port.operators.collision_operator_char(axis, m_tilde, g_tilde=0.0)[source]
Collision in the characteristic frame of axis: R^-1 Q_hat R.
- qlb_port.operators.streaming_reference(axis, n_pos)[source]
Classical streaming permutation on the (spinor x position) space for axis.
Returns a (4*N, 4*N) permutation matrix, N = 2**n_pos, with i = x*4 + c layout.
- qlb_port.operators.reflecting_streaming_reference(axis, n_pos)[source]
Classical reflecting (bounce-back) streaming permutation for axis.
Movers reaching a wall reverse direction: the spinor direction bit flips (c -> c^2, spin preserved) and the amplitude stays at the wall node. Same i = x*4 + c layout as
streaming_reference().
Backend
Qiskit Aer helpers (GPU-first): circuit unitary, state-vector application, and fidelity metrics.
qiskit-aer backend helpers (GPU-first) for the QLB porting layer.
Two Aer simulators are used:
a
unitarysimulator to extract the full unitary a circuit implements (used to verify a ported gate against its target matrix), anda
statevectorsimulator to apply a circuit to an input spinor/state (used for state-level checks and, later, full circuit emulation).
Both prefer the GPU (H100) and fall back to CPU if a GPU device is unavailable, so the module also runs on a login node without a GPU.
- qlb_port.backend.unitary_simulator()[source]
Cached unitary-method AerSimulator (GPU if available).
- qlb_port.backend.statevector_simulator()[source]
Cached statevector-method AerSimulator (GPU if available).
- qlb_port.backend.device_report()[source]
Return which device each simulator resolved to (for diagnostics).
- qlb_port.backend.circuit_unitary(qc)[source]
Return the 2^n x 2^n unitary implemented by circuit qc (n = qc.num_qubits).
- qlb_port.backend.apply_to_statevector(qc, psi_in)[source]
Apply circuit qc to input statevector psi_in; return the output statevector.
- qlb_port.backend.gate_fidelity(A, B)[source]
Phase-invariant gate fidelity |tr(A^dag B)| / dim for two same-size unitaries.
- qlb_port.backend.evolve_snapshots(step_circuit, psi0, snapshots)[source]
Apply a single-step circuit repeatedly, saving the statevector at each snapshot time.
Efficient for time evolution: the full circuit (initialize + repeated steps with labelled statevector saves) is transpiled once and simulated in a single run, rather than rebuilding and re-transpiling a fresh circuit per snapshot.
- Parameters:
step_circuit (QuantumCircuit for one time step (n qubits).)
psi0 (initial statevector (length 2**n).)
snapshots (iterable of step indices at which to record the statevector.)
- Returns:
dict {t
- Return type:
statevector} for each t in snapshots.
Porting harness
The general “unitary \(\rightarrow\) verified circuit” primitive, plus convenience builders for the QLB rotation and collision operators.
General “unitary -> verified circuit” porting harness, plus QLB-specific builders.
The core primitive is port_unitary(), which compiles any 2^n x 2^n unitary into
a gate circuit over a chosen basis (KAK / Shannon decomposition via the transpiler),
and verify(), which checks the compiled circuit reproduces the target unitary on
the qiskit-aer backend. port_and_verify() combines them and reports gate metrics.
These are reused to port each QLB unit operator (rotations, collision). The same harness will serve the AI-driven synthesis work later: any target unitary in, a verified circuit + fidelity out.
- qlb_port.port.num_qubits_for(U)[source]
Number of qubits for a 2^n x 2^n unitary (raises if not a power-of-two square).
- qlb_port.port.port_unitary(U, basis=('rz', 'ry', 'rx', 'cx'), optimization_level=3, label=None)[source]
Compile a unitary matrix U into a gate circuit over basis.
- Parameters:
- Return type:
QuantumCircuit implementing U (up to global phase) over basis.
- qlb_port.port.verify(U, qc=None, basis=('rz', 'ry', 'rx', 'cx'), tol=1e-09)[source]
Port U (if qc not given) and verify the circuit reproduces it.
Returns a dict with the circuit, phase-invariant gate fidelity, two-qubit gate count, depth, basis op counts, and a boolean
ok(fidelity within tol of 1).
- qlb_port.port.port_and_verify(U, basis=('rz', 'ry', 'rx', 'cx'), tol=1e-09, label=None)[source]
Convenience: port U and verify in one call (see
verify()).
Streaming
The QLB \(\pm 1\) lattice shift as a controlled increment / decrement of a position register, and the reflecting (bounce-back) streaming as a folded-ring increment.
Streaming as quantum circuits: the QLB per-component +/-1 lattice shift.
The streaming sub-step shifts each spinor component by +/-1 site along the sweep axis. With the spinor encoded in qubits 0,1 the shift sign depends only on spinor qubit 1 (components 0,1 have qubit1=0; components 2,3 have qubit1=1), so streaming is a controlled increment/decrement of the position register:
axis x, z : qubit1 = 1 -> +1 (increment) , qubit1 = 0 -> -1 (decrement) axis y : qubit1 = 1 -> -1 (decrement) , qubit1 = 0 -> +1 (increment)
The increment adds 1 (mod 2**n_pos) with a ripple cascade of multi-controlled X gates; the decrement is its inverse. This realises periodic streaming (the wrap-around matches the periodic y/z sweeps and the bulk of the x-sweep). The open / bounce-back x boundary is a separate boundary operator (not included here).
With method="fourier" the same shift is built instead as a Draper Fourier
adder (Draper, “Addition on a quantum computer”, arXiv:quant-ph/0008033): the
position register is mapped to the Fourier basis, where adding a constant is a
diagonal phase, and mapped back. The direction control q1 enters as free controlled
phases. The shift itself is O(n_pos) phase gates; with the two swapless QFTs the
circuit is O(n_pos**2) two-qubit gates and uses no ancilla – measured (transpiled to
{rz,ry,rx,cx}) 5 / 15 / 29 / 47 / 69 CX for n_pos = 2 / 3 / 4 / 5 / 6, versus
12 / 106 / 331 / 900 / 2203 CX for the MCX ripple. See also ancilla_streaming_circuit
for the ripple-carry alternative (n_pos - 1 clean carry ancilla).
- Qubit layout (matches operators.streaming_reference):
spinor = qubits 0,1 (qubit 0 = LSB) position = qubits 2..(1+n_pos)
- qlb_port.streaming.increment_gate(n_pos)[source]
Gate that adds 1 (mod 2**n_pos) to an n_pos-qubit register (qubit 0 = LSB).
- qlb_port.streaming.decrement_gate(n_pos)[source]
Gate that subtracts 1 (mod 2**n_pos); inverse of
increment_gate().
- qlb_port.streaming.streaming_circuit(axis, n_pos, method='mcx')[source]
Controlled increment/decrement circuit implementing the streaming sub-step.
- Parameters:
axis ('x', 'y', or 'z')
n_pos (number of position qubits (lattice size N = 2**n_pos))
method ('mcx' (default; ancilla-free multi-controlled-X ripple) or 'fourier') – (Draper Fourier adder: no ancilla, O(n_pos**2) CX via two swapless QFTs; 5/15/29/47/69 CX transpiled for n_pos=2..6 vs 12/106/331/900/2203 for ‘mcx’). See ancilla_streaming_circuit for the ripple-carry route.
- Returns:
QuantumCircuit on (2 + n_pos) qubits
- Return type:
spinor = 0,1 ; position = 2..(1+n_pos).
- qlb_port.streaming.reflecting_streaming_circuit(axis, n_pos)[source]
Reflecting (bounce-back) streaming: hard walls at both ends of the axis.
A reflecting wall is a periodic shift on the folded 2N-site ring R0 -> R1 -> … -> R_{N-1} -> L_{N-1} -> … -> L0 -> R0, which is a single 2N-cycle and therefore unitary. We realise it by unfolding the (direction, position) pair into an (n_pos+1)-bit coordinate p (p = x for +movers, p = 2N-1-x for -movers) and applying a plain +1 (mod 2^{n_pos+1}) increment: every mover advances by one, and a mover that reaches a wall crosses the fold and comes back with reversed direction (its spinor direction bit q1 flips, spin q0 preserved).
Qubit layout: spinor = qubits 0,1 (q1 = direction); position = qubits 2..(1+n_pos).
- qlb_port.streaming.n_stream_ancilla(n_pos)[source]
Carry-ancilla count used by the ripple-carry streaming (n_pos - 1).
- qlb_port.streaming.ancilla_increment_circuit(n_pos)[source]
+1 (mod 2**n_pos) on qubits 0..n_pos-1 via a ripple-carry chain on the carry ancilla qubits n_pos..(2*n_pos-2), which are restored to |0>.
- qlb_port.streaming.ancilla_streaming_circuit(axis, n_pos)[source]
Ancilla (ripple-carry) version of
streaming_circuit(): the same controlled +/-1 shift, but O(n_pos) Toffoli gates instead of the MCX cascade.Returns a QuantumCircuit on 2 + n_pos + (n_pos-1) qubits (spinor 0,1; position 2..1+n_pos; carry ancilla 2+n_pos.., clean before and after).
Single-axis sweep
Assemble rotation, collision, and streaming into one full single-axis substep.
Assemble the ported unit operators into a full single-axis QLB sweep circuit.
One QLB sub-step along an axis is
rotate (R^-1) -> collide (Q_char) -> stream (+/-1 shift) -> rotate back (R)
acting on a 4-component spinor (qubits 0,1) at every lattice site (position qubits 2..(1+n_pos)). For a free particle the mass/potential couplings are uniform, so the collision Q_char is a single fixed 2-qubit gate; the potential-dependent (position-varying) collision is handled separately as a later phase-oracle stage.
The classical reference sweep_operator() is the exact linear operator of one
solver sub-step on the (spinor x position) space (periodic streaming), and
sweep_circuit() is its gate-level implementation. They agree to machine
precision (see test_port.py::test_sweep_assembly).
Qubit / index layout (matches operators.streaming_reference): i = x*4 + c, with spinor = qubits 0,1 (LSB) and position = qubits 2..(1+n_pos).
- qlb_port.sweep.sweep_operator(axis, n_pos, m_tilde=0.0, g_tilde=0.0)[source]
Exact classical operator of one QLB sub-step along axis (periodic streaming).
Sub = (R) . Stream . (Q_char) . (R^-1)
Returns a (4*N, 4*N) unitary, N = 2**n_pos.
- qlb_port.sweep.sweep_circuit(axis, n_pos, m_tilde=0.0, g_tilde=0.0, boundary='periodic', streaming_method='mcx')[source]
Gate-level circuit for one QLB sub-step along axis.
- Parameters:
axis ('x', 'y', or 'z')
n_pos (number of position qubits (lattice N = 2**n_pos))
m_tilde ((per-sweep) dimensionless mass coupling (0 => massless))
g_tilde ((per-sweep) dimensionless potential coupling (0 => free particle))
boundary ('periodic' (modular wrap) or 'reflecting' (bounce-back hard walls))
streaming_method ('mcx' (default; ancilla-free multi-controlled-X ripple) or) – ‘fourier’ (Draper Fourier adder: no ancilla; see
streaming.streaming_circuit()). Ignored for boundary=’reflecting’.
- Return type:
QuantumCircuit on (2 + n_pos) qubits.
Position-dependent potential
A position-dependent potential as a phase oracle (massless) or a position-multiplexed collision (massive).
Position-dependent potential (impurity scattering) as a circuit.
In the QLB collision Q_hat(m, g) = a_hat I - i b_hat ALPHA_Y the potential enters through g (the local coupling g_tilde = V_energy * DT / (N_sweeps * hbar)). For the massless Dirac / graphene case (m = 0) the mass coupling vanishes (b_hat = 0) and the collision reduces to a position-dependent global phase
Q_hat(0, g(x)) = a_hat(g(x)) * I , |a_hat| = 1 ,
i.e. a diagonal phase oracle diag(a_hat(x)) acting on the position register only (the same phase for all four spinor components). This is exactly how a potential landscape - such as the random impurity barriers of the Klein-tunneling benchmark - scatters the wave packet.
This module builds that phase oracle and the massless sweep circuit that includes it, plus a general classical reference (valid for massive potentials too) for validation.
Layout matches operators.streaming_reference: position = qubits 2..(1+n_pos), and the oracle’s diagonal entry x multiplies position basis state |x>.
- qlb_port.potential.collision_phases(V_tilde)[source]
Massless collision phases a_hat(x) for a per-site potential coupling array.
- Parameters:
V_tilde (array (N,) of per-site g_tilde (dimensionless potential coupling).)
- Returns:
a_hat
- Return type:
complex array (N,), unit modulus (a_hat = collision_coefficients(0, g)[0]).
- qlb_port.potential.potential_oracle(V_tilde)[source]
Diagonal phase-oracle gate diag(a_hat(x)) for the massless potential collision.
Acts on n_pos = log2(len(V_tilde)) position qubits.
- qlb_port.potential.impurity_field(n_pos, positions, g_value)[source]
Build a per-site potential coupling array with g_value at positions, else 0.
- Parameters:
n_pos (number of position qubits (lattice N = 2**n_pos).)
positions (iterable of lattice sites carrying a barrier.)
g_value (dimensionless potential coupling g_tilde at those sites.)
- qlb_port.potential.multiplexed_collision_circuit(axis, n_pos, V_tilde, m_tilde)[source]
Position-multiplexed collision: apply Q_char(m, V(x)) to the spinor at every site.
Implemented as a uniform vacuum collision Q_char(m, 0) on the spinor qubits, plus a position-controlled correction C(x) = Q_char(m, V(x)) Q_char(m, 0)^dagger at each site where V(x) != 0. For the massless case this reduces to a diagonal phase; for a massive particle it is a genuine 2-qubit gate, so a potential barrier reflects.
- qlb_port.potential.sweep_circuit_potential(axis, n_pos, V_tilde, m_tilde=0.0)[source]
QLB sub-step with a position-dependent potential:
rotate R^-1 -> collision(m, V(x)) -> stream -> rotate R
For m_tilde = 0 the collision is a diagonal phase oracle on the position register (cheap). For m_tilde != 0 it is a position-multiplexed 2-qubit gate, so the barrier can reflect the (now gapped) particle.
Two dimensions
Compose x- and y-sweeps on two position registers.
2D QLB: compose the x- and y-sweeps on two position registers.
A 2D Dirac time step is operator-split into an x-sweep followed by a y-sweep (Lie-Trotter). On qubits:
spinor = qubits 0, 1 x-position = qubits 2 .. (1 + nx) y-position = qubits (2 + nx) .. (1 + nx + ny)
The x-sweep acts on (spinor, x-register) and the y-sweep on (spinor, y-register),
sharing the spinor qubits. Each is the validated 1D sweep.sweep_circuit()
mapped onto the appropriate register, so the 2D circuit inherits the 1D correctness.
Full-state index layout (matches classical_step_2d): i = (y*Nx + x)*4 + c, with c the spinor component (qubits 0,1), x the x-register, y the y-register.
- qlb_port.twod.sweep2d_circuit(nx, ny, m_tilde=0.0, g_tilde=0.0)[source]
One 2D QLB step (x-sweep then y-sweep) for uniform mass/potential.
- qlb_port.twod.evolution2d_circuit(nx, ny, n_steps, m_tilde=0.0, g_tilde=0.0)[source]
n_steps repeated 2D steps.
- qlb_port.twod.classical_step_2d(psi_flat, nx, ny, m_tilde=0.0, g_tilde=0.0)[source]
One classical 2D QLB step on a flat statevector (index i = (y*Nx + x)*4 + c).
- qlb_port.twod.sweep2d_operator(nx, ny, m_tilde=0.0, g_tilde=0.0)[source]
Exact 2D step operator (built column-by-column; use only for small nx, ny).
- qlb_port.twod.sweep2d_circuit_potential(nx, ny, V2d, m_tilde=0.0)[source]
Massless 2D QLB step through a potential landscape V(x, y).
The collision is the diagonal phase oracle diag(a_hat(V(x,y))) on the full (x, y) position register, applied in each sweep:
x-sweep: rotate_x -> oracle(x,y) -> stream_x -> rotate_x^-1 y-sweep: oracle(x,y) -> stream_y
(Only m_tilde = 0 is ported as a circuit; the massive case would need a position-multiplexed collision.)
- qlb_port.twod.evolution2d_circuit_potential(nx, ny, n_steps, V2d, m_tilde=0.0)[source]
n_steps repeated massless 2D steps through a fixed potential landscape.
Three dimensions
Compose x-, y-, and z-sweeps on three position registers.
3D QLB: compose the x-, y-, and z-sweeps on three position registers.
A 3D Dirac time step is operator-split into x-, y-, then z-sweeps (Lie-Trotter). On qubits:
spinor = qubits 0, 1 x-position = qubits 2 .. (1 + nx) y-position = next ny qubits z-position = next nz qubits
Each sweep is the validated 1D sweep.sweep_circuit() mapped onto the matching
register (spinor shared), so the 3D circuit inherits the 1D correctness. Dellar’s
representation makes this clean: the three spatial streaming matrices are
{ALPHA_X, BETA, ALPHA_Z}, so the z-sweep uses the Z rotation exactly as the 1D case.
- Full-state index layout (matches classical_step_3d):
i = ((z*Ny + y)*Nx + x)*4 + c
with c the spinor component and x/y/z the three registers (x lowest).
- qlb_port.threed.sweep3d_circuit(nx, ny, nz, m_tilde=0.0, g_tilde=0.0, bc=('periodic', 'periodic', 'periodic'), streaming_method='mcx')[source]
One 3D QLB step (x-, y-, z-sweeps) for uniform mass/potential.
bc : per-axis boundary conditions, each ‘periodic’ or ‘reflecting’ (hard walls). streaming_method : ‘mcx’ (default) or ‘fourier’ (Draper QFT adder); passed to each
periodic sweep and ignored on reflecting axes.
- qlb_port.threed.evolution3d_circuit(nx, ny, nz, n_steps, m_tilde=0.0, g_tilde=0.0, bc=('periodic', 'periodic', 'periodic'), streaming_method='mcx')[source]
n_steps repeated 3D steps.
- qlb_port.threed.classical_step_3d(psi_flat, nx, ny, nz, m_tilde=0.0, g_tilde=0.0, bc=('periodic', 'periodic', 'periodic'))[source]
One classical 3D QLB step on a flat statevector (i = ((z*Ny+y)*Nx+x)*4+c).
- qlb_port.threed.sweep3d_operator(nx, ny, nz, m_tilde=0.0, g_tilde=0.0, bc=('periodic', 'periodic', 'periodic'))[source]
Exact 3D step operator (built column-by-column; use only for small sizes).
- qlb_port.threed.sweep3d_circuit_potential(nx, ny, nz, V3d, m_tilde=0.0)[source]
Massless 3D QLB step through a potential landscape V(x,y,z) (phase oracle per sweep).
- qlb_port.threed.evolution3d_circuit_potential(nx, ny, nz, n_steps, V3d, m_tilde=0.0)[source]
n_steps repeated massless 3D steps through a fixed potential landscape.