qudenoise 0.1.0__py3-none-any.whl

qudenoise/__init__.py

@@ -0,0 +1,43 @@
+"""QuDenoise: pure-Python MPS quantum circuit simulator with noise and a QAE denoiser."""
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from . import backend, gates, noise, observables
+from .backend import (
+    get_backend,
+    get_rng,
+    gpu_available,
+    set_backend,
+    to_backend,
+    to_numpy,
+    use_backend,
+)
+from .circuit import Circuit, Op
+from .mps import MPS
+from .noise import KrausChannel
+from .qae import QAE
+from .simulator import ObservableResult, SimulationReport, Simulator
+
+__all__ = [
+    "__version__",
+    "backend",
+    "gates",
+    "noise",
+    "observables",
+    "get_backend",
+    "get_rng",
+    "gpu_available",
+    "set_backend",
+    "to_backend",
+    "to_numpy",
+    "use_backend",
+    "Circuit",
+    "Op",
+    "MPS",
+    "KrausChannel",
+    "QAE",
+    "Simulator",
+    "SimulationReport",
+    "ObservableResult",
+]

qudenoise/backend.py

@@ -0,0 +1,256 @@
+"""Array-backend abstraction layer (NumPy <-> CuPy).
+
+This is the *only* library module that imports NumPy. Every other module
+obtains the active array library through :func:`get_backend` so that all
+tensor code is device-agnostic::
+
+    from qudenoise.backend import get_backend as xp_
+    xp = xp_()
+    xp.einsum("ab,bc->ac", A, B)
+
+CuPy is strictly optional. It is imported lazily, only when GPU support is
+probed (``device="auto"``) or explicitly requested, so a NumPy-only
+installation imports and runs with no errors or warnings about CuPy.
+
+The active backend is process-global state (like matplotlib's backend).
+Use :func:`use_backend` for scoped switches.
+"""
+from __future__ import annotations
+
+import contextlib
+import logging
+import os
+from typing import Any, Iterator, Optional
+
+import numpy as _np
+
+logger = logging.getLogger("qudenoise")
+
+#: dtype used for all state tensors and gates.
+DTYPE = "complex128"
+
+_cp: Any = None  # the cupy module once successfully loaded
+_cupy_probed = False
+_cupy_error: Optional[str] = None
+
+_current: Any = _np
+_current_name = "numpy"
+
+_ALIASES = {
+    "numpy": "numpy",
+    "np": "numpy",
+    "cpu": "numpy",
+    "cupy": "cupy",
+    "cuda": "cupy",
+    "gpu": "cupy",
+}
+
+
+# --------------------------------------------------------------------------
+# CuPy detection
+# --------------------------------------------------------------------------
+def _load_cupy() -> Any:
+    """Import CuPy lazily. Returns the module or ``None``; never raises."""
+    global _cp, _cupy_probed, _cupy_error
+    if _cupy_probed:
+        return _cp
+    _cupy_probed = True
+    try:
+        import cupy  # type: ignore
+
+        if cupy.cuda.runtime.getDeviceCount() < 1:
+            raise RuntimeError("CuPy is installed but no CUDA device was found")
+        _cp = cupy
+    except Exception as exc:  # ImportError, CUDA runtime errors, ...
+        _cp = None
+        _cupy_error = f"{type(exc).__name__}: {exc}"
+    return _cp
+
+
+def gpu_available() -> bool:
+    """True if CuPy is importable *and* a CUDA device is visible."""
+    return _load_cupy() is not None
+
+
+def _is_cupy_array(x: Any) -> bool:
+    return type(x).__module__.split(".")[0] == "cupy"
+
+
+# --------------------------------------------------------------------------
+# Backend selection
+# --------------------------------------------------------------------------
+def _normalize(name: str) -> str:
+    try:
+        return _ALIASES[str(name).lower()]
+    except KeyError:
+        raise ValueError(
+            f"Unknown backend: {name!r} (expected 'numpy' or 'cupy')"
+        ) from None
+
+
+def set_backend(name: str) -> Any:
+    """Activate ``'numpy'`` or ``'cupy'`` (aliases: cpu / cuda / gpu).
+
+    Raises ``RuntimeError`` if CuPy is requested but unavailable.
+    Returns the activated array module.
+    """
+    global _current, _current_name
+    canon = _normalize(name)
+    if canon == "cupy":
+        cp = _load_cupy()
+        if cp is None:
+            raise RuntimeError(
+                "CuPy backend requested but CuPy is not installed or no GPU "
+                f"was detected ({_cupy_error}). Install a CuPy wheel matching "
+                "your CUDA toolkit, e.g. `pip install cupy-cuda12x`."
+            )
+        _current, _current_name = cp, "cupy"
+    else:
+        _current, _current_name = _np, "numpy"
+    if _debug_enabled():
+        validate_svd()
+    return _current
+
+
+def get_backend() -> Any:
+    """Return the active array module (``numpy`` or ``cupy``)."""
+    return _current
+
+
+def backend_name() -> str:
+    """``'numpy'`` or ``'cupy'``."""
+    return _current_name
+
+
+def is_gpu() -> bool:
+    return _current_name == "cupy"
+
+
+def resolve_device(device: str = "auto") -> str:
+    """Map a user-facing device string to a backend name.
+
+    ``"auto"`` -> CuPy when available, else NumPy (never fails).
+    ``"cpu"``/``"numpy"`` -> NumPy.
+    ``"cuda"``/``"gpu"``/``"cupy"`` -> CuPy, raising if unavailable.
+    """
+    if str(device).lower() == "auto":
+        return "cupy" if gpu_available() else "numpy"
+    canon = _normalize(device)
+    if canon == "cupy" and not gpu_available():
+        raise RuntimeError(
+            f"device={device!r} requested but CuPy/GPU is unavailable "
+            f"({_cupy_error}). Use device='auto' to fall back to CPU."
+        )
+    return canon
+
+
+def configure(device: str = "auto", *, log: bool = True) -> str:
+    """Resolve ``device``, activate it, and (optionally) log the choice.
+
+    Returns the active backend name.
+    """
+    name = resolve_device(device)
+    set_backend(name)
+    if log:
+        if name == "cupy":
+            logger.info("QuDenoise: running on GPU (CuPy)")
+        elif str(device).lower() == "auto":
+            logger.info("QuDenoise: no GPU/CuPy found, running on CPU (NumPy)")
+        else:
+            logger.info("QuDenoise: running on CPU (NumPy)")
+    return name
+
+
+@contextlib.contextmanager
+def use_backend(name: str) -> Iterator[Any]:
+    """Temporarily switch backend inside a ``with`` block."""
+    prev = _current_name
+    xp = set_backend(name)
+    try:
+        yield xp
+    finally:
+        set_backend(prev)
+
+
+# --------------------------------------------------------------------------
+# Host <-> device movement
+# --------------------------------------------------------------------------
+def to_backend(array: Any, dtype: Optional[str] = None) -> Any:
+    """Move / convert ``array`` onto the active backend."""
+    if _current_name == "cupy":
+        out = _current.asarray(array)  # numpy->cupy copies, cupy->cupy no-op
+    else:
+        out = _np.asarray(array.get() if _is_cupy_array(array) else array)
+    if dtype is not None:
+        out = out.astype(dtype, copy=False)
+    return out
+
+
+def to_numpy(array: Any) -> Any:
+    """Return a host ``numpy.ndarray`` regardless of where ``array`` lives."""
+    if _is_cupy_array(array):
+        return array.get()
+    return _np.asarray(array)
+
+
+# --------------------------------------------------------------------------
+# RNG
+# --------------------------------------------------------------------------
+def get_rng(seed: Optional[int] = None) -> Any:
+    """Backend-appropriate ``Generator`` (``default_rng``), explicitly seeded.
+
+    There is no global RNG state anywhere in the library: generators are
+    created here and passed explicitly to whoever needs randomness.
+    """
+    return _current.random.default_rng(seed)
+
+
+def spawn_seeds(seed: Optional[int], n: int) -> list[int]:
+    """Derive ``n`` statistically independent integer seeds from ``seed``.
+
+    Trajectory ``i`` always receives the same seed for a given master seed,
+    independent of how trajectories are scheduled across workers.
+    """
+    ss = _np.random.SeedSequence(seed)
+    return [int(child.generate_state(1, dtype="uint64")[0]) for child in ss.spawn(n)]
+
+
+def draw_uniform(rng: Any) -> float:
+    """One uniform ``[0, 1)`` sample as a Python float, on either backend."""
+    return float(rng.random())
+
+
+# --------------------------------------------------------------------------
+# SVD self-check
+# --------------------------------------------------------------------------
+def _debug_enabled() -> bool:
+    return os.environ.get("QUDENOISE_DEBUG", "").lower() in ("1", "true", "yes", "on")
+
+
+def validate_svd(tol: float = 1e-10, seed: int = 1234) -> None:
+    """Check ``linalg.svd`` on the active backend across several shapes.
+
+    A silently wrong SVD would corrupt every truncation step, so this runs
+    automatically on backend switches when ``QUDENOISE_DEBUG=1`` and can be
+    called explicitly at any time. Raises ``RuntimeError`` on failure.
+    """
+    xp = _current
+    rng = _np.random.default_rng(seed)
+    for shape in [(2, 2), (4, 4), (8, 4), (4, 8), (16, 16), (32, 8), (1, 4)]:
+        host = rng.normal(size=shape) + 1j * rng.normal(size=shape)
+        m = to_backend(host, DTYPE)
+        u, s, vh = xp.linalg.svd(m, full_matrices=False)
+        rec = (u * s) @ vh
+        err = float(abs(rec - m).max())
+        orth = float(abs(u.conj().T @ u - xp.eye(u.shape[1])).max())
+        unsorted = bool((s[:-1] < s[1:] - 1e-12).any())
+        if err >= tol or orth >= tol or unsorted:
+            raise RuntimeError(
+                f"SVD self-check failed on backend {_current_name!r} for shape "
+                f"{shape}: reconstruction error {err:.2e}, "
+                f"orthogonality error {orth:.2e}, unsorted={unsorted}"
+            )
+
+
+if _debug_enabled():  # opt-in import-time check
+    validate_svd()

