qcoder 0.1.0a0__py3-none-any.whl

qcoder/__init__.py

@@ -0,0 +1,3 @@
+__all__ = []
+__version__ = "0.1.0a0"
+file = __file__

qcoder/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from qcoder.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

qcoder/cli.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from qcoder.pipelines.analyze import analyze_qasm
+from qcoder.tools.batch import analyze_qasm_dir_to_jsonl
+
+
+def _cmd_analyze(argv: list[str]) -> int:
+    p = argparse.ArgumentParser(prog="qcoder analyze", add_help=True)
+    p.add_argument("qasm", help="Path to a .qasm file")
+
+    # Circuit identity / metadata
+    p.add_argument("--id", dest="circuit_id", default=None, help="Optional circuit id")
+    p.add_argument("--name", dest="circuit_name", default=None, help="Optional circuit name")
+
+    # Run config (conditioning vars for predictors; not used by feature extraction)
+    p.add_argument(
+        "--processor",
+        "--backend",
+        dest="processor",
+        default="CPU",
+        help='Processor/backend label (aliases: Scarlet/Amber, CPU/GPU)',
+    )
+    p.add_argument("--precision", default="single", help="Precision: single|double (aliases: fp32/fp64)")
+    p.add_argument("--threshold", type=float, default=None, help="Optional threshold/bond-dim conditioning value")
+    p.add_argument("--mirror-artifacts-dir", default=None, metavar="DIR", help="If set, write mirror QASM to DIR and add adjoint_supported/adjoint_reason/mirror_qasm_ref to output")
+
+    p.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
+    args = p.parse_args(argv)
+
+    report = analyze_qasm(
+        args.qasm,
+        circuit_id=args.circuit_id,
+        circuit_name=args.circuit_name,
+        processor=args.processor,
+        precision=args.precision,
+        threshold=args.threshold,
+        mirror_artifacts_dir=args.mirror_artifacts_dir or None,
+    )
+
+    if args.json:
+        print(json.dumps(report.to_json_dict(), indent=2, sort_keys=True))
+        return 0
+
+    ex = report.example
+    rc = report.run_config
+    print(f"file: {ex.qasm_path}")
+    print(f"format: {ex.ir.source_format}")
+    if ex.name:
+        print(f"name: {ex.name}")
+    print(f"function_hint: {ex.function_hint} ({ex.function_source})")
+    print(f"processor: {rc.processor}  backend: {rc.backend}  precision: {rc.precision}  threshold: {rc.threshold}")
+    print(f"n_qubits: {ex.ir.n_qubits}")
+    print(f"n_ops: {ex.ir.n_ops}")
+    fv = ex.global_features
+    print(f"schema: {fv.schema_version}")
+    print(f"n_features: {len(fv.features)}")
+    return 0
+
+
+def _cmd_batch(argv: list[str]) -> int:
+    p = argparse.ArgumentParser(prog="qcoder batch", add_help=True)
+    p.add_argument("circuits_dir", help="Directory containing QASM files")
+    p.add_argument("--out", required=True, help="Output JSONL path")
+    p.set_defaults(recursive=True)
+    p.add_argument("--recursive", dest="recursive", action="store_true", help="Discover files recursively (default)")
+    p.add_argument("--non-recursive", dest="recursive", action="store_false", help="Only discover top-level files")
+    p.add_argument("--pattern", default="*.qasm", help="Glob pattern for files (default: *.qasm)")
+    p.add_argument("--skip-errors", action="store_true", help="Continue on error, emit error records (default: fail-fast)")
+    p.add_argument("--processor", default=None, help="Processor/backend label for run_config")
+    p.add_argument("--backend", default=None, help="Backend label (CPU/GPU, etc.)")
+    p.add_argument("--precision", default=None, help="Precision: single|double|fp32|fp64")
+    p.add_argument("--threshold", type=float, default=None, help="Optional threshold for run_config")
+    p.add_argument("--mirror-artifacts-dir", default=None, metavar="DIR", help="If set, write mirror QASM to DIR and add adjoint_supported/adjoint_reason/mirror_qasm_ref to each record")
+    args = p.parse_args(argv)
+
+    n = analyze_qasm_dir_to_jsonl(
+        args.circuits_dir,
+        args.out,
+        processor=args.processor,
+        backend=args.backend,
+        precision=args.precision,
+        threshold=args.threshold,
+        recursive=args.recursive,
+        pattern=args.pattern,
+        fail_fast=not args.skip_errors,
+        mirror_artifacts_dir=args.mirror_artifacts_dir or None,
+    )
+    print(f"Wrote {n} records to {args.out}", file=sys.stderr)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    if argv is None:
+        argv = sys.argv[1:]
+
+    parser = argparse.ArgumentParser(prog="qcoder")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("analyze", help="Analyze a QASM file (feature extraction + metadata + run config)")
+    sub.add_parser("batch", help="Batch extract directory to JSONL")
+    ns, rest = parser.parse_known_args(argv)
+
+    if ns.cmd == "analyze":
+        return _cmd_analyze(rest)
+    if ns.cmd == "batch":
+        return _cmd_batch(rest)
+
+    parser.error(f"Unknown command: {ns.cmd}")
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

