qcoder 0.1.0a0__py3-none-any.whl

qcoder/pipelines/analyze.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from pathlib import Path
+
+from qcoder.core.run_config import RunConfig
+from qcoder.engines.feature_extraction.extractor import CircuitExample, extract_example
+
+
+@dataclass(frozen=True)
+class AnalyzeReport:
+    example: CircuitExample
+    run_config: RunConfig
+    mirror_metadata: dict | None = None  # when --mirror-artifacts-dir used
+
+    def to_json_dict(self) -> dict:
+        ex = self.example
+        out = {
+            "circuit_id": ex.id,
+            "circuit_name": ex.name,
+            "function_hint": ex.function_hint,
+            "function_source": ex.function_source,
+            "qasm_path": ex.qasm_path,
+            "source_format": ex.ir.source_format,
+            "n_qubits": ex.ir.n_qubits,
+            "n_cbits": ex.ir.n_cbits,
+            "n_ops": ex.ir.n_ops,
+            "run_config": self.run_config.to_dict(),
+            "features": ex.global_features.to_dict(),
+        }
+        if self.mirror_metadata is not None:
+            out["adjoint_supported"] = self.mirror_metadata["adjoint_supported"]
+            out["adjoint_reason"] = self.mirror_metadata["adjoint_reason"]
+            if self.mirror_metadata.get("mirror_qasm_ref") is not None:
+                out["mirror_qasm_ref"] = self.mirror_metadata["mirror_qasm_ref"]
+        return out
+
+
+def analyze_qasm(
+    qasm_path: str,
+    *,
+    circuit_id: str | None = None,
+    circuit_name: str | None = None,
+    processor: str | None = None,
+    backend: str | None = None,
+    precision: str | None = None,
+    threshold: float | None = None,
+    prediction_artifact_path: str | None = None,
+    prediction_allow_schema_mismatch: bool | None = None,
+    prediction_fidelity_target: float | None = None,
+    prediction_fidelity_metric: str | None = None,
+    mirror_artifacts_dir: str | None = None,
+) -> AnalyzeReport:
+    ex = extract_example(qasm_path, circuit_id=circuit_id, circuit_name=circuit_name)
+    rc = RunConfig.from_raw(
+        processor=processor,
+        backend=backend,
+        precision=precision,
+        threshold=threshold,
+        prediction_artifact_path=prediction_artifact_path,
+        prediction_allow_schema_mismatch=prediction_allow_schema_mismatch,
+        prediction_fidelity_target=prediction_fidelity_target,
+        prediction_fidelity_metric=prediction_fidelity_metric,
+    )
+    mirror_metadata = None
+    if mirror_artifacts_dir:
+        from qcoder.core.qasm2.adjoint_eligibility import check_adjoint_eligibility
+
+        qasm_text = Path(qasm_path).read_text(encoding="utf-8", errors="replace")
+        content_hash = hashlib.sha256(qasm_text.encode("utf-8")).hexdigest()
+        eligibility = check_adjoint_eligibility(qasm_text, include_mirror_qasm=True)
+        mirror_qasm_ref = None
+        if eligibility.adjoint_supported and eligibility.mirror_qasm:
+            Path(mirror_artifacts_dir).mkdir(parents=True, exist_ok=True)
+            mirror_path = Path(mirror_artifacts_dir) / f"{content_hash}__mirror.qasm"
+            mirror_path.write_text(eligibility.mirror_qasm, encoding="utf-8")
+            mirror_qasm_ref = f"{content_hash}__mirror.qasm"
+        mirror_metadata = {
+            "adjoint_supported": eligibility.adjoint_supported,
+            "adjoint_reason": eligibility.adjoint_reason,
+            "mirror_qasm_ref": mirror_qasm_ref,
+        }
+    return AnalyzeReport(example=ex, run_config=rc, mirror_metadata=mirror_metadata)
+
+
+def analyze_qasm_json(
+    qasm_path: str,
+    *,
+    circuit_id: str | None = None,
+    circuit_name: str | None = None,
+    processor: str | None = None,
+    backend: str | None = None,
+    precision: str | None = None,
+    threshold: float | None = None,
+    prediction_artifact_path: str | None = None,
+    prediction_allow_schema_mismatch: bool | None = None,
+    prediction_fidelity_target: float | None = None,
+    prediction_fidelity_metric: str | None = None,
+    mirror_artifacts_dir: str | None = None,
+) -> dict:
+    """
+    Run analyze and return JSON-serializable dict. When prediction_artifact_path is set,
+    load artifact, run prediction engine, and attach prediction_model block next to features.
+    When mirror_artifacts_dir is set, compute adjoint eligibility and optionally write mirror QASM.
+    """
+    report = analyze_qasm(
+        qasm_path,
+        circuit_id=circuit_id,
+        circuit_name=circuit_name,
+        processor=processor,
+        backend=backend,
+        precision=precision,
+        threshold=threshold,
+        prediction_artifact_path=prediction_artifact_path,
+        prediction_allow_schema_mismatch=prediction_allow_schema_mismatch,
+        prediction_fidelity_target=prediction_fidelity_target,
+        prediction_fidelity_metric=prediction_fidelity_metric,
+        mirror_artifacts_dir=mirror_artifacts_dir,
+    )
+    out = report.to_json_dict()
+    if report.run_config.prediction_artifact_path:
+        from qcoder.engines.prediction_model.engine import predict
+
+        pred = predict(
+            out,
+            artifact_path=report.run_config.prediction_artifact_path,
+            allow_schema_mismatch=report.run_config.prediction_allow_schema_mismatch,
+        )
+        out["prediction_model"] = pred
+    return out

