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_solver via 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 unitary simulator to extract the full unitary a circuit implements (used to verify a ported gate against its target matrix), and

  • a statevector simulator 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.state_fidelity(a, b)[source]

|<a|b>| for two (unnormalized) state vectors.

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:
  • U ((2^n, 2^n) array — the target unitary.)

  • basis (tuple[str] — basis gate set to compile to (default: CNOT + rotations).)

  • optimization_level (int — transpiler optimization level (0-3).)

  • label (str | None — optional gate label.)

Return type:

QuantumCircuit implementing U (up to global phase) over basis.

qlb_port.port.two_qubit_count(qc)[source]

Total number of two-qubit entangling gates in qc.

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

qlb_port.port.rotation_circuit(axis, basis=('rz', 'ry', 'rx', 'cx'))[source]

Ported circuit for the QLB rotation R along axis (‘x’ or ‘z’; ‘y’ is identity).

qlb_port.port.collision_circuit(m_tilde, g_tilde=0.0, basis=('rz', 'ry', 'rx', 'cx'))[source]

Ported circuit for the standard-frame collision Q_hat(m_tilde, g_tilde).

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.

qlb_port.sweep.evolution_circuit(axis, n_pos, n_steps, m_tilde=0.0, g_tilde=0.0, streaming_method='mcx')[source]

Circuit for n_steps repeated single-axis sub-steps (free-particle evolution).

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.

qlb_port.potential.sweep_operator_potential(axis, n_pos, V_tilde, m_tilde=0.0)[source]

Exact classical operator of one QLB sub-step with a per-site potential (general; valid for massive potentials too). Collision is block-diagonal over position, each block Q_char(m_tilde, V_tilde[x]).

qlb_port.potential.evolution_circuit_potential(axis, n_pos, n_steps, V_tilde, m_tilde=0.0)[source]

Circuit for n_steps sub-steps through a fixed potential landscape.

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.

qlb_port.twod.classical_step_2d_potential(psi_flat, nx, ny, V2d, m_tilde=0.0)[source]

Classical 2D QLB step with a per-cell potential V2d (shape (Nx, Ny), V2d[x,y]).

qlb_port.twod.barrier_field_2d(nx, ny, x_sites, g_value)[source]

2D potential (shape (Nx, Ny)) with a vertical barrier at the given x-sites.

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.

qlb_port.threed.classical_step_3d_potential(psi_flat, nx, ny, nz, V3d, m_tilde=0.0)[source]

Classical 3D QLB step with a per-cell potential V3d (shape (Nx,Ny,Nz), V3d[x,y,z]).

qlb_port.threed.planar_barrier_field_3d(nx, ny, nz, x_sites, g_value)[source]

3D potential (shape (Nx,Ny,Nz)) with a planar barrier at the given x-sites (all y,z).