qcoder/core/__init__.py

@@ -0,0 +1 @@
+# Core shared types and utilities

qcoder/core/context.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+# Backwards-compatible shim.
+# Prefer: from qcoder.core.run_config import RunConfig
+from qcoder.core.run_config import (
+    CPU_ALIASES,
+    GPU_ALIASES,
+    SINGLE_ALIASES,
+    DOUBLE_ALIASES,
+    RunConfig,
+    normalize_backend,
+    normalize_precision,
+)
+
+# Older code referred to Context; keep it as an alias.
+Context = RunConfig

qcoder/core/qasm2/__init__.py

@@ -0,0 +1 @@
+# QASM2 lightweight utilities (e.g. mirror build)

qcoder/core/qasm2/adjoint_eligibility.py

@@ -0,0 +1,128 @@
+"""
+Lightweight adjoint/mirror eligibility for OpenQASM 2.
+
+Detects unitary eligibility (no measure/reset; conservative) and attempts
+to generate mirror QASM via existing inversion utilities. Does not modify
+the 48-feature vector; for metadata only.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+from .mirror_build import UnsupportedQasm, build_mirror_qasm
+
+_RE_MEASURE = re.compile(r"^\s*measure\s+", re.I)
+_RE_RESET = re.compile(r"^\s*reset\s+", re.I)
+_RE_IF = re.compile(r"^\s*if\s*\(", re.I)
+_RE_OPENQASM = re.compile(r"^\s*openqasm\s+", re.I)
+_RE_INCLUDE = re.compile(r'^\s*include\s+"[^"]+"\s*;\s*$', re.I)
+_RE_QREG = re.compile(r"^\s*qreg\s+[A-Za-z_]\w*\s*\[\s*\d+\s*\]\s*;\s*$", re.I)
+_RE_CREG = re.compile(r"^\s*creg\s+[A-Za-z_]\w*\s*\[\s*\d+\s*\]\s*;\s*$", re.I)
+_RE_BARRIER = re.compile(r"^\s*barrier\s+", re.I)
+_RE_OP = re.compile(r"^\s*[A-Za-z_]\w*\s*(\([^)]*\))?\s+.+;\s*$")
+
+
+@dataclass(frozen=True)
+class AdjointEligibility:
+    adjoint_supported: bool
+    adjoint_reason: str
+    mirror_qasm: Optional[str] = None
+
+    def to_metadata_dict(self, *, include_mirror_qasm: bool = False) -> dict:
+        out = {
+            "adjoint_supported": self.adjoint_supported,
+            "adjoint_reason": self.adjoint_reason,
+        }
+        if include_mirror_qasm and self.mirror_qasm is not None:
+            out["mirror_qasm"] = self.mirror_qasm
+        return out
+
+
+def classify_mirror_eligibility(qasm_text: str) -> tuple[str, str]:
+    """
+    Return (classification, reason) where classification is one of:
+      - ok
+      - non_unitary
+      - parse_error
+    Policy:
+      - allow terminal measurement block
+      - non_unitary on reset
+      - non_unitary on measurements before terminal block
+      - non_unitary on classical conditional execution (if (...))
+    """
+    saw_terminal_measure = False
+
+    for line in qasm_text.splitlines():
+        s = line.strip()
+        if not s or s.startswith("//"):
+            continue
+        # Remove trailing inline comments for simple statement checks.
+        if "//" in s:
+            s = s.split("//", 1)[0].strip()
+            if not s:
+                continue
+
+        if _RE_RESET.match(s):
+            return "non_unitary", "circuit contains reset (not unitary)"
+        if _RE_IF.match(s):
+            return "non_unitary", "circuit contains classical conditional execution"
+        if _RE_MEASURE.match(s):
+            saw_terminal_measure = True
+            continue
+
+        # Non-measurement statement after measure => mid-circuit measurement.
+        if saw_terminal_measure:
+            return "non_unitary", "circuit has measurement before terminal measurement block"
+
+        if (
+            _RE_OPENQASM.match(s)
+            or _RE_INCLUDE.match(s)
+            or _RE_QREG.match(s)
+            or _RE_CREG.match(s)
+            or _RE_BARRIER.match(s)
+            or _RE_OP.match(s)
+        ):
+            continue
+
+        return "parse_error", f"unrecognized statement: {s[:80]}"
+
+    return "ok", ""
+
+
+def check_adjoint_eligibility(
+    qasm_text: str,
+    *,
+    drop_barriers: bool = True,
+    include_mirror_qasm: bool = True,
+) -> AdjointEligibility:
+    """
+    Check whether the circuit is eligible for mirror/adjoint (unitary) and
+    attempt to generate mirror QASM.
+
+    Returns AdjointEligibility with adjoint_supported, adjoint_reason, and
+    optionally mirror_qasm text. Unitary eligibility is conservative:
+    presence of measure or reset lines makes the circuit non-unitary.
+    """
+    cls, reason = classify_mirror_eligibility(qasm_text)
+    if cls != "ok":
+        return AdjointEligibility(
+            adjoint_supported=False,
+            adjoint_reason=reason or cls,
+            mirror_qasm=None,
+        )
+    try:
+        mirror_qasm, _ = build_mirror_qasm(qasm_text, drop_barriers=drop_barriers)
+        return AdjointEligibility(
+            adjoint_supported=True,
+            adjoint_reason="",
+            mirror_qasm=mirror_qasm if include_mirror_qasm else None,
+        )
+    except UnsupportedQasm as e:
+        return AdjointEligibility(
+            adjoint_supported=False,
+            adjoint_reason=str(e),
+            mirror_qasm=None,
+        )

qcoder/core/qasm2/mirror_build.py

@@ -0,0 +1,234 @@
+"""
+Build mirror QASM (U then U†) from OpenQASM 2 source for counts-based mirror runs.
+
+Tolerates standard OpenQASM 2 include "qelib1.inc"; and preserves it in output.
+Raises UnsupportedQasm for other include statements or gates that cannot be
+inverted in this minimal implementation (no gate definitions, no opaque).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import List, Optional, Tuple
+
+
+class UnsupportedQasm(Exception):
+    """Raised when the QASM cannot be mirrored (e.g. include, unsupported gate)."""
+    pass
+
+
+# Gate name -> (adjoint_param_negate_mask, self_adjoint)
+# u1(t)† = u1(-t); u2(p,l)† = u2(-l,-p); u3(t,p,l)† = u3(-t,-l,-p)
+# cx, cz, swap, id, x, y, z, h are self-adjoint; s<->sdg, t<->tdg
+_ADJOINT_U1 = (True,)   # one param negate
+_ADJOINT_U2 = (True, True)  # swap and negate both
+_ADJOINT_U3 = (True, True, True)  # negate all three
+_SELF_ADJOINT = ()
+_GATE_ADJOINT: dict[str, tuple] = {
+    "u1": _ADJOINT_U1,
+    "u2": _ADJOINT_U2,
+    "u3": _ADJOINT_U3,
+    "u": (True, True, True),  # U(theta,phi,lambda) same as u3
+    "cu3": _ADJOINT_U3,
+    "p": _ADJOINT_U1,
+    "cp": _ADJOINT_U1,
+    "cu1": _ADJOINT_U1,
+    "rx": _ADJOINT_U1,
+    "ry": _ADJOINT_U1,
+    "rz": _ADJOINT_U1,
+    "rxx": _ADJOINT_U1,
+    "rzz": _ADJOINT_U1,
+    "crx": _ADJOINT_U1,
+    "cry": _ADJOINT_U1,
+    "crz": _ADJOINT_U1,
+    "cx": _SELF_ADJOINT,
+    "ch": _SELF_ADJOINT,
+    "cy": _SELF_ADJOINT,
+    "cz": _SELF_ADJOINT,
+    "swap": _SELF_ADJOINT,
+    "cswap": _SELF_ADJOINT,
+    "ccx": _SELF_ADJOINT,
+    "rccx": _SELF_ADJOINT,
+    "id": _SELF_ADJOINT,
+    "x": _SELF_ADJOINT,
+    "y": _SELF_ADJOINT,
+    "z": _SELF_ADJOINT,
+    "h": _SELF_ADJOINT,
+    "s": ("sdg",),   # S† = Sdg (name swap, no params)
+    "sdg": ("s",),
+    "t": ("tdg",),
+    "tdg": ("t",),
+    "sx": ("sxdg",),
+    "sxdg": ("sx",),
+}
+
+_RE_INCLUDE = re.compile(r'^\s*include\s+"([^"]+)"\s*;\s*$', re.I)
+_RE_OPENQASM = re.compile(r'^\s*OPENQASM\s+', re.I)
+_RE_QREG = re.compile(r'^\s*qreg\s+([A-Za-z_]\w*)\s*\[\s*(\d+)\s*\]\s*;\s*$')
+_RE_CREG = re.compile(r'^\s*creg\s+', re.I)
+_RE_BARRIER = re.compile(r'^\s*barrier\s+', re.I)
+_RE_MEASURE = re.compile(r'^\s*measure\s+', re.I)
+# gate line: name ( params )? qubit_operands ;
+_RE_OP = re.compile(r'^\s*([A-Za-z_]\w*)\s*(\([^)]*\))?\s+(.+?)\s*;\s*$')
+
+
+def _parse_float(s: str) -> float:
+    s = s.strip()
+    try:
+        return float(s)
+    except ValueError:
+        return 0.0
+
+
+def _negate_param(p: str) -> str:
+    s = p.strip()
+
+    def _strip_outer_parens(x: str) -> str:
+        x = x.strip()
+        while x.startswith("(") and x.endswith(")"):
+            depth = 0
+            ok = True
+            for i, ch in enumerate(x):
+                if ch == "(":
+                    depth += 1
+                elif ch == ")":
+                    depth -= 1
+                    if depth == 0 and i != len(x) - 1:
+                        ok = False
+                        break
+            if not ok or depth != 0:
+                break
+            x = x[1:-1].strip()
+        return x
+
+    def _is_zero_literal(x: str) -> bool:
+        try:
+            return float(x.strip()) == 0.0
+        except Exception:
+            return False
+
+    try:
+        v = -float(s)
+        return "0" if v == 0.0 else str(v)
+    except ValueError:
+        core = _strip_outer_parens(s)
+        # Simplify double negation: -(-x) -> x
+        if core.startswith("-"):
+            pos = _strip_outer_parens(core[1:])
+            return "0" if _is_zero_literal(pos) else pos
+        # Keep symbolic form explicit for non-numeric params.
+        return f"-({core})"
+
+
+def _emit_adjoint_gate(name: str, params: List[str], operands: str) -> str:
+    key = name.lower()
+    adj = _GATE_ADJOINT.get(key)
+    if adj is None:
+        raise UnsupportedQasm(f"Unsupported gate for mirror: {name}")
+    if adj == _SELF_ADJOINT:
+        param_str = f"({', '.join(params)})" if params else ""
+        return f"{name}{param_str} {operands};"
+    if isinstance(adj, tuple) and len(adj) == 1 and isinstance(adj[0], str):
+        # name swap only: s->sdg, sdg->s, t->tdg, tdg->t
+        adj_name = adj[0]
+        param_str = f"({', '.join(params)})" if params else ""
+        return f"{adj_name}{param_str} {operands};"
+    # negate params: adj is (bool,) for each param to negate
+    out_params: List[str] = []
+    for i, p in enumerate(params):
+        if i < len(adj) and adj[i]:
+            out_params.append(_negate_param(p))
+        else:
+            out_params.append(p)
+    if key == "u2":
+        # u2(phi, lambda)† = u2(-lambda, -phi): swap and negate
+        if len(out_params) >= 2:
+            out_params[0], out_params[1] = out_params[1], out_params[0]
+    if key == "cu3":
+        # cu3(theta, phi, lambda)† = cu3(-theta, -lambda, -phi)
+        if len(out_params) >= 3:
+            out_params[1], out_params[2] = out_params[2], out_params[1]
+    param_str = f"({', '.join(out_params)})" if out_params else ""
+    return f"{name}{param_str} {operands};"
+
+
+def build_mirror_qasm(orig_text: str, drop_barriers: bool = True) -> Tuple[str, Optional[int]]:
+    """
+    Build mirror circuit QASM (U then U†) from OpenQASM 2 source.
+
+    Returns (mirror_qasm_string, n_qubits). Drops measure and optionally barrier.
+    Raises UnsupportedQasm if non-standard includes or unsupported gates are present.
+    """
+    lines = orig_text.splitlines()
+    header_lines: List[str] = []
+    qregs: List[Tuple[str, int]] = []
+    gate_lines: List[Tuple[str, List[str], str]] = []  # (name, params, operands)
+
+    for raw in lines:
+        s = raw.strip()
+        if not s or s.startswith("//"):
+            continue
+        m = _RE_INCLUDE.match(s)
+        if m:
+            inc = m.group(1).strip().lower()
+            if inc != "qelib1.inc":
+                raise UnsupportedQasm(f'Unsupported include for mirror: "{m.group(1).strip()}"')
+            header_lines.append(s)
+            continue
+        if _RE_OPENQASM.match(s):
+            header_lines.append(s)
+            continue
+        if _RE_CREG.match(s):
+            continue
+        if _RE_MEASURE.match(s):
+            continue
+        if _RE_BARRIER.match(s):
+            if not drop_barriers:
+                raise UnsupportedQasm("barrier in circuit (use drop_barriers=True)")
+            continue
+        m = _RE_QREG.match(s)
+        if m:
+            header_lines.append(s)
+            qregs.append((m.group(1), int(m.group(2))))
+            continue
+        m = _RE_OP.match(s)
+        if m:
+            name = m.group(1)
+            params_raw = (m.group(2) or "").strip()
+            operands = (m.group(3) or "").strip()
+            params: List[str] = []
+            if params_raw.startswith("(") and params_raw.endswith(")"):
+                inside = params_raw[1:-1].strip()
+                if inside:
+                    params = [x.strip() for x in inside.split(",")]
+            gate_lines.append((name, params, operands))
+            continue
+        # unknown line (gate def, etc.)
+        raise UnsupportedQasm(f"Unsupported line for mirror: {s[:60]}")
+
+    if not qregs:
+        raise UnsupportedQasm("No qreg declaration found")
+    total_width = sum(sz for _, sz in qregs)
+
+    # Ensure OPENQASM 2.0 header
+    if not any(_RE_OPENQASM.match(h) for h in header_lines):
+        header_lines.insert(0, "OPENQASM 2.0;")
+
+    out: List[str] = []
+    out.extend(header_lines)
+    # U
+    for name, params, operands in gate_lines:
+        param_str = f"({', '.join(params)})" if params else ""
+        out.append(f"{name}{param_str} {operands};")
+    # U† (reversed, adjoint)
+    for name, params, operands in reversed(gate_lines):
+        out.append(_emit_adjoint_gate(name, params, operands))
+    # Final measurements for counts-based mirror mode.
+    out.append(f"creg c[{total_width}];")
+    cidx = 0
+    for qreg_name, qreg_size in qregs:
+        for i in range(int(qreg_size)):
+            out.append(f"measure {qreg_name}[{i}] -> c[{cidx}];")
+            cidx += 1
+
+    return "\n".join(out) + "\n", total_width