qcoder/pipelines/batch.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from qcoder.pipelines.analyze import analyze_qasm
+
+
+@dataclass
+class BatchItemResult:
+    qasm_path: str
+    report: dict  # same structure as AnalyzeReport.to_json_dict()
+
+
+def analyze_directory(
+    circuits_dir: str,
+    *,
+    processor: str | None = None,
+    backend: str | None = None,
+    precision: str | None = None,
+    threshold: float | None = None,
+    recursive: bool = True,
+    pattern: str = "*.qasm",
+    fail_fast: bool = True,
+    mirror_artifacts_dir: str | None = None,
+) -> list[dict]:
+    root = Path(circuits_dir)
+    if not root.is_dir():
+        raise NotADirectoryError(f"Not a directory: {circuits_dir}")
+
+    if recursive:
+        paths = sorted(root.rglob(pattern), key=str)
+    else:
+        paths = sorted(root.glob(pattern), key=str)
+
+    # only files (rglob/glob can return dirs if pattern allows)
+    paths = [p for p in paths if p.is_file()]
+
+    results: list[dict] = []
+    for p in paths:
+        path_str = str(p)
+        try:
+            report = analyze_qasm(
+                path_str,
+                processor=processor,
+                backend=backend,
+                precision=precision,
+                threshold=threshold,
+                mirror_artifacts_dir=mirror_artifacts_dir,
+            )
+            results.append(report.to_json_dict())
+        except Exception as e:
+            if fail_fast:
+                raise
+            results.append({"qasm_path": path_str, "error": str(e)})
+    return results

