dense-evolution 8.3.0__py3-none-win_amd64.whl

dashboard_core/crypto_protocols.py

@@ -0,0 +1,77 @@
+"""
+Thin wrappers around dense_evolution.protocols (crypto-q, promoted from
+Dense-Evolution-Discovery issue #189) for the Composer kernel -- see
+docs/api/protocols.md for the real, validated numbers behind each
+protocol. Each function here just calls straight into the real protocol
+module and returns a plain dict; no new cryptographic logic lives here.
+"""
+from dataclasses import dataclass
+
+from dense_evolution.protocols import bb84 as _bb84
+from dense_evolution.protocols import di_qkd_ghz as _di_qkd_ghz
+from dense_evolution.protocols import dicka_protocol2 as _dicka
+
+__all__ = ['Bb84Result', 'run_bb84', 'DiQkdGhzResult', 'run_di_qkd_ghz', 'run_dicka_protocol']
+
+
+@dataclass
+class Bb84Result:
+    n_rounds: int
+    p_channel: float
+    eve: bool
+    qber: float
+    sifted_key_length: int
+
+
+def run_bb84(n_rounds: int, p_channel: float = 0.0, eve: bool = False, seed=None) -> Bb84Result:
+    """BB84: prepare -> channel -> measure -> sift -> QBER
+    (dense_evolution.protocols.bb84.bb84_run). QBER=0 on a perfect
+    channel, `2*p_channel/3` under isotropic depolarizing noise,
+    `0.25` under an intercept-resend attack (`eve=True`) -- see
+    docs/api/protocols.md for the validated numbers this reproduces."""
+    qber, sifted_key_length = _bb84.bb84_run(n_rounds, p_channel, eve=eve, seed=seed)
+    return Bb84Result(
+        n_rounds=n_rounds, p_channel=p_channel, eve=eve,
+        qber=float(qber), sifted_key_length=int(sifted_key_length),
+    )
+
+
+@dataclass
+class DiQkdGhzResult:
+    n_rounds: int
+    p_dep: float
+    win_rate: float
+    expected_win_rate: float
+    qber_b1: float
+    qber_b2: float
+
+
+def run_di_qkd_ghz(n_rounds: int, p_dep: float = 0.0, seed=None) -> DiQkdGhzResult:
+    """Three-party device-independent conference key agreement via GHZ(3)
+    (Ribeiro, Murta & Wehner 2018, arXiv:1708.00798;
+    dense_evolution.protocols.di_qkd_ghz). `win_rate` is the real,
+    simulated Parity-CHSH win rate over `n_rounds` test rounds;
+    `expected_win_rate` is the exact theoretical value at this `p_dep`
+    (quantum max `0.85355...` at `p_dep=0`) -- comparing the two directly
+    checks the simulation against the closed-form prediction, not just
+    against itself."""
+    win_rate = _di_qkd_ghz.parity_chsh_win_rate(n_rounds, p_dep, seed=seed)
+    qber_b1, qber_b2 = _di_qkd_ghz.key_qber(n_rounds, p_dep, seed=seed)
+    return DiQkdGhzResult(
+        n_rounds=n_rounds, p_dep=p_dep,
+        win_rate=float(win_rate), expected_win_rate=float(_di_qkd_ghz.expected_win_rate(p_dep)),
+        qber_b1=float(qber_b1), qber_b2=float(qber_b2),
+    )
+
+
+def run_dicka_protocol(n_rounds: int, gamma: float, beta: float, p_dep: float = 0.0, seed=None) -> dict:
+    """Full multi-round DICKA structure (Appendix Protocol 2 of Ribeiro,
+    Murta & Wehner 2018; dense_evolution.protocols.dicka_protocol2):
+    round selection, parameter estimation, and the abort decision.
+    Already returns a plain, JSON-safe dict -- see run_protocol's own
+    docstring for exactly what each field means. Deliberately does not
+    report a secure key length: Theorem 4's exact value depends on a
+    numerical optimization the source paper never reduces to closed form."""
+    result = _dicka.run_protocol(n_rounds=n_rounds, gamma=gamma, beta=beta, p_dep=p_dep, seed=seed)
+    result["aborted"] = bool(result["aborted"])
+    return result

dashboard_core/engine.py

