compactq 0.1.0__py3-none-any.whl

compactq/__init__.py

@@ -0,0 +1,62 @@
+"""Q-PROOF Compact — the verified quantum circuit optimizer.
+
+Smaller circuits, proven.
+
+Smaller, shallower quantum circuits, exact by construction and verified
+before return.  Works standalone or alongside Qiskit.
+
+    >>> import compactq
+    >>> from compactq.benchmarks import qft
+    >>> opt = compactq.optimize(qft(4))
+    >>> opt.two_qubit_count() <= qft(4).two_qubit_count()
+    True
+"""
+from .circuit import Circuit, Gate
+from .optimize import optimize, optimize_deep
+from .search import optimize_search
+from .approximate import approximate
+from .target import Target, optimize_for, approximate_for_target
+from .mcx import expand_mcx, expand_mcp
+from .templates import template_pass
+from .stabilizer import clifford_equal, is_clifford
+from .io_qasm import from_qasm, from_qasm3, to_qasm
+from .errors import UnsupportedCircuitError
+from .symbolic import param, bind, structure_optimize
+from .verify_large import optimize_large, states_agree
+from .io_qasm3 import to_qasm3
+from .qiskit_bridge import from_qiskit, to_qiskit, compactq_pass
+from .hardware import exact_placement
+from .noise import NoiseModel, default_model
+from .suppress import (pauli_twirl, insert_dd, suppress_plan,
+                       suppress_execute, expand_for_suppression)
+from .mitigate import mitigate_counts, mitigate_mle
+from .adapters import RunTarget, qiskit_runtime, braket_device
+from .report import SuppressionReport
+from .simulate import simulate_counts
+from .stabsim import stab_sample
+from .zne import fold_global, zne_expectation, zne_execute
+from .cdr import cdr_execute, near_clifford_variants
+from .metrics import layer_fidelity, eplg, suppression_metrics
+from .shadows import shadow_snapshots, shadow_estimate_parity
+from .resources import resource_estimate, t_depth, rebase_cliffordt
+from .solvers import maxcut_qaoa, brute_force_maxcut
+from .simulate import statevector, exact_probabilities
+from . import benchmarks
+
+__version__ = "0.1.0"
+__all__ = ["Circuit", "Gate", "optimize", "optimize_deep", "optimize_search", "is_clifford", "clifford_equal", "approximate", "Target", "optimize_for", "approximate_for_target", "from_qasm3", "expand_mcx", "expand_mcp", "template_pass", "from_qasm", "to_qasm",
+           "to_qasm3", "benchmarks", "__version__", "param", "bind",
+            "structure_optimize", "optimize_large", "states_agree",
+            "UnsupportedCircuitError",
+            "NoiseModel", "default_model", "pauli_twirl", "insert_dd",
+            "suppress_plan", "suppress_execute", "expand_for_suppression",
+            "mitigate_counts", "mitigate_mle", "simulate_counts",
+            "SuppressionReport", "to_device",
+            "RunTarget", "qiskit_runtime", "braket_device", "stab_sample",
+            "fold_global", "zne_expectation", "zne_execute",
+            "cdr_execute", "near_clifford_variants", "statevector",
+            "exact_probabilities", "layer_fidelity", "eplg",
+            "suppression_metrics", "maxcut_qaoa", "brute_force_maxcut",
+            "shadow_snapshots", "shadow_estimate_parity",
+            "resource_estimate", "t_depth", "rebase_cliffordt",
+            "exact_placement"]

compactq/__main__.py

