Source code for qlb_port.threed

"""
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 :func:`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).
"""

import numpy as np
from qiskit import QuantumCircuit
from qiskit.circuit.library import UnitaryGate, DiagonalGate

from . import operators as ops
from . import sweep
from . import streaming as st
from . import potential as pot
from .twod import _line_step   # shared 1D line step (rotate->collide->stream->rotate)

AXES = ("x", "y", "z")


def _registers(nx, ny, nz):
    """Qubit lists [spinor(0,1) + position register] for each axis."""
    q = {}
    start = 2
    for axis, n in zip(AXES, (nx, ny, nz)):
        q[axis] = [0, 1] + list(range(start, start + n))
        start += n
    return q


[docs] def sweep3d_circuit(nx, ny, nz, m_tilde=0.0, g_tilde=0.0, bc=("periodic", "periodic", "periodic"), streaming_method="mcx"): """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. """ qc = QuantumCircuit(2 + nx + ny + nz, name="sweep3d") regs = _registers(nx, ny, nz) for axis, n, b in zip(AXES, (nx, ny, nz), bc): qc.compose(sweep.sweep_circuit(axis, n, m_tilde=m_tilde, g_tilde=g_tilde, boundary=b, streaming_method=streaming_method), qubits=regs[axis], inplace=True) return qc
[docs] def evolution3d_circuit(nx, ny, nz, n_steps, m_tilde=0.0, g_tilde=0.0, bc=("periodic", "periodic", "periodic"), streaming_method="mcx"): """`n_steps` repeated 3D steps.""" qc = QuantumCircuit(2 + nx + ny + nz, name=f"evolve3d_{n_steps}") step = sweep3d_circuit(nx, ny, nz, m_tilde=m_tilde, g_tilde=g_tilde, bc=bc, streaming_method=streaming_method) for _ in range(n_steps): qc.compose(step, inplace=True) return qc
[docs] def classical_step_3d(psi_flat, nx, ny, nz, m_tilde=0.0, g_tilde=0.0, bc=("periodic", "periodic", "periodic")): """One classical 3D QLB step on a flat statevector (i = ((z*Ny+y)*Nx+x)*4+c).""" Nx, Ny, Nz = 2 ** nx, 2 ** ny, 2 ** nz bx, by, bz = bc psi = np.asarray(psi_flat, dtype=complex).reshape(Nz, Ny, Nx, 4).copy() for z in range(Nz): # x-sweep for y in range(Ny): psi[z, y] = _line_step(psi[z, y], "x", m_tilde, g_tilde, boundary=bx) for z in range(Nz): # y-sweep for x in range(Nx): psi[z, :, x, :] = _line_step(psi[z, :, x, :], "y", m_tilde, g_tilde, boundary=by) for y in range(Ny): # z-sweep for x in range(Nx): psi[:, y, x, :] = _line_step(psi[:, y, x, :], "z", m_tilde, g_tilde, boundary=bz) return psi.reshape(-1)
[docs] def sweep3d_operator(nx, ny, nz, m_tilde=0.0, g_tilde=0.0, bc=("periodic", "periodic", "periodic")): """Exact 3D step operator (built column-by-column; use only for small sizes).""" dim = 4 * (2 ** nx) * (2 ** ny) * (2 ** nz) M = np.zeros((dim, dim), dtype=complex) for j in range(dim): e = np.zeros(dim, dtype=complex) e[j] = 1.0 M[:, j] = classical_step_3d(e, nx, ny, nz, m_tilde, g_tilde, bc=bc) return M
# ----------------------------------------------------------------------------- # 3D with a position-dependent potential V(x, y, z) (massless / graphene) # ----------------------------------------------------------------------------- def _oracle_diag_3d(V3d): """Phase-oracle diagonal a_hat(V(x,y,z)) ordered by register index x + Nx*y + Nx*Ny*z.""" V3d = np.asarray(V3d, dtype=float) # shape (Nx, Ny, Nz), V3d[x,y,z] return pot.collision_phases(V3d.flatten("F")) # F-order: x fastest -> matches register
[docs] def sweep3d_circuit_potential(nx, ny, nz, V3d, m_tilde=0.0): """Massless 3D QLB step through a potential landscape V(x,y,z) (phase oracle per sweep).""" if m_tilde != 0.0: raise NotImplementedError("3D potential circuit is massless-only (graphene/Klein).") oracle = DiagonalGate(list(_oracle_diag_3d(V3d))) posq = list(range(2, 2 + nx + ny + nz)) regs = _registers(nx, ny, nz) qc = QuantumCircuit(2 + nx + ny + nz, name="sweep3dV") for axis, n in zip(AXES, (nx, ny, nz)): R = ops.ROTATIONS[axis] if axis != "y": qc.append(UnitaryGate(R.conj().T, label=f"R{axis}_inv"), [0, 1]) qc.append(oracle, posq) qc.compose(st.streaming_circuit(axis, n), qubits=regs[axis], inplace=True) if axis != "y": qc.append(UnitaryGate(R, label=f"R{axis}"), [0, 1]) return qc
[docs] def evolution3d_circuit_potential(nx, ny, nz, n_steps, V3d, m_tilde=0.0): """`n_steps` repeated massless 3D steps through a fixed potential landscape.""" qc = QuantumCircuit(2 + nx + ny + nz, name=f"evolve3dV_{n_steps}") step = sweep3d_circuit_potential(nx, ny, nz, V3d, m_tilde=m_tilde) for _ in range(n_steps): qc.compose(step, inplace=True) return qc
[docs] def classical_step_3d_potential(psi_flat, nx, ny, nz, V3d, m_tilde=0.0): """Classical 3D QLB step with a per-cell potential V3d (shape (Nx,Ny,Nz), V3d[x,y,z]).""" Nx, Ny, Nz = 2 ** nx, 2 ** ny, 2 ** nz V3d = np.asarray(V3d, dtype=float) psi = np.asarray(psi_flat, dtype=complex).reshape(Nz, Ny, Nx, 4).copy() for z in range(Nz): # x-sweep: g along x = V3d[:, y, z] for y in range(Ny): psi[z, y] = _line_step(psi[z, y], "x", m_tilde, V3d[:, y, z]) for z in range(Nz): # y-sweep: g along y = V3d[x, :, z] for x in range(Nx): psi[z, :, x, :] = _line_step(psi[z, :, x, :], "y", m_tilde, V3d[x, :, z]) for y in range(Ny): # z-sweep: g along z = V3d[x, y, :] for x in range(Nx): psi[:, y, x, :] = _line_step(psi[:, y, x, :], "z", m_tilde, V3d[x, y, :]) return psi.reshape(-1)
[docs] def planar_barrier_field_3d(nx, ny, nz, x_sites, g_value): """3D potential (shape (Nx,Ny,Nz)) with a planar barrier at the given x-sites (all y,z).""" V = np.zeros((2 ** nx, 2 ** ny, 2 ** nz), dtype=float) V[np.asarray(list(x_sites), dtype=int), :, :] = g_value return V