@@ -0,0 +1,326 @@
+"""
+Real simulation engine for the dashboard.
+
+OpenQASM text -> dense_evolution's own QASMParser -> executed on
+dense_evolution's actual DenseSVSimulator/MPSSimulator (not Qiskit's own
+simulator, and not Qiskit's QASM parser either) -> statevector,
+probabilities and shot counts, all reordered into Qiskit's little-endian
+qubit convention so they line up with the Circuit tab's qubit labels and
+with qiskit.visualization's functions (which assume that convention).
+
+No Qiskit QuantumCircuit is ever constructed here, not even for the
+Circuit-diagram panel: qiskit.circuit.QuantumCircuit.__init__ itself
+segfaults (SIGSEGV, inside qiskit's own compiled extension) on macOS,
+independent of *how* the circuit is built or what's done with it
+afterwards -- see tests/integration/test_interop.py::TestQiskitInterop for the full
+reproduction story (QuantumCircuit(3) alone, no QASM, no method calls,
+still crashes there). SimulationResult/LargeScaleMPSResult below carry
+the plain gate tuples instead, and dashboard_core.circuit_diagram draws
+the diagram directly from those with plain matplotlib.
+
+No synthetic/placeholder data anywhere here: every quantity returned is
+computed from a real run of the real engine.
+"""
+
+from dataclasses import dataclass
+from functools import lru_cache
+from typing import Optional
+
+import numpy as np
+
+import dense_evolution as de
+
+__all__ = [
+    'SimulationResult', 'run_circuit_from_qasm', 'LargeScaleMPSResult',
+    'run_large_circuit_mps', 'run_bond_convergence_check',
+]
+
+
+def _qasm_to_tuples(qasm_text: str):
+    """Parses qasm_text with dense_evolution's own QASMParser (never
+    Qiskit's) and returns (n_qubits, ops) where ops is the same
+    (name, *qubits[, param]) tuple format every other dense_evolution
+    entry point (run_circuit, QuantumTranspiler.transpile, ...) accepts."""
+    parsed = de.QASMParser().parse(qasm_text)
+    return parsed.n_qubits, parsed.to_tuples()
+
+# MPSSimulator.contract_to_statevector's own hard ceiling (RAM-independent
+# -- it refuses above this regardless of available memory, since a dense
+# 2**n array stops being the point of using MPS at all). Circuits at or
+# below this go through the normal dense-statevector path (same
+# Probabilities/Q-sphere/Statevector panels as the Dense backend); above
+# it, run_large_circuit_mps is the only real path.
+MPS_DENSE_CONTRACTION_LIMIT = 24
+
+
+@lru_cache(maxsize=None)
+def _qiskit_bit_order_perm(n_qubits: int) -> np.ndarray:
+    """The bit-reverse index permutation itself, cached per n_qubits --
+    it's O(2**n_qubits) to build and depends only on n_qubits, so a
+    circuit run repeatedly at the same qubit count (the common case: a
+    fixed molecule/preset re-run with different parameters) was
+    rebuilding an identical array every single call. lru_cache keys on
+    the (hashable) n_qubits argument only -- the returned array itself
+    doesn't need to be hashable.
+
+    Vectorized bit-reversal (prog.txt, dashboard_core audit point 1b/4c):
+    loops over n_qubits bit positions, not over the 2**n_qubits indices
+    themselves like the previous `format(i, ...)[::-1]`-per-index Python
+    loop did -- the same fix already applied to
+    dense_evolution.interop.qiskit_pennylane's own copy of this exact
+    permutation."""
+    idx = np.arange(2 ** n_qubits)
+    perm = np.zeros_like(idx)
+    for b in range(n_qubits):
+        perm |= ((idx >> b) & 1) << (n_qubits - 1 - b)
+    perm.setflags(write=False)  # cached and shared across calls -- never mutate in place
+    return perm
+
+
+def _to_qiskit_bit_order(values: np.ndarray, n_qubits: int) -> np.ndarray:
+    """Bit-reverse index order: Dense-Evolution is MSB-first (qubit 0 =
+    most significant bit of the index), Qiskit is little-endian (qubit 0
+    = least significant bit) -- the same remap dense_evolution.interop
+    applies to probabilities internally, used here for the raw complex
+    statevector too since it is the identical index permutation."""
+    return values[_qiskit_bit_order_perm(n_qubits)]
+
+
+@dataclass
+class SimulationResult:
+    ops: list  # dense_evolution gate tuples -- feeds dashboard_core.circuit_diagram for the Circuit tab
+    n_qubits: int
+    statevector: np.ndarray    # complex128, Qiskit bit order
+    probabilities: np.ndarray  # Qiskit bit order
+    counts: dict                # Qiskit-style bitstring -> shot count
+    noise_model: str = "ideal"
+    noise_p: float = 0.0
+    fidelity_vs_ideal: Optional[float] = None
+    backend: str = "dense"
+    mps_max_bond_used: Optional[int] = None
+    mps_memory_mb: Optional[float] = None
+    mps_avg_jsd: Optional[float] = None
+
+
+def run_circuit_from_qasm(
+    qasm_text: str,
+    n_shots: int = 1000,
+    seed: Optional[int] = None,
+    noise_model: str = "ideal",
+    noise_p: float = 0.0,
+    backend: str = "dense",
+) -> SimulationResult:
+    """Parse `qasm_text` and run it on a real dense_evolution engine,
+    returning every quantity the dashboard's tabs need.
+
+    noise_model/noise_p: one of dense_evolution.NoiseModel.MODELS
+    ('ideal', 'depolarizing', 'bitflip', 'phaseflip', 'amplitude_damping',
+    'combined') applied as a real stochastic Kraus channel to the
+    statevector via NoiseModel.apply_to_sv -- not a fabricated decay
+    curve, the actual channel math. 'ideal'/p<=0 skips it entirely (and
+    leaves SimulationResult.fidelity_vs_ideal as None -- comparing a run
+    against itself is not a real quantity). Otherwise fidelity_vs_ideal
+    is the real dense_evolution.statevector_fidelity(|<ideal|noisy>|^2)
+    between this run's one noisy trajectory and the same circuit's ideal
+    statevector, both computed in this same call (not re-simulated by the
+    caller).
+
+    backend: 'dense' (DenseSVSimulator, the default) or 'mps'
+    (MPSSimulator -- adaptive SVD-truncated matrix product state, scales
+    to far more qubits for low-entanglement circuits; contracted back to
+    a dense statevector afterwards so the same Probabilities/Q-sphere/
+    Statevector panels work unchanged regardless of which engine ran the
+    circuit). Verified to match 'dense' exactly (atol=1e-6) on every
+    preset in QASM_LIBRARY, and to run a 12-qubit GHZ state in ~2.5s
+    (max_bond=2) where 'dense' would need 2**12 complex amplitudes.
+
+    Examples
+    --------
+    >>> from dashboard_core.engine import run_circuit_from_qasm
+    >>> qasm = '''
+    ... OPENQASM 2.0;
+    ... include "qelib1.inc";
+    ... qreg q[2];
+    ... creg c[2];
+    ... h q[0];
+    ... cx q[0],q[1];
+    ... measure q -> c;
+    ... '''
+    >>> result = run_circuit_from_qasm(qasm, n_shots=1000, seed=0)
+    >>> result.probabilities.round(3).tolist()  # Bell pair: only |00> and |11> populated
+    [0.5, 0.0, 0.0, 0.5]
+    >>> set(result.counts.keys()) <= {'00', '11'}  # shot counts only land on those two states
+    True
+    """
+    n_qubits, ops = _qasm_to_tuples(qasm_text)
+    if n_qubits < 1:
+        raise ValueError("circuit must declare at least 1 qubit")
+    if backend not in ("dense", "mps"):
+        raise ValueError(f"unknown backend {backend!r}, must be 'dense' or 'mps'")
+
+    # Both backends end up holding a real 2**n_qubits complex128 dense
+    # statevector (Dense always; MPS after contract_to_statevector() for
+    # display) -- check against this machine's *actual* free RAM before
+    # allocating it, via the same real anti-OOM guard dense_evolution.chunk
+    # already uses (15% safety threshold, psutil-backed), rather than
+    # letting a manually-typed large QASM circuit (which bypasses the
+    # UI's qubit cap entirely) crash the process.
+    required_mb = (2 ** n_qubits) * 16 / 1e6
+    de.chunk.SafeMemoryGuard().check_allocation(required_mb, context=f"{n_qubits}-qubit statevector")
+
+    mps_max_bond_used = mps_memory_mb = mps_avg_jsd = None
+
+    if backend == "mps":
+        # MPSSimulator.run_circuit_jit does not auto-transpile (unlike
+        # DenseSVSimulator.run_circuit) -- swap/ccx must be decomposed
+        # first or it raises on 'swap' not being in its native GATE_IDS
+        # (verified directly: the QFT preset's trailing swap fails here
+        # without this step).
+        transpiled = de.QuantumTranspiler.transpile(ops)
+        mps = de.MPSSimulator(n_qubits)
+        mps.run_circuit_jit(transpiled)
+        sv_native = np.asarray(mps.contract_to_statevector())
+        mps_max_bond_used = mps.max_bond_used()
+        mps_memory_mb = mps.memory_mb()
+        mps_avg_jsd = mps.avg_jsd()
+    else:
+        sim = de.DenseSVSimulator(n_qubits, use_float32=False)
+        sim.run_circuit(ops)
+        sv_native = np.asarray(sim.sv)
+
+    rng = np.random.default_rng(seed)
+    fidelity_vs_ideal = None
+    if noise_model != "ideal" and noise_p > 0:
+        # apply_to_sv mutates its numpy input in-place, so the pre-noise
+        # amplitudes have to be copied out first -- this is one stochastic
+        # Kraus-channel trajectory (a real single noisy realization, not a
+        # density matrix), so the result is still a valid pure state and
+        # dense_evolution.statevector_fidelity (the pure-state counterpart
+        # to the density-matrix uhlmann_fidelity already used by the ZNE
+        # panels below) is the right comparison against the ideal state.
+        sv_ideal = sv_native.copy()
+        sv_native = de.NoiseModel.apply_to_sv(sv_native, n_qubits, noise_model, noise_p, rng=rng)
+        fidelity_vs_ideal = float(de.statevector_fidelity(sv_ideal, sv_native))
+
+    statevector = _to_qiskit_bit_order(sv_native, n_qubits)
+    probabilities = np.abs(statevector) ** 2
+
+    # sample_counts expects/returns dense_evolution's native MSB-first
+    # bitstring convention -- reverse each key to relabel into Qiskit's
+    # little-endian convention (same physical samples, just relabeled to
+    # match the Circuit/Probabilities tabs' qubit numbering).
+    counts_native = de.sample_counts(sv_native, n_shots, rng=rng)
+    counts = {key[::-1]: n for key, n in counts_native.items()}
+
+    return SimulationResult(
+        ops=ops,
+        n_qubits=n_qubits,
+        statevector=statevector,
+        probabilities=probabilities,
+        counts=counts,
+        noise_model=noise_model,
+        noise_p=noise_p,
+        fidelity_vs_ideal=fidelity_vs_ideal,
+        backend=backend,
+        mps_max_bond_used=mps_max_bond_used,
+        mps_memory_mb=mps_memory_mb,
+        mps_avg_jsd=mps_avg_jsd,
+    )
+
+
+@dataclass
+class LargeScaleMPSResult:
+    ops: list  # dense_evolution gate tuples -- feeds dashboard_core.circuit_diagram for the Circuit tab
+    n_qubits: int
+    top_k_states: list  # [(bitstring, probability), ...] Qiskit bit order, sorted descending
+    k_requested: int
+    mps_max_bond_used: int
+    mps_memory_mb: float
+    mps_avg_jsd: float
+
+
+def run_large_circuit_mps(qasm_text: str, k: int = 32, seed: Optional[int] = None) -> LargeScaleMPSResult:
+    """For circuits beyond MPS_DENSE_CONTRACTION_LIMIT qubits, where no
+    dense (2**n,) statevector/probabilities array can exist at all: runs
+    the real MPS circuit and finds the top-k most probable basis states
+    via MPSSimulator.get_top_k_probable_states -- a real greedy beam
+    search, EXACT probabilities for the states it finds (not sampled or
+    approximated). Verified directly against exact dense diagonalization
+    at 10 qubits: every state with non-negligible probability was found,
+    matching to 6 decimal places (recall isn't guaranteed complete for
+    highly-entangled circuits at fixed k -- see MPSSimulator's own
+    docstring -- but the probabilities reported are always exact, never
+    estimated).
+
+    Chosen over MPSSimulator.get_probabilities_sampled for this UI:
+    measured directly, sampling 2000 shots takes 130s/257s/582s at
+    30/50/100 qubits (grows with n -- roughly O(n_samples * n_qubits)),
+    while get_top_k_probable_states stays under 2s even at 100 qubits.
+
+    Examples
+    --------
+    >>> from dashboard_core.engine import run_large_circuit_mps
+    >>> qasm = '''
+    ... OPENQASM 2.0;
+    ... include "qelib1.inc";
+    ... qreg q[5];
+    ... creg c[5];
+    ... h q[0];
+    ... cx q[0],q[1];
+    ... cx q[1],q[2];
+    ... cx q[2],q[3];
+    ... cx q[3],q[4];
+    ... measure q -> c;
+    ... '''
+    >>> result = run_large_circuit_mps(qasm, k=4, seed=0)  # a 5-qubit GHZ state
+    >>> top2 = sorted(result.top_k_states, key=lambda t: -t[1])[:2]
+    >>> [bits for bits, _ in top2]
+    ['00000', '11111']
+    >>> all(abs(p - 0.5) < 1e-9 for _, p in top2)
+    True
+    """
+    n_qubits, raw_ops = _qasm_to_tuples(qasm_text)
+    if n_qubits < 1:
+        raise ValueError("circuit must declare at least 1 qubit")
+
+    ops = de.QuantumTranspiler.transpile(raw_ops)
+    mps = de.MPSSimulator(n_qubits)
+    mps.run_circuit_jit(ops)
+
+    idx, probs = mps.get_top_k_probable_states(k=k)
+
+    top_k_states = []
+    for i, p in zip(idx.tolist(), probs.tolist()):
+        native_bits = format(int(i), f'0{n_qubits}b')
+        qiskit_bits = native_bits[::-1]  # same MSB-first -> little-endian flip as _to_qiskit_bit_order
+        top_k_states.append((qiskit_bits, float(p)))
+    top_k_states.sort(key=lambda t: t[1], reverse=True)
+
+    return LargeScaleMPSResult(
+        ops=raw_ops,
+        n_qubits=n_qubits,
+        top_k_states=top_k_states,
+        k_requested=k,
+        mps_max_bond_used=mps.max_bond_used(),
+        mps_memory_mb=mps.memory_mb(),
+        mps_avg_jsd=mps.avg_jsd(),
+    )
+
+
+def run_bond_convergence_check(qasm_text: str, observables: list, bonds: list, tol: float = 1e-3):
+    """Runs the circuit at every bond dimension in `bonds` and checks
+    whether each observable's expectation value has actually converged
+    as bond dimension grows -- a single MPS run's own diagnostics
+    (avg_jsd, budget_violations) say nothing about whether a *specific*
+    observable has settled, since they are truncation-error proxies
+    averaged over the whole state, not the observable itself.
+
+    Thin wrapper around dense_evolution.backends.mps.bond_convergence:
+    parses qasm_text the same way as every other entry point here, then
+    delegates. See that function's own docstring for the "undecidable"
+    verdict (fires when chi_used at the top bond already equals its own
+    cap, i.e. truncation never had headroom to demonstrate convergence).
+    """
+    n_qubits, raw_ops = _qasm_to_tuples(qasm_text)
+    ops = de.QuantumTranspiler.transpile(raw_ops)
+    return de.backends.mps.bond_convergence(ops, n_qubits, observables, bonds, tol=tol)