@@ -0,0 +1,210 @@
+"""compactq command line interface.
+
+Usage:
+  compactq INPUT.qasm [-o OUTPUT.qasm] [--stats] [--approx FIDELITY]
+             [--no-verify] [--native {cz,ecr,iswap}] [--json]
+
+Reads an OpenQASM 2.0 file, optimizes it, and writes the result (stdout by
+default).  Exit code is 0 on success.
+
+Verification policy (reported on stderr and in --json):
+  exact-unitary    whole-circuit dense proof (default, within the prover's
+                   qubit limit: 8 with the native kernels, 6 without)
+  randomized-exact large circuits: K=32 random-state verification
+                   (probabilistically exact; see compactq.verify_large)
+  approximate      --approx mode: per-block fidelity guarantees
+  unverified       --no-verify, or circuits beyond the randomized prover's
+                   reach (> 30 qubits)
+
+Trailing measurements in the input are dropped (the unitary core is
+optimized); mid-circuit measurement and reset are rejected.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+
+def _write_out(dest: str, text: str) -> None:
+    """Write CLI output to the user-specified destination safely: the
+    path is expanded and fully resolved (no ambiguity about where the
+    bytes land) and its parent directory must already exist."""
+    out_path = Path(dest).expanduser().resolve()
+    if not out_path.parent.is_dir():
+        raise SystemExit(f"--output directory does not exist: "
+                         f"{out_path.parent}")
+    out_path.write_text(text, encoding="utf-8")
+    print(f"compactq: wrote {out_path}", file=sys.stderr)
+
+
+def _stats_dict(circ):
+    return {
+        "gates": len(circ.ops),
+        "two_qubit": circ.two_qubit_count(),
+        "depth": circ.depth(),
+    }
+
+
+def _suppress_main(args, circ, to_qasm):
+    """--suppress: the automated suppression pipeline, offline."""
+    import json
+    import compactq
+    from compactq import default_model, NoiseModel
+    from compactq.suppress import suppress_plan
+
+    if args.noise:
+        with open(args.noise, "r", encoding="utf-8") as f:
+            noise = NoiseModel.from_dict(circ.num_qubits, json.load(f))
+    else:
+        noise = default_model(circ.num_qubits)
+
+    plan = suppress_plan(circ, noise, variants=max(1, args.variants),
+                         dd_sequence=args.dd_sequence)
+    report = plan["report"]
+    out = plan["variants"][0]
+
+    qasm = to_qasm(out)
+    if args.output:
+        _write_out(args.output, qasm)
+    else:
+        sys.stdout.write(qasm)
+
+    print(str(report), file=sys.stderr)
+    if args.report:
+        _write_out(args.report, json.dumps(report.to_dict(), indent=2) + "\n")
+
+    if args.json:
+        payload = {
+            "version": compactq.__version__,
+            "status": "suppressed",
+            "num_qubits": circ.num_qubits,
+            "variants": plan["num_variants"],
+            "dd_sequence": args.dd_sequence,
+            "mapping": plan["mapping"],
+            "before": _stats_dict(circ),
+            "after": _stats_dict(out),
+            "report": report.to_dict(),
+        }
+        sys.stdout.write(json.dumps(payload, indent=2) + "\n")
+    return 0
+
+
+def _optimize_dispatch(circ, approx, verify):
+    """Returns (circuit, proof_status, dense_limit).  Never raises on
+    circuit width: wide circuits fall back to unverified optimization
+    with an honest status instead of crashing."""
+    from compactq.equivalence import _MAX_QUBITS as dense_limit
+    if approx is not None:
+        from compactq.approximate import approximate
+        return approximate(circ, min_fidelity=approx), "approximate", dense_limit
+    if not verify:
+        from compactq import optimize_search
+        return optimize_search(circ, verify=False), "unverified", dense_limit
+    if circ.num_qubits <= dense_limit:
+        from compactq import optimize_search
+        return optimize_search(circ, verify=True), "exact-unitary", dense_limit
+    try:
+        from compactq.verify_large import optimize_large
+        out, st = optimize_large(circ)
+        if st == "exact":
+            return out, "randomized-exact", dense_limit
+        # randomized verification rejected the optimized circuit: the
+        # original is returned unoptimized rather than shipping unproven
+        return out, "verification-rejected (original returned)", dense_limit
+    except ValueError:
+        # beyond the randomized prover's reach: optimize without proof
+        from compactq import optimize_search
+        return optimize_search(circ, verify=False), "unverified", dense_limit
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="compactq",
+        description="compactq: the verified quantum circuit optimizer",
+    )
+    parser.add_argument("input", help="input OpenQASM 2.0 file ('-' = stdin)")
+    parser.add_argument("-o", "--output", help="output file (default: stdout)")
+    parser.add_argument("--stats", action="store_true",
+                        help="print before/after statistics to stderr")
+    parser.add_argument("--approx", type=float, default=None, metavar="FIDELITY",
+                        help="approximate mode: per-block fidelity floor "
+                             "(e.g. 0.99); trades bounded fidelity for fewer "
+                             "2-qubit gates")
+    parser.add_argument("--no-verify", action="store_true",
+                        help="skip the whole-circuit proof (large circuits "
+                             "automatically use randomized state verification)")
+    parser.add_argument("--native", default=None, choices=["cz", "ecr", "iswap"],
+                        help="re-express 2q gates in a machine-native basis")
+    parser.add_argument("--json", action="store_true",
+                        help="print a machine-readable result summary (JSON) "
+                             "to stdout; the QASM circuit is then written "
+                             "only when -o is given")
+    parser.add_argument("--suppress", action="store_true",
+                        help="run the error-suppression pipeline (optimize, "
+                             "layout/route, twirl, decouple) and emit the "
+                             "suppressed circuit plus a per-stage report")
+    parser.add_argument("--noise", default=None, metavar="JSON",
+                        help="with --suppress: NoiseModel calibrations "
+                             "(T1_us, T2_us, readout, gate_infidelity, "
+                             "drift_rate, durations_ns); defaults to a "
+                             "representative superconducting device")
+    parser.add_argument("--report", default=None, metavar="JSON",
+                        help="with --suppress: write the SuppressionReport "
+                             "artifact (per-stage proof levels) here")
+    parser.add_argument("--dd-sequence", default="auto",
+                        choices=["auto", "xy4", "xy8", "xzx", "pdd4"],
+                        help="dynamical-decoupling sequence family "
+                             "(default: auto)")
+    parser.add_argument("--variants", type=int, default=4, metavar="K",
+                        help="with --suppress: number of twirled variants "
+                             "to build (default 4)")
+    args = parser.parse_args(argv)
+
+    import compactq
+    from compactq import from_qasm, to_qasm
+
+    text = sys.stdin.read() if args.input == "-" else open(
+        args.input, "r", encoding="utf-8").read()
+    circ = from_qasm(text)
+
+    if args.suppress:
+        return _suppress_main(args, circ, to_qasm)
+
+    out, status, dense_limit = _optimize_dispatch(
+        circ, args.approx, verify=not args.no_verify)
+    if args.native is not None:
+        from compactq.native import rebase
+        out = rebase(out, args.native)
+
+    result = {
+        "version": compactq.__version__,
+        "status": status,
+        "num_qubits": circ.num_qubits,
+        "dense_proof_limit": dense_limit,
+        "native": args.native,
+        "before": _stats_dict(circ),
+        "after": _stats_dict(out),
+    }
+
+    if args.json:
+        import json
+        sys.stdout.write(json.dumps(result, indent=2) + "\n")
+        if args.output:
+            _write_out(Path(args.output), to_qasm(out))
+    else:
+        qasm = to_qasm(out)
+        if args.output:
+            _write_out(Path(args.output), qasm)
+        else:
+            sys.stdout.write(qasm)
+
+    print(f"compactq: proof status: {status}", file=sys.stderr)
+    if args.stats:
+        print(f"before: {circ.stats()}", file=sys.stderr)
+        print(f"after : {out.stats()}", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

compactq/adapters.py

@@ -0,0 +1,107 @@
+"""Thin execution adapters - the `execute(...)` box of the pipeline.
+
+Turn a hardware handle into the pair the suppression pipeline consumes:
+a `run_fn(circuit, *, seed, shots) -> counts` callable plus a NoiseModel
+ingested from the same device's calibrations.
+
+    from compactq import suppress_execute
+    from compactq.adapters import qiskit_runtime
+
+    rt = qiskit_runtime(backend)                 # BackendV2, incl. fakes
+    result = suppress_execute(circ, rt.noise_model, rt.run_fn)
+
+Every import beyond the standard library is lazy: the CORE stays
+zero-dependency, and adapters raise a clear RuntimeError when the
+optional stack (qiskit-ibm-runtime, amazon-braket-sdk) is missing.
+
+Counts convention: hardware APIs return most-significant-bit-first
+bitstrings; the adapters reverse them into compactq's little-endian
+convention (char i of the string is wire i).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable
+
+
+@dataclass
+class RunTarget:
+    """A ready-to-use execution target: callable + calibrations."""
+    run_fn: Callable
+    noise_model: object
+    name: str = "device"
+    meta: dict = field(default_factory=dict)
+
+
+def _reverse_counts(raw: dict, n: int) -> dict:
+    """qiskit/braket count strings are MSB-first; compactq wants char i =
+    wire i.  Truncate to n wires and reverse."""
+    out = {}
+    for s, c in raw.items():
+        clean = s.replace(" ", "")
+        if len(clean) < n:
+            continue
+        out[clean[::-1][:n]] = out.get(clean[::-1][:n], 0) + c
+    return out
+
+
+def qiskit_runtime(backend) -> RunTarget:
+    """Wrap a qiskit BackendV2 (real via qiskit-ibm-runtime, or a
+    fake-provider backend) into a RunTarget.  Uses SamplerV2; measurements
+    are appended to a copy of each submitted circuit."""
+    from .noise import NoiseModel
+    noise = NoiseModel.from_qiskit_backend(backend)
+    name = getattr(backend, "name", None) or str(getattr(backend,
+                                                         "backend_name", ""))
+    try:
+        from qiskit_ibm_runtime import SamplerV2
+        sampler = SamplerV2(mode=backend)
+    except Exception as e:
+        raise RuntimeError(
+            f"qiskit-ibm-runtime SamplerV2 unavailable for {name}: {e}. "
+            "Install qiskit-ibm-runtime or pass run_fn manually.") from e
+
+    def run_fn(circ, *, seed: int = 0, shots: int = 1024) -> dict:
+        from .qiskit_bridge import to_qiskit
+        qc = to_qiskit(circ)
+        qc.measure_all()
+        try:
+            job = sampler.run([qc], shots=shots)
+        except TypeError:
+            job = sampler.run([qc])          # some backends fix shots elsewhere
+        result = job.result()
+        data = result[0].data
+        raw = data.meas.get_counts() if hasattr(data, "meas") \
+            else data.get_counts()
+        return _reverse_counts(raw, circ.num_qubits)
+
+    return RunTarget(run_fn=run_fn, noise_model=noise,
+                     name=str(name), meta={"stack": "qiskit-ibm-runtime"})
+
+
+def braket_device(device) -> RunTarget:
+    """Wrap an Amazon Braket device (AwsDevice) into a RunTarget via the
+    QASM bridge.  Best-effort: exact kwargs vary across Braket SDK
+    versions; failures surface as RuntimeError from run_fn."""
+    from .noise import NoiseModel
+    name = getattr(device, "name", None) or str(device)
+    # Braket exposes device calibrations in its own schema; a full mapping
+    # lands with a hardware-verified run.  Defaults keep the pipeline usable.
+    noise = NoiseModel(getattr(device, "qubit_count", None) or 8)
+
+    def run_fn(circ, *, seed: int = 0, shots: int = 1024) -> dict:
+        try:
+            from braket.circuits import Circuit as BKCircuit
+        except Exception as e:
+            raise RuntimeError(
+                "amazon-braket-sdk not installed; pip install "
+                "amazon-braket-sdk to use braket_device().") from e
+        from .io_qasm import to_qasm
+        bk = BKCircuit.from_qasm(to_qasm(circ))
+        task = device.run(bk, shots=shots)
+        result = task.result()
+        raw = result.measurement_counts()
+        return _reverse_counts(raw, circ.num_qubits)
+
+    return RunTarget(run_fn=run_fn, noise_model=noise,
+                     name=str(name), meta={"stack": "amazon-braket-sdk"})