qcoder/tools/analyze.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable
+
+
+@dataclass(frozen=True)
+class QasmAnalysis:
+    path: str
+    format: str  # "qasm2" | "qasm3" | "unknown"
+    lines: int
+    bytes: int
+    gate_lines: int
+    measure_lines: int
+    include_lines: int
+    comment_lines: int
+
+    def to_dict(self) -> dict:
+        return {
+            "path": self.path,
+            "format": self.format,
+            "lines": self.lines,
+            "bytes": self.bytes,
+            "gate_lines": self.gate_lines,
+            "measure_lines": self.measure_lines,
+            "include_lines": self.include_lines,
+            "comment_lines": self.comment_lines,
+        }
+
+
+def _read_text(path: Path) -> str:
+    return path.read_text(encoding="utf-8", errors="replace")
+
+
+def _detect_format(lines: Iterable[str]) -> str:
+    for raw in lines:
+        s = raw.strip()
+        if not s or s.startswith("//"):
+            continue
+        if s.startswith("OPENQASM 3"):
+            return "qasm3"
+        if s.startswith("OPENQASM 2") or s.startswith("OPENQASM 2."):
+            return "qasm2"
+        break
+    return "unknown"
+
+
+def analyze_qasm_file(path: str) -> QasmAnalysis:
+    p = Path(path)
+    text = _read_text(p)
+    lines = text.splitlines()
+
+    fmt = _detect_format(lines)
+
+    comment_lines = 0
+    include_lines = 0
+    gate_lines = 0
+    measure_lines = 0
+
+    for raw in lines:
+        s = raw.strip()
+        if not s:
+            continue
+        if s.startswith("//"):
+            comment_lines += 1
+            continue
+        if s.startswith("include "):
+            include_lines += 1
+            continue
+        if "measure" in s and s.endswith(";"):
+            measure_lines += 1
+            continue
+        if s.endswith(";"):
+            head = s.split()[0]
+            if head not in {"OPENQASM", "qreg", "creg", "qubit", "bit", "let", "def", "gate", "opaque"}:
+                gate_lines += 1
+
+    return QasmAnalysis(
+        path=str(p),
+        format=fmt,
+        lines=len(lines),
+        bytes=p.stat().st_size,
+        gate_lines=gate_lines,
+        measure_lines=measure_lines,
+        include_lines=include_lines,
+        comment_lines=comment_lines,
+    )

qcoder/tools/analyze_shot_scaling.py