qudenoise/circuit.py

@@ -0,0 +1,362 @@
+"""Circuit builder and compiler.
+
+A :class:`Circuit` is a lightweight, backend-independent list of instructions.
+:meth:`Circuit.compile` turns it into a flat, inspectable list of
+``Op(op_type, qubits, data, name)`` records that the simulator consumes:
+
+* ``op_type == "gate"``  -> ``data`` is a matrix (``2x2`` or ``4x4``) on the
+  active backend, ``qubits`` has length 1 or 2.
+* ``op_type == "noise"`` -> ``data`` is a :class:`~qudenoise.noise.KrausChannel`.
+
+Non-adjacent two-qubit operations are made adjacent by wrapping them in SWAP
+chains. Every insertion is logged (``logging`` INFO on the ``qudenoise``
+logger) and recorded in :attr:`Circuit.routing_log`.
+"""
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any, Dict, List, NamedTuple, Optional, Sequence, Tuple, Union
+
+from . import gates as G
+from . import noise as N
+from .backend import DTYPE, to_backend, to_numpy
+
+logger = logging.getLogger("qudenoise")
+
+
+class Op(NamedTuple):
+    """One compiled operation."""
+
+    op_type: str  # "gate" | "noise"
+    qubits: Tuple[int, ...]
+    data: Any  # matrix (gate) or KrausChannel (noise)
+    name: str = ""
+
+
+@dataclass(frozen=True)
+class Instruction:
+    kind: str  # "gate" | "noise"
+    name: str
+    qubits: Tuple[int, ...]
+    params: Tuple[float, ...] = ()
+    payload: Any = None  # host matrix for custom unitaries / KrausChannel for noise
+
+
+# inverse rules for named gates
+_SELF_INVERSE = {"i", "x", "y", "z", "h", "cnot", "cz", "swap"}
+_DAGGER_PAIRS = {"s": "sdg", "sdg": "s", "t": "tdg", "tdg": "t"}
+_NEGATE_PARAMS = {"rx", "ry", "rz", "p", "rxx", "ryy", "rzz", "entangler"}
+
+
+class Circuit:
+    """Quantum circuit on ``n_qubits`` qubits (qubit 0 = leftmost MPS site)."""
+
+    def __init__(self, n_qubits: int) -> None:
+        if n_qubits < 1:
+            raise ValueError("n_qubits must be >= 1")
+        self.n_qubits = int(n_qubits)
+        self._instructions: List[Instruction] = []
+        self.routing_log: List[str] = []
+        self.n_swaps_inserted: int = 0
+
+    # ------------------------------------------------------------------
+    # container protocol
+    # ------------------------------------------------------------------
+    def __len__(self) -> int:
+        return len(self._instructions)
+
+    def __iter__(self):
+        return iter(self._instructions)
+
+    def __repr__(self) -> str:
+        return f"Circuit(n_qubits={self.n_qubits}, n_instructions={len(self)})"
+
+    @property
+    def instructions(self) -> List[Instruction]:
+        return list(self._instructions)
+
+    @property
+    def has_noise(self) -> bool:
+        return any(ins.kind == "noise" for ins in self._instructions)
+
+    # ------------------------------------------------------------------
+    # building
+    # ------------------------------------------------------------------
+    def _check(self, qubits: Sequence[int]) -> Tuple[int, ...]:
+        qs = tuple(int(q) for q in qubits)
+        if len(set(qs)) != len(qs):
+            raise ValueError(f"Repeated qubit in {qs}")
+        for q in qs:
+            if not 0 <= q < self.n_qubits:
+                raise ValueError(f"Qubit {q} out of range for a {self.n_qubits}-qubit circuit")
+        return qs
+
+    def add_gate(self, name: str, qubits: Sequence[int], *params: float) -> "Circuit":
+        """Append a named gate from :data:`qudenoise.gates.GATES`."""
+        key = G.canonical_name(name)
+        if key not in G.GATES:
+            raise ValueError(f"Unknown gate {name!r}. Known gates: {sorted(G.GATES)}")
+        spec = G.GATES[key]
+        qs = self._check(qubits)
+        if len(qs) != spec.n_qubits:
+            raise ValueError(f"Gate {key!r} acts on {spec.n_qubits} qubit(s), got {len(qs)}")
+        if len(params) != spec.n_params:
+            raise ValueError(f"Gate {key!r} takes {spec.n_params} parameter(s), got {len(params)}")
+        self._instructions.append(Instruction("gate", key, qs, tuple(float(p) for p in params)))
+        return self
+
+    def unitary(self, matrix: Any, qubits: Sequence[int], name: str = "unitary") -> "Circuit":
+        """Append an arbitrary 1- or 2-qubit unitary (columns = input basis, big-endian)."""
+        qs = self._check(qubits)
+        host = to_numpy(matrix).astype("complex128")
+        if len(qs) not in (1, 2) or host.shape != (2 ** len(qs),) * 2:
+            raise ValueError("unitary needs a 2x2 (1 qubit) or 4x4 (2 qubit) matrix")
+        self._instructions.append(Instruction("gate", name, qs, (), host))
+        return self
+
+    def add_noise_channel(
+        self,
+        channel: Union[str, N.KrausChannel],
+        qubits: Sequence[int],
+        params: Optional[float] = None,
+    ) -> "Circuit":
+        """Append a noise channel.
+
+        ``channel`` is either a :class:`~qudenoise.noise.KrausChannel` or a
+        name (``"depolarizing"``, ``"amplitude_damping"``, ``"phase_damping"``,
+        ``"bit_flip"``, ``"phase_flip"``) together with its error
+        probability/rate in ``params``.
+        """
+        qs = self._check(qubits)
+        if isinstance(channel, str):
+            if params is None:
+                raise ValueError(f"Channel {channel!r} needs its error rate in `params`")
+            ch = N.make_channel(channel, float(params), n_qubits=len(qs))
+        else:
+            ch = channel
+        if ch.n_qubits != len(qs):
+            raise ValueError(f"{ch.name} acts on {ch.n_qubits} qubit(s), got {len(qs)}")
+        self._instructions.append(Instruction("noise", ch.name, qs, (), ch))
+        return self
+
+    # single-qubit gates
+    def i(self, q: int) -> "Circuit":
+        return self.add_gate("i", [q])
+
+    def x(self, q: int) -> "Circuit":
+        return self.add_gate("x", [q])
+
+    def y(self, q: int) -> "Circuit":
+        return self.add_gate("y", [q])
+
+    def z(self, q: int) -> "Circuit":
+        return self.add_gate("z", [q])
+
+    def h(self, q: int) -> "Circuit":
+        return self.add_gate("h", [q])
+
+    def s(self, q: int) -> "Circuit":
+        return self.add_gate("s", [q])
+
+    def sdg(self, q: int) -> "Circuit":
+        return self.add_gate("sdg", [q])
+
+    def t(self, q: int) -> "Circuit":
+        return self.add_gate("t", [q])
+
+    def tdg(self, q: int) -> "Circuit":
+        return self.add_gate("tdg", [q])
+
+    def rx(self, q: int, theta: float) -> "Circuit":
+        return self.add_gate("rx", [q], theta)
+
+    def ry(self, q: int, theta: float) -> "Circuit":
+        return self.add_gate("ry", [q], theta)
+
+    def rz(self, q: int, theta: float) -> "Circuit":
+        return self.add_gate("rz", [q], theta)
+
+    def p(self, q: int, phi: float) -> "Circuit":
+        return self.add_gate("p", [q], phi)
+
+    # two-qubit gates
+    def cnot(self, control: int, target: int) -> "Circuit":
+        return self.add_gate("cnot", [control, target])
+
+    cx = cnot
+
+    def cz(self, a: int, b: int) -> "Circuit":
+        return self.add_gate("cz", [a, b])
+
+    def swap(self, a: int, b: int) -> "Circuit":
+        return self.add_gate("swap", [a, b])
+
+    def rxx(self, a: int, b: int, theta: float) -> "Circuit":
+        return self.add_gate("rxx", [a, b], theta)
+
+    def ryy(self, a: int, b: int, theta: float) -> "Circuit":
+        return self.add_gate("ryy", [a, b], theta)
+
+    def rzz(self, a: int, b: int, theta: float) -> "Circuit":
+        return self.add_gate("rzz", [a, b], theta)
+
+    def entangler(self, a: int, b: int, ax: float, ay: float, az: float) -> "Circuit":
+        return self.add_gate("entangler", [a, b], ax, ay, az)
+
+    # noise shortcuts
+    def depolarizing(self, qubits: Union[int, Sequence[int]], p: float) -> "Circuit":
+        return self.add_noise_channel("depolarizing", _as_tuple(qubits), p)
+
+    def amplitude_damping(self, q: int, gamma: float) -> "Circuit":
+        return self.add_noise_channel("amplitude_damping", [q], gamma)
+
+    def phase_damping(self, q: int, lam: float) -> "Circuit":
+        return self.add_noise_channel("phase_damping", [q], lam)
+
+    def bit_flip(self, q: int, p: float) -> "Circuit":
+        return self.add_noise_channel("bit_flip", [q], p)
+
+    def phase_flip(self, q: int, p: float) -> "Circuit":
+        return self.add_noise_channel("phase_flip", [q], p)
+
+    # ------------------------------------------------------------------
+    # composition
+    # ------------------------------------------------------------------
+    def extend(self, other: "Circuit") -> "Circuit":
+        """Append all instructions of ``other`` (same qubit count required)."""
+        if other.n_qubits != self.n_qubits:
+            raise ValueError("Circuits act on different numbers of qubits")
+        self._instructions.extend(other._instructions)
+        return self
+
+    def copy(self) -> "Circuit":
+        new = Circuit(self.n_qubits)
+        new._instructions = list(self._instructions)
+        return new
+
+    def inverse(self) -> "Circuit":
+        """The adjoint circuit (reversed order, inverted gates). Noise is not invertible."""
+        inv = Circuit(self.n_qubits)
+        for ins in reversed(self._instructions):
+            if ins.kind == "noise":
+                raise ValueError("Cannot invert a circuit containing noise channels")
+            if ins.payload is not None:
+                inv._instructions.append(
+                    Instruction("gate", ins.name + "^dag", ins.qubits, (), ins.payload.conj().T)
+                )
+            elif ins.name in _SELF_INVERSE:
+                inv._instructions.append(ins)
+            elif ins.name in _DAGGER_PAIRS:
+                inv._instructions.append(Instruction("gate", _DAGGER_PAIRS[ins.name], ins.qubits))
+            elif ins.name in _NEGATE_PARAMS:
+                inv._instructions.append(
+                    Instruction("gate", ins.name, ins.qubits, tuple(-p for p in ins.params))
+                )
+            else:  # pragma: no cover - registry/inverse tables out of sync
+                raise ValueError(f"No inverse rule for gate {ins.name!r}")
+        return inv
+
+    # ------------------------------------------------------------------
+    # compile
+    # ------------------------------------------------------------------
+    def compile(self, route: bool = True) -> List[Op]:
+        """Compile to an ordered list of :class:`Op` on the active backend.
+
+        With ``route=True`` non-adjacent two-qubit operations are wrapped in SWAP
+        chains (logged, and recorded in ``self.routing_log``). With
+        ``route=False`` they are passed through unchanged (used by the dense
+        reference simulator, which needs no routing).
+        """
+        self.routing_log = []
+        self.n_swaps_inserted = 0
+        ops: List[Op] = []
+        swap = None
+        for ins in self._instructions:
+            if ins.kind == "gate":
+                if ins.payload is not None:
+                    data = to_backend(ins.payload, DTYPE)
+                else:
+                    data = G.get_gate(ins.name, *ins.params)
+            else:
+                data = ins.payload
+            op = Op(ins.kind, ins.qubits, data, ins.name)
+            if len(ins.qubits) == 2 and abs(ins.qubits[0] - ins.qubits[1]) > 1 and route:
+                if swap is None:
+                    swap = G.SWAP()
+                ops.extend(self._route(op, swap))
+            else:
+                ops.append(op)
+        return ops
+
+    def _route(self, op: Op, swap: Any) -> List[Op]:
+        a, b = op.qubits
+        d = abs(a - b)
+        step = 1 if a < b else -1
+        # move qubit `a` next to `b`
+        path = [(a + step * k, a + step * (k + 1)) for k in range(d - 1)]
+        target = (b - step, b)
+        n_new = 2 * len(path)
+        msg = (
+            f"Routing non-adjacent {op.name}{op.qubits}: inserting {n_new} SWAPs "
+            f"(qubit {a} -> position {b - step}, then back)"
+        )
+        logger.info(msg)
+        self.routing_log.append(msg)
+        self.n_swaps_inserted += n_new
+        out = [Op("gate", pair, swap, "swap") for pair in path]
+        out.append(Op(op.op_type, target, op.data, op.name))
+        out.extend(Op("gate", pair, swap, "swap") for pair in reversed(path))
+        return out
+
+    # ------------------------------------------------------------------
+    # (de)serialization for the CLI
+    # ------------------------------------------------------------------
+    def to_dict(self) -> Dict[str, Any]:
+        ops: List[Dict[str, Any]] = []
+        for ins in self._instructions:
+            if ins.kind == "gate":
+                if ins.payload is not None:
+                    raise ValueError("Custom unitaries are not JSON-serializable")
+                ops.append({"gate": ins.name, "qubits": list(ins.qubits), "params": list(ins.params)})
+            else:
+                ch = ins.payload
+                if len(ch.params) != 1:
+                    raise ValueError("Only named single-parameter channels are serializable")
+                ops.append(
+                    {
+                        "noise": ins.name,
+                        "qubits": list(ins.qubits),
+                        "param": next(iter(ch.params.values())),
+                    }
+                )
+        return {"n_qubits": self.n_qubits, "ops": ops}
+
+    @classmethod
+    def from_dict(cls, spec: Dict[str, Any], n_qubits: Optional[int] = None) -> "Circuit":
+        """Build a circuit from ``{"n_qubits": N, "ops": [...]}``.
+
+        Each op is ``{"gate": name, "qubits": [...], "params": [...]}`` or
+        ``{"noise": name, "qubits": [...], "param": rate}`` (``p`` / ``gamma`` /
+        ``lam`` are accepted as synonyms of ``param``).
+        """
+        n = n_qubits if n_qubits is not None else spec.get("n_qubits")
+        if n is None:
+            raise ValueError("Circuit spec has no 'n_qubits' and none was supplied")
+        circ = cls(int(n))
+        for i, op in enumerate(spec.get("ops", [])):
+            try:
+                if "gate" in op:
+                    circ.add_gate(op["gate"], op["qubits"], *op.get("params", []))
+                elif "noise" in op:
+                    rate = next(op[k] for k in ("param", "p", "gamma", "lam") if k in op)
+                    circ.add_noise_channel(op["noise"], op["qubits"], rate)
+                else:
+                    raise ValueError("op needs a 'gate' or 'noise' key")
+            except (KeyError, StopIteration, ValueError) as exc:
+                raise ValueError(f"Bad circuit op #{i} {op!r}: {exc}") from exc
+        return circ
+
+
+def _as_tuple(qubits: Union[int, Sequence[int]]) -> Tuple[int, ...]:
+    return (int(qubits),) if isinstance(qubits, int) else tuple(qubits)