qcoder/core/run_config.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+CPU_ALIASES = {"cpu", "scarlet"}
+GPU_ALIASES = {"gpu", "amber"}
+
+SINGLE_ALIASES = {"single", "fp32", "float32"}
+DOUBLE_ALIASES = {"double", "fp64", "float64"}
+
+
+def normalize_backend(x: str | None) -> str:
+    s = (x or "").strip().lower()
+    if s in CPU_ALIASES:
+        return "CPU"
+    if s in GPU_ALIASES:
+        return "GPU"
+    return "CPU"
+
+
+def normalize_precision(x: str | None) -> str:
+    s = (x or "").strip().lower()
+    if s in SINGLE_ALIASES:
+        return "single"
+    if s in DOUBLE_ALIASES:
+        return "double"
+    return "single"
+
+
+@dataclass(frozen=True)
+class RunConfig:
+    """
+    Conditioning variables for runtime/fidelity predictors.
+
+    These are NOT circuit-derived features.
+    """
+    processor: str | None           # raw label like "Amber", "Scarlet", "CPU", "GPU"
+    backend: str                    # normalized: "CPU" | "GPU"
+    precision: str                  # normalized: "single" | "double"
+    threshold: float | None = None  # e.g. bond-dimension/threshold conditioning
+    prediction_artifact_path: str | None = None
+    prediction_allow_schema_mismatch: bool = False
+    prediction_fidelity_target: float | None = None
+    prediction_fidelity_metric: str | None = None
+
+    @staticmethod
+    def from_raw(
+        *,
+        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,
+    ) -> "RunConfig":
+        # accept processor OR backend as the same input channel
+        raw = processor if processor is not None else backend
+        proc = (raw or "").strip()
+        proc = proc if proc else None
+
+        return RunConfig(
+            processor=proc,
+            backend=normalize_backend(raw or backend),
+            precision=normalize_precision(precision),
+            threshold=float(threshold) if threshold is not None else None,
+            prediction_artifact_path=prediction_artifact_path,
+            prediction_allow_schema_mismatch=prediction_allow_schema_mismatch or False,
+            prediction_fidelity_target=prediction_fidelity_target,
+            prediction_fidelity_metric=prediction_fidelity_metric,
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "processor": self.processor,
+            "backend": self.backend,
+            "precision": self.precision,
+            "threshold": self.threshold,
+            "prediction_artifact_path": self.prediction_artifact_path,
+            "prediction_allow_schema_mismatch": self.prediction_allow_schema_mismatch,
+            "prediction_fidelity_target": self.prediction_fidelity_target,
+            "prediction_fidelity_metric": self.prediction_fidelity_metric,
+        }

