Source code for qlb_port.port

"""
General "unitary -> verified circuit" porting harness, plus QLB-specific builders.
==================================================================================

The core primitive is :func:`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 :func:`verify`, which checks the compiled circuit reproduces the target unitary on
the qiskit-aer backend.  :func:`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.
"""

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

from . import operators as ops
from . import backend as bk

# CNOT + single-qubit rotations (the KAK target of Task 1).
DEFAULT_BASIS = ("rz", "ry", "rx", "cx")
# IBM Heron-native set (kept for later hardware-aware ports).
HERON_BASIS = ("cz", "rz", "sx", "x")

# Two-qubit entangling gates whose counts we report.
_TWO_QUBIT = ("cx", "cz", "ecr")


[docs] def num_qubits_for(U): """Number of qubits for a 2^n x 2^n unitary (raises if not a power-of-two square).""" d = np.asarray(U).shape[0] n = int(round(np.log2(d))) if 2 ** n != d or np.asarray(U).shape != (d, d): raise ValueError(f"operator shape {np.asarray(U).shape} is not 2^n x 2^n") return n
[docs] def port_unitary(U, basis=DEFAULT_BASIS, optimization_level=3, label=None): """ 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. Returns ------- QuantumCircuit implementing `U` (up to global phase) over `basis`. """ n = num_qubits_for(U) qc = QuantumCircuit(n) qc.append(UnitaryGate(np.asarray(U, dtype=complex), label=label), list(range(n))) return transpile(qc, basis_gates=list(basis), optimization_level=optimization_level)
[docs] def two_qubit_count(qc): """Total number of two-qubit entangling gates in `qc`.""" ops_count = qc.count_ops() return sum(ops_count.get(g, 0) for g in _TWO_QUBIT)
[docs] def verify(U, qc=None, basis=DEFAULT_BASIS, tol=1e-9): """ 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). """ if qc is None: qc = port_unitary(U, basis=basis) U_circ = bk.circuit_unitary(qc) fid = bk.gate_fidelity(U, U_circ) return { "circuit": qc, "fidelity": fid, "ok": abs(fid - 1.0) < tol, "cx": two_qubit_count(qc), "depth": qc.depth(), "ops": dict(qc.count_ops()), }
[docs] def port_and_verify(U, basis=DEFAULT_BASIS, tol=1e-9, label=None): """Convenience: port `U` and verify in one call (see :func:`verify`).""" qc = port_unitary(U, basis=basis, label=label) return verify(U, qc=qc, basis=basis, tol=tol)
# --- QLB-specific convenience builders -----------------------------------------
[docs] def rotation_circuit(axis, basis=DEFAULT_BASIS): """Ported circuit for the QLB rotation R along `axis` ('x' or 'z'; 'y' is identity).""" R = ops.ROTATIONS[axis] return port_unitary(R, basis=basis, label=f"R_{axis}")
[docs] def collision_circuit(m_tilde, g_tilde=0.0, basis=DEFAULT_BASIS): """Ported circuit for the standard-frame collision Q_hat(m_tilde, g_tilde).""" Q = ops.collision_operator(m_tilde, g_tilde) return port_unitary(Q, basis=basis, label="Qhat")