compactq/approximate.py

@@ -0,0 +1,27 @@
+"""Approximate optimization: trade a bounded, quantified amount of fidelity
+for fewer two-qubit gates.
+
+Two-qubit blocks are re-synthesized into the cheapest CX class whose average
+gate fidelity |Tr(U_ref^dag U)|/d (d = 4 for a two-qubit block) is at least
+`min_fidelity`.  Each synthesized block carries that per-block guarantee from
+the exact KAK fidelity table; the whole-circuit infidelity is therefore
+bounded by (number of approximated blocks) * (1 - min_fidelity).
+"""
+from __future__ import annotations
+
+from .circuit import Circuit
+from .search import optimize_search
+
+
+def approximate(circ: Circuit, min_fidelity: float = 0.999) -> Circuit:
+    """Approximately optimize `circ`, prioritizing 2-qubit gate count.
+
+    Per-block average gate fidelity is guaranteed >= min_fidelity; total
+    circuit infidelity is bounded by (#approximated blocks) * (1 -
+    min_fidelity).  An exact baseline is always computed first and an
+    approximate candidate is returned only when it is strictly smaller.
+    """
+    if not 0.0 < min_fidelity <= 1.0:
+        raise ValueError("min_fidelity must be in (0, 1]")
+    return optimize_search(circ, verify=None,
+                           fidelity_tolerance=min_fidelity)