qcoder/core/schema.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable
+
+
+@dataclass(frozen=True)
+class FeatureSchema:
+    version: str
+    feature_names: tuple[str, ...]
+    transforms: dict[str, str]
+
+    def index(self) -> dict[str, int]:
+        return {n: i for i, n in enumerate(self.feature_names)}
+
+
+# Feature schema version (append-only updates).
+SCHEMA_VERSION = "0.4.0"
+
+
+def make_schema(names: Iterable[str], *, transforms: dict[str, str] | None = None) -> FeatureSchema:
+    return FeatureSchema(
+        version=SCHEMA_VERSION,
+        feature_names=tuple(names),
+        transforms=dict(transforms or {}),
+    )

qcoder/engines/feature_extraction/adapters/__init__.py

@@ -0,0 +1 @@
+"""Optional format adapters (e.g. Qiskit). Imports here must remain lazy where noted."""

qcoder/engines/feature_extraction/adapters/qiskit_intake.py

@@ -0,0 +1,46 @@
+"""
+Optional Qiskit QuantumCircuit intake via OpenQASM 2 export.
+
+Qiskit is imported only when functions in this module are called.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..features.compute_v0 import FeatureVector, compute_features_v0
+from ..ir import CircuitIR
+from ..qasm2_regex_parser import parse_qasm2_text
+
+
+def _load_qiskit() -> tuple[type, Any]:
+    try:
+        from qiskit import QuantumCircuit
+        from qiskit.qasm2 import dumps
+    except ImportError as e:
+        raise ImportError(
+            "qcoder: Qiskit is not installed. "
+            "Install with: pip install qiskit  or  pip install 'qcoder[qiskit]' "
+            "(optional extra)."
+        ) from e
+    return QuantumCircuit, dumps
+
+
+def circuit_ir_from_qiskit(qc: Any) -> CircuitIR:
+    """
+    Export ``qc`` with ``qiskit.qasm2.dumps`` and parse as OpenQASM 2 text.
+
+    Raises ImportError when Qiskit is not installed (only at call time).
+    Raises TypeError if ``qc`` is not a ``qiskit.QuantumCircuit``.
+    """
+    QuantumCircuit, dumps = _load_qiskit()
+    if not isinstance(qc, QuantumCircuit):
+        raise TypeError(f"expected qiskit.QuantumCircuit, got {type(qc).__name__}")
+    qasm_text = dumps(qc)
+    return parse_qasm2_text(qasm_text, source_label="qiskit.qasm2.dumps")
+
+
+def extract_features_from_qiskit_circuit(qc: Any) -> FeatureVector:
+    """``circuit_ir_from_qiskit`` + ``compute_features_v0`` (same schema as file intake)."""
+    ir = circuit_ir_from_qiskit(qc)
+    return compute_features_v0(ir)