dashboard_core/graphical_builder.py

@@ -0,0 +1,114 @@
+"""
+Turns the ops list produced by the graphical (drag-and-drop) circuit
+builder component into dense_evolution's own (name, *qubits[, param])
+gate tuples -- the same format dashboard_core.engine already runs on the
+real dense_evolution DenseSVSimulator (via dashboard_core.qasm_library.
+gate_tuples_to_qasm for the QASM round-trip). No separate execution path
+for graphically-built circuits, and no Qiskit QuantumCircuit ever built
+here: they go through the exact same engine as typed OpenQASM.
+"""
+
+import numpy as np
+
+__all__ = ['GATE_PALETTE', 'ops_to_native_tuples']
+
+# Palette offered by the drag-and-drop grid (dashboard_core.circuit_builder_component).
+# kind:
+#   'single'  -- dropped directly on one qubit's cell
+#   'control' -- the (.) end of a 2-qubit gate; pairs with a 'target' in the same column
+#   'target'  -- the other end of a 2-qubit gate, carries which gate (x/y/z -> cx/cy/cz)
+#   'swap'    -- two 'swap' markers in the same column form a SWAP
+GATE_PALETTE = [
+    {"id": "h", "label": "H", "kind": "single", "gate": "h"},
+    {"id": "x", "label": "X", "kind": "single", "gate": "x"},
+    {"id": "y", "label": "Y", "kind": "single", "gate": "y"},
+    {"id": "z", "label": "Z", "kind": "single", "gate": "z"},
+    {"id": "s", "label": "S", "kind": "single", "gate": "s"},
+    {"id": "sdg", "label": "S†", "kind": "single", "gate": "sdg"},
+    {"id": "t", "label": "T", "kind": "single", "gate": "t"},
+    {"id": "tdg", "label": "T†", "kind": "single", "gate": "tdg"},
+    {"id": "sx", "label": "√X", "kind": "single", "gate": "sx"},
+    {"id": "rx", "label": "Rx(π/2)", "kind": "single", "gate": "rx"},
+    {"id": "ry", "label": "Ry(π/2)", "kind": "single", "gate": "ry"},
+    {"id": "rz", "label": "Rz(π/2)", "kind": "single", "gate": "rz"},
+    {"id": "ctrl", "label": "●", "kind": "control", "gate": None},
+    {"id": "tgt_x", "label": "⊕", "kind": "target", "gate": "x"},
+    {"id": "tgt_z", "label": "● Z", "kind": "target", "gate": "z"},
+    {"id": "tgt_y", "label": "⊗ Y", "kind": "target", "gate": "y"},
+    {"id": "swap", "label": "×", "kind": "swap", "gate": None},
+]
+
+_SINGLE_QUBIT_METHODS = {"h", "x", "y", "z", "s", "sdg", "t", "tdg", "sx"}
+_ROTATION_METHODS = {"rx", "ry", "rz"}
+
+# Fixed rotation angle for graphically-placed Rx/Ry/Rz -- the grid has no
+# angle-entry UI yet (out of scope for this pass), so these place a real,
+# working pi/2 rotation rather than a fake/placeholder gate.
+_DEFAULT_ROTATION_ANGLE = np.pi / 2
+
+
+def ops_to_native_tuples(n_qubits: int, ops: list) -> list:
+    """Build dense_evolution's own (name, *qubits[, param]) gate tuples
+    from the builder's op list -- the same shape dashboard_core.engine's
+    QASMParser-based pipeline and qasm_library.gate_tuples_to_qasm both
+    already accept, and the same validation the old QuantumCircuit-based
+    version did (qubit range, unknown gate name), just performed by hand
+    instead of relying on Qiskit's own checks.
+
+    Parameters
+    ----------
+    n_qubits : int
+    ops : list[dict]
+        Each dict has 'gate' (one of the GATE_PALETTE gate ids: h/x/y/z/s/t/
+        rx/ry/rz/cx/cy/cz/swap) and 'qubits' (list[int]).
+
+    Notes
+    -----
+    A graphically-placed rx/ry/rz always gets a fixed pi/2 rotation angle
+    (_DEFAULT_ROTATION_ANGLE, prog.txt dashboard_core audit point 5d) --
+    the drag-and-drop grid has no angle-entry UI yet, so this places a
+    real, working rotation rather than a fake/placeholder one. A user
+    who drops an Rx expecting to pick its own angle should know this is
+    fixed, not something this function silently decided for them.
+
+    Returns
+    -------
+    list[tuple]
+        Pass to qasm_library.gate_tuples_to_qasm(tuples, n_qubits) for the
+        QASM text the rest of the Composer already runs on (measure_all
+        equivalent included there by default).
+
+    Examples
+    --------
+    >>> from dashboard_core.graphical_builder import ops_to_native_tuples
+    >>> ops = [{'gate': 'h', 'qubits': [0]}, {'gate': 'cx', 'qubits': [0, 1]}]
+    >>> ops_to_native_tuples(2, ops)
+    [('h', 0), ('cx', 0, 1)]
+    """
+    if n_qubits < 1:
+        raise ValueError("circuit must have at least 1 qubit")
+
+    tuples = []
+    for op in ops:
+        gate = op.get("gate")
+        qubits = op.get("qubits", [])
+        for q in qubits:
+            if not (0 <= q < n_qubits):
+                raise ValueError(f"qubit index {q} out of range for {n_qubits}-qubit circuit")
+
+        if gate in _SINGLE_QUBIT_METHODS:
+            (q,) = qubits
+            tuples.append((gate, q))
+        elif gate in _ROTATION_METHODS:
+            (q,) = qubits
+            tuples.append((gate, q, _DEFAULT_ROTATION_ANGLE))
+        elif gate == "swap":
+            a, b = qubits
+            tuples.append(("swap", a, b))
+        elif gate in ("cx", "cy", "cz"):
+            control, target = qubits
+            tuples.append((gate, control, target))
+        else:
+            raise ValueError(f"unknown gate from circuit builder: {gate!r}")
+
+    return tuples