compactq/bench.py

@@ -0,0 +1,116 @@
+"""Benchmark CLI: compactq vs. raw circuits (and vs. Qiskit when installed).
+
+Usage:
+    python -m compactq.bench [--quick] [--out FILE]
+
+Fairness rules: every optimizer receives the *same* input circuit (our QASM
+serialization), the same basis set, fixed seeds, and best-of-3 timings.
+"""
+from __future__ import annotations
+
+import argparse
+import time
+
+from .benchmarks import default_suite
+from .io_qasm import from_qasm, to_qasm
+from .optimize import optimize
+
+
+def _two_q(ops) -> int:
+    return sum(1 for g in ops if len(g.qubits) == 2)
+
+
+def _metrics(circ):
+    return len(circ.ops), _two_q(circ.ops), circ.depth()
+
+
+def _qiskit_baseline(qasm: str):
+    """Run Qiskit optimization_level=3 on the same QASM. Returns (gates, 2q, depth, ms) or None."""
+    try:
+        from qiskit import transpile
+        from qiskit import qasm2 as qk_qasm
+    except Exception:
+        return None
+    qc = qk_qasm.loads(qasm)
+    basis = ["h", "x", "y", "z", "s", "sdg", "t", "tdg", "rx", "ry", "rz", "p", "cx", "cz", "swap"]
+    best = None
+    for _ in range(3):
+        t0 = time.perf_counter()
+        out = transpile(qc, basis_gates=basis, optimization_level=3, seed_transpiler=42)
+        dt = (time.perf_counter() - t0) * 1000.0
+        best = dt if best is None else min(best, dt)
+    ops = out.count_ops()
+    total = int(sum(v for k, v in ops.items() if k not in ("barrier",)))
+    two_q = int(ops.get("cx", 0) + ops.get("cz", 0) + ops.get("swap", 0)
+                + ops.get("ecr", 0) + ops.get("rxx", 0))
+    depth = int(out.depth())
+    return total, two_q, depth, best
+
+
+def run_suite(quick: bool = False):
+    suite = default_suite()
+    if quick:
+        suite = {k: v for k, v in suite.items() if k in ("ghz-5", "qft-3", "clifford-ladder-4")}
+    rows = []
+    for name, circ in suite.items():
+        qasm = to_qasm(circ)
+        raw = _metrics(circ)
+
+        best_ms = None
+        for _ in range(3):
+            t0 = time.perf_counter()
+            opt = optimize(from_qasm(qasm), verify=circ.num_qubits <= 6)
+            dt = (time.perf_counter() - t0) * 1000.0
+            best_ms = dt if best_ms is None else min(best_ms, dt)
+        ours = _metrics(opt)
+
+        qk = _qiskit_baseline(qasm)
+        rows.append((name, raw, ours, best_ms, qk))
+    return rows
+
+
+def _fmt_row(name, raw, ours, ours_ms, qk):
+    def cell(v):
+        return str(v) if v is not None else "n/a"
+    line = f"| {name} | {raw[0]} / {raw[1]} / {raw[2]} | {ours[0]} / {ours[1]} / {ours[2]} | {ours_ms:.2f} |"
+    if qk is not None:
+        qt, q2, qd, qms = qk
+        gain = f"-{(1 - ours[1] / q2) * 100:.0f}%" if q2 else "n/a"
+        line += f" {qt} / {q2} / {qd} | {qms:.2f} | {gain} |"
+    return line
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(prog="compactq-bench", description=__doc__)
+    ap.add_argument("--quick", action="store_true", help="run a 3-circuit quick suite")
+    ap.add_argument("--out", default=None, help="also write the markdown table to FILE")
+    args = ap.parse_args()
+
+    rows = run_suite(quick=args.quick)
+    has_qk = rows and rows[0][4] is not None
+
+    lines = []
+    header = "| circuit | raw gates/2q/depth | compactq gates/2q/depth | compactq ms |"
+    sep = "|---|---|---|---|"
+    if has_qk:
+        header += " qiskit L3 gates/2q/depth | qiskit ms | 2q-gate gain vs qiskit |"
+        sep += "---|---|---|"
+    lines.append(header)
+    lines.append(sep)
+    for name, raw, ours, ms, qk in rows:
+        lines.append(_fmt_row(name, raw, ours, ms, qk))
+
+    table = "\n".join(lines)
+    print(table)
+    if args.out:
+        from pathlib import Path
+        out_path = Path(args.out).expanduser().resolve()
+        if not out_path.parent.is_dir():
+            raise SystemExit(f"--out directory does not exist: "
+                             f"{out_path.parent}")
+        out_path.write_text(table + "\n", encoding="utf-8")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