@@ -0,0 +1,239 @@
+"""
+Analyze whether forward execution time scales linearly with shots for a single circuit
+using one or more run-record JSONL files. Stdlib only.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+
+def _normalize_path(p: str | None) -> str:
+    if not p or not str(p).strip():
+        return ""
+    return os.path.normpath(os.path.abspath(str(p).strip()))
+
+
+def _sha256_file(path: str | Path) -> str:
+    h = hashlib.sha256()
+    p = Path(path)
+    with p.open("rb") as f:
+        for chunk in iter(lambda: f.read(65536), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _load_run_records(paths: list[str | Path]) -> list[dict[str, Any]]:
+    rows = []
+    for path in paths:
+        p = Path(path)
+        if not p.exists():
+            continue
+        with p.open("r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                rows.append(json.loads(line))
+    return rows
+
+
+def _safe_int(v: Any) -> int | None:
+    if v is None:
+        return None
+    try:
+        return int(v)
+    except (TypeError, ValueError):
+        return None
+
+
+def _safe_float(v: Any) -> float | None:
+    if v is None:
+        return None
+    try:
+        return float(v)
+    except (TypeError, ValueError):
+        return None
+
+
+def _match_circuit(rows: list[dict], qasm_path: str, content_hash: str, backend_id: str | None, precision: str | None) -> list[dict]:
+    qnorm = _normalize_path(qasm_path)
+    out = []
+    for r in rows:
+        if r.get("run_kind") != "forward_runner_execution":
+            continue
+        if (r.get("content_hash") or "").strip() != content_hash and (not qnorm or _normalize_path(r.get("qasm_path")) != qnorm):
+            continue
+        if backend_id is not None and (r.get("backend_id") or r.get("backend") or "").strip() != backend_id:
+            continue
+        if precision is not None and (r.get("precision") or "").strip() != precision:
+            continue
+        out.append(r)
+    return out
+
+
+def _linear_fit(x: list[float], y: list[float]) -> tuple[float, float, float]:
+    """Return (intercept, slope, r_squared). Simple OLS."""
+    n = len(x)
+    if n < 2:
+        return (0.0, 0.0, 0.0)
+    sx = sum(x)
+    sy = sum(y)
+    sx2 = sum(xi * xi for xi in x)
+    sxy = sum(xi * yi for xi, yi in zip(x, y))
+    denom = n * sx2 - sx * sx
+    if denom == 0:
+        return (0.0, 0.0, 0.0)
+    slope = (n * sxy - sx * sy) / denom
+    intercept = (sy - slope * sx) / n
+    y_mean = sy / n
+    ss_tot = sum((yi - y_mean) ** 2 for yi in y)
+    ss_res = sum((yi - (intercept + slope * xi)) ** 2 for xi, yi in zip(x, y))
+    r2 = 1.0 - (ss_res / ss_tot) if ss_tot != 0 else 0.0
+    return (intercept, slope, r2)
+
+
+def run_analysis(
+    qasm_path: str,
+    run_record_paths: list[str | Path],
+    *,
+    backend_id: str | None = None,
+    precision: str | None = None,
+) -> dict[str, Any]:
+    content_hash = _sha256_file(qasm_path)
+    all_rows = _load_run_records(run_record_paths)
+    rows = _match_circuit(all_rows, qasm_path, content_hash, backend_id, precision)
+
+    # Group by (threshold, shots_runner); for each threshold get build row (shots_runner==1)
+    by_threshold: dict[int, list[dict]] = {}
+    for r in rows:
+        thr = _safe_int(r.get("threshold"))
+        shots = _safe_int(r.get("shots_runner"))
+        if thr is None or shots is None:
+            continue
+        runner_wall = _safe_float(r.get("runner_wall_s"))
+        if runner_wall is None:
+            continue
+        by_threshold.setdefault(thr, []).append({"shots_runner": shots, "runner_wall_s": runner_wall})
+
+    table_rows: list[dict[str, Any]] = []
+    fits: list[dict[str, Any]] = []
+
+    for thr in sorted(by_threshold.keys()):
+        group = by_threshold[thr]
+        build_row = next((g for g in group if g["shots_runner"] == 1), None)
+        if build_row is None:
+            continue
+        build_time_s = build_row["runner_wall_s"]
+        hist_rows = [g for g in group if g["shots_runner"] >= 1]
+        for g in hist_rows:
+            total_runtime_s = g["runner_wall_s"]
+            exec_time_s = max(0.0, total_runtime_s - build_time_s)
+            shots_hist = g["shots_runner"]
+            exec_per_shot = exec_time_s / shots_hist if shots_hist else 0.0
+            table_rows.append({
+                "threshold": thr,
+                "shots_hist": shots_hist,
+                "build_time_s": build_time_s,
+                "total_runtime_s": total_runtime_s,
+                "exec_time_s": exec_time_s,
+                "exec_time_per_shot_s": exec_per_shot,
+            })
+        if len(hist_rows) >= 3:
+            x = [g["shots_runner"] for g in hist_rows]
+            y = [max(0.0, g["runner_wall_s"] - build_time_s) for g in hist_rows]
+            intercept_s, slope_s_per_shot, r2 = _linear_fit(x, y)
+            fits.append({
+                "threshold": thr,
+                "intercept_s": intercept_s,
+                "slope_s_per_shot": slope_s_per_shot,
+                "r2": r2,
+            })
+
+    return {
+        "qasm_path": str(qasm_path),
+        "content_hash": content_hash,
+        "backend_id": backend_id,
+        "precision": precision,
+        "table": table_rows,
+        "fits": fits,
+    }
+
+
+def _print_table(result: dict[str, Any]) -> None:
+    table = result.get("table") or []
+    fits_by_thr = {f["threshold"]: f for f in result.get("fits") or []}
+    if not table:
+        print("No rows (no forward_runner_execution with build row per threshold).")
+        return
+    print(f"qasm: {result['qasm_path']}")
+    print(f"content_hash: {result.get('content_hash', '')}")
+    if result.get("backend_id") is not None:
+        print(f"backend_id: {result['backend_id']}")
+    if result.get("precision") is not None:
+        print(f"precision: {result['precision']}")
+    print("")
+    w = 14
+    print(
+        f"{'threshold':>{w}}  {'shots_hist':>{w}}  {'build_time_s':>{w}}  {'total_runtime_s':>{w}}  "
+        f"{'exec_time_s':>{w}}  {'exec_time_per_shot_s':>{w}}"
+    )
+    print("-" * (6 * (w + 2)))
+    for r in table:
+        print(
+            f"{r['threshold']:>{w}}  {r['shots_hist']:>{w}}  {r['build_time_s']:>{w}.6g}  {r['total_runtime_s']:>{w}.6g}  "
+            f"{r['exec_time_s']:>{w}.6g}  {r['exec_time_per_shot_s']:>{w}.6e}"
+        )
+    if fits_by_thr:
+        print("")
+        print("Per-threshold linear fit (exec_time_s ≈ intercept_s + slope_s_per_shot * shots_hist):")
+        print(f"{'threshold':>{w}}  {'intercept_s':>{w}}  {'slope_s_per_shot':>{w}}  {'r2':>{w}}")
+        print("-" * (4 * (w + 2)))
+        for f in result.get("fits") or []:
+            print(
+                f"{f['threshold']:>{w}}  {f['intercept_s']:>{w}.6g}  {f['slope_s_per_shot']:>{w}.6e}  {f['r2']:>{w}.4f}"
+            )
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(
+        description="Analyze forward execution time vs shots for one circuit from run-record JSONL."
+    )
+    ap.add_argument("qasm_path", help="Path to one .qasm file")
+    ap.add_argument(
+        "--run-record",
+        action="append",
+        dest="run_records",
+        default=[],
+        metavar="PATH",
+        help="Path to run_record JSONL (repeat for multiple files)",
+    )
+    ap.add_argument("--backend-id", default=None, help="Restrict to this backend_id")
+    ap.add_argument("--precision", default=None, help="Restrict to this precision")
+    ap.add_argument("--json", action="store_true", help="Emit JSON output")
+    args = ap.parse_args(argv)
+
+    if not args.run_records:
+        print("Error: at least one --run-record is required", file=__import__("sys").stderr)
+        return 1
+
+    result = run_analysis(
+        args.qasm_path,
+        args.run_records,
+        backend_id=args.backend_id or None,
+        precision=args.precision or None,
+    )
+    if args.json:
+        print(json.dumps(result, indent=2, sort_keys=True))
+    else:
+        _print_table(result)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

qcoder/tools/batch.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from qcoder.pipelines.batch import analyze_directory
+
+
+def analyze_qasm_dir_to_jsonl(
+    circuits_dir: str,
+    out_path: str,
+    *,
+    processor: str | None = None,
+    backend: str | None = None,
+    precision: str | None = None,
+    threshold: float | None = None,
+    recursive: bool = True,
+    pattern: str = "*.qasm",
+    fail_fast: bool = True,
+    mirror_artifacts_dir: str | None = None,
+) -> int:
+    """Run batch extraction and write one JSON object per line to out_path. Returns record count."""
+    results = analyze_directory(
+        circuits_dir,
+        processor=processor,
+        backend=backend,
+        precision=precision,
+        threshold=threshold,
+        recursive=recursive,
+        pattern=pattern,
+        fail_fast=fail_fast,
+        mirror_artifacts_dir=mirror_artifacts_dir,
+    )
+    path = Path(out_path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as f:
+        for rec in results:
+            f.write(json.dumps(rec, sort_keys=True) + "\n")
+    return len(results)