quantbom 0.6.0__py3-none-any.whl

quantbom/_circuit.py

@@ -0,0 +1,77 @@
+"""Preconditions on the circuit being certified (HARNESS_KITS_PLAN.md K0).
+
+The certified object must be the circuit that ran. Two properties decide what
+the harness can honestly say about it, before any evidence is written:
+
+  * **closed** — every parameter bound. An unbound `Parameter` cannot be
+    executed; certifying it once produced a "measured" result for a run that
+    never happened, and QBOM-BENCH-02 then blamed the circuit. Refused here.
+  * **dynamic** — mid-circuit measurement or reset, or classical control flow
+    (`if_test`, `while_loop`, `for_loop`, `switch`). Accepted (decision
+    2 Oct 2026), and recorded, because it changes how the circuit can be
+    executed (qiskit-aer) and proved equivalent (QCEC's dynamic-circuit
+    transformation).
+"""
+from __future__ import annotations
+
+from typing import Any
+
+CONTROL_FLOW = {"if_else", "while_loop", "for_loop", "switch_case", "box"}
+_PASSIVE = {"barrier", "delay"}
+
+
+def inspect_circuit(qc: Any) -> dict[str, Any]:
+    """{'unbound_parameters': [...], 'dynamic': bool, 'dynamic_features': [...]}."""
+    features: set[str] = set()
+    measured: set[int] = set()  # qubits measured so far
+    touched: set[int] = set()   # qubits any operation has acted on
+    index = {q: i for i, q in enumerate(qc.qubits)}
+    for inst in qc.data:
+        name = inst.operation.name
+        qubits = [index[q] for q in inst.qubits]
+        if name in CONTROL_FLOW:
+            features.add("classical-control-flow")
+        elif name == "measure":
+            measured.update(qubits)
+        elif name == "reset":
+            if any(q in touched for q in qubits):
+                features.add("mid-circuit-reset")
+        elif name not in _PASSIVE and any(q in measured for q in qubits):
+            features.add("mid-circuit-measurement")
+        if name in CONTROL_FLOW and measured:
+            features.add("mid-circuit-measurement")
+        touched.update(qubits)
+    return {
+        "unbound_parameters": sorted(str(p) for p in getattr(qc, "parameters", ())),
+        "dynamic": bool(features),
+        "dynamic_features": sorted(features),
+    }
+
+
+def require_closed(info: dict[str, Any]) -> None:
+    refuse_open(info["unbound_parameters"])
+
+
+def refuse_dynamic(features: list[str], framework: str) -> None:
+    """A dynamic program from an adapter that does not claim dynamic support.
+
+    The adapter's lowering is conformance-tested for static circuits only, so
+    certifying this program would rest on an unverified translation. Refused
+    with the same wording for every framework; Qiskit input is accepted and
+    other frameworks gain support through their own conformance fixture (C7)."""
+    if features:
+        raise ValueError(
+            f"{framework} programs with {', '.join(features)} are not supported yet: the {framework} adapter's "
+            "lowering is conformance-tested for static circuits only, so a dynamic circuit cannot be certified "
+            "on it. Dynamic circuits are accepted as Qiskit input (qiskit.QuantumCircuit)"
+        )
+
+
+def refuse_open(unbound: list[str], how: str = "qc.assign_parameters({...})") -> None:
+    """One refusal, worded the same for every framework."""
+    if unbound:
+        shown = ", ".join(unbound[:5]) + (" …" if len(unbound) > 5 else "")
+        raise ValueError(
+            f"the circuit has {len(unbound)} unbound parameter(s) ({shown}). Bind them before certifying "
+            f"(e.g. {how}): the certified circuit must be the circuit that ran"
+        )