compactq/benchmarks.py

@@ -0,0 +1,110 @@
+"""Standard benchmark circuits, generated locally (no downloads needed)."""
+from __future__ import annotations
+
+import math
+import random
+
+from .circuit import Circuit, Gate
+
+
+def ghz(n: int) -> Circuit:
+    c = Circuit(n, [])
+    c.append(Gate("h", (), (0,)))
+    for k in range(1, n):
+        c.append(Gate("cx", (), (0, k)))
+    return c
+
+
+def _cp(c: Circuit, theta: float, ctrl: int, tgt: int) -> None:
+    """Controlled-phase via the standard 2-CX identity (exact up to phase)."""
+    c.append(Gate("p", (theta / 2,), (ctrl,)))
+    c.append(Gate("cx", (), (ctrl, tgt)))
+    c.append(Gate("p", (-theta / 2,), (tgt,)))
+    c.append(Gate("cx", (), (ctrl, tgt)))
+    c.append(Gate("p", (theta / 2,), (ctrl,)))
+
+
+def qft(n: int) -> Circuit:
+    c = Circuit(n, [])
+    for i in range(n):
+        c.append(Gate("h", (), (i,)))
+        for j in range(i + 1, n):
+            _cp(c, math.pi / (2 ** (j - i)), j, i)
+    return c
+
+
+def clifford_ladder(n: int, seed: int = 7) -> Circuit:
+    """Random Clifford circuit — the optimizer should compress these hard."""
+    rng = random.Random(seed)
+    c = Circuit(n, [])
+    for _ in range(3 * n):
+        pick = rng.random()
+        q = rng.randrange(n)
+        if pick < 0.45:
+            c.append(Gate(rng.choice(["h", "s", "sdg", "x", "z"]), (), (q,)))
+        else:
+            a = rng.randrange(n)
+            b = (a + 1 + rng.randrange(n - 1)) % n
+            c.append(Gate("cx", (), (a, b)))
+    return c
+
+
+def brickwork(n: int, layers: int, seed: int = 11) -> Circuit:
+    """Nearest-neighbour 2-qubit brickwork with rotations (hardware-friendly)."""
+    rng = random.Random(seed)
+    c = Circuit(n, [])
+    for _ in range(layers):
+        for q in range(n):
+            c.append(Gate(rng.choice(["rz", "rx", "ry"]), (rng.uniform(-3, 3),), (q,)))
+        for pair in range(0, n - 1, 2):
+            c.append(Gate("cx", (), (pair, pair + 1)))
+        for q in range(n):
+            c.append(Gate("rz", (rng.uniform(-3, 3),), (q,)))
+        for pair in range(1, n - 1, 2):
+            c.append(Gate("cx", (), (pair, pair + 1)))
+    return c
+
+
+def random_circuit(n: int, depth: int, seed: int = 0) -> Circuit:
+    rng = random.Random(seed)
+    c = Circuit(n, [])
+    for _ in range(depth):
+        pick = rng.random()
+        if pick < 0.30:
+            c.append(Gate(rng.choice(["h", "t", "tdg", "s", "x"]), (), (rng.randrange(n),)))
+        elif pick < 0.60:
+            c.append(Gate(rng.choice(["rx", "ry", "rz"]), (rng.uniform(-3, 3),), (rng.randrange(n),)))
+        elif pick < 0.92:
+            a = rng.randrange(n)
+            b = rng.randrange(n)
+            while b == a:
+                b = rng.randrange(n)
+            c.append(Gate("cx", (), (a, b)))
+        else:
+            a = rng.randrange(n)
+            b = rng.randrange(n)
+            while b == a:
+                b = rng.randrange(n)
+            c.append(Gate("swap", (), (a, b)))
+    return c
+
+
+def default_suite() -> dict:
+    suite = {
+        "ghz-5": ghz(5),
+        "qft-3": qft(3),
+        "qft-4": qft(4),
+        "clifford-ladder-4": clifford_ladder(4, seed=7),
+        "clifford-ladder-5": clifford_ladder(5, seed=13),
+        "brickwork-4x4": brickwork(4, 4, seed=11),
+        "random-4q-40": random_circuit(4, 40, seed=1),
+        "random-5q-60": random_circuit(5, 60, seed=2),
+    }
+    return suite
+
+
+def load_qasm(path: str) -> Circuit:
+    """Load a QASM2 file (convenience wrapper)."""
+    from .io_qasm import from_qasm
+    with open(path) as f:
+        return from_qasm(f.read())