qcoder 0.1.0a0__py3-none-any.whl

qcoder/engines/feature_extraction/extractor.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .features.compute_v0 import FeatureVector, compute_features_v0
+from .ir import CircuitIR
+from .labeling import infer_function
+from .parsers import parse_circuit_file
+
+
+@dataclass(frozen=True)
+class CircuitExample:
+    id: str | None
+    name: str | None
+    function_hint: str           # small normalized label
+    function_source: str         # "name" | "qasm" | "unknown"
+    qasm_path: str
+    ir: CircuitIR
+    global_features: FeatureVector
+
+
+def extract_example(
+    qasm_path: str,
+    *,
+    circuit_id: str | None = None,
+    circuit_name: str | None = None,
+) -> CircuitExample:
+    p = Path(qasm_path)
+    ir = parse_circuit_file(str(p))
+    fv = compute_features_v0(ir)
+
+    function_hint, function_source = infer_function(circuit_name, ir)
+
+    return CircuitExample(
+        id=circuit_id,
+        name=circuit_name,
+        function_hint=function_hint,
+        function_source=function_source,
+        qasm_path=str(p),
+        ir=ir,
+        global_features=fv,
+    )

qcoder/engines/feature_extraction/features/compute_v0.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..ir import CircuitIR
+from ..reps.cut_profile import compute_cut_profile_stats
+from ..reps.depth import compute_depth_stats
+from ..reps.entangling_layers import compute_entangling_layer_stats
+from ..reps.gate_set_stats import compute_gate_set_stats
+from ..reps.interaction_graph import build_interaction_graph
+from ..reps.interaction_graph_metrics import compute_interaction_graph_metrics
+from ..reps.spans import compute_span_stats
+from .schema_v0 import SCHEMA_V0
+
+
+@dataclass(frozen=True)
+class FeatureVector:
+    schema_version: str
+    feature_names: tuple[str, ...]
+    features: tuple[float, ...]
+
+    def to_dict(self) -> dict:
+        return {
+            "schema_version": self.schema_version,
+            "feature_names": list(self.feature_names),
+            "features": list(self.features),
+        }
+
+
+def compute_features_v0(ir: CircuitIR) -> FeatureVector:
+    n_measure = 0
+    n_barrier = 0
+    n_reset = 0
+    n_gate = 0
+    n_1q = 0
+    n_2q = 0
+    n_3p = 0
+    n_param = 0
+    n_custom = 0
+
+    for op in ir.operations:
+        if op.is_measure:
+            n_measure += 1
+            continue
+        if op.is_barrier:
+            n_barrier += 1
+            continue
+        if op.is_reset:
+            n_reset += 1
+            continue
+
+        if not op.qubits:
+            continue
+
+        n_gate += 1
+        if op.is_custom:
+            n_custom += 1
+        if op.params:
+            n_param += 1
+
+        ar = len(op.qubits)
+        if ar == 1:
+            n_1q += 1
+        elif ar == 2:
+            n_2q += 1
+        else:
+            n_3p += 1
+
+    depth = compute_depth_stats(ir)
+    ig = build_interaction_graph(ir)
+    spans = compute_span_stats(ir)
+    cuts = compute_cut_profile_stats(ig)
+    gate_stats = compute_gate_set_stats(ir)
+    ig_metrics = compute_interaction_graph_metrics(ig)
+    ent_layers = compute_entangling_layer_stats(ir)
+
+    n_edges = float(len(ig.edges))
+    denom = (ir.n_qubits * (ir.n_qubits - 1) / 2.0) if ir.n_qubits >= 2 else 1.0
+    edge_density = float(n_edges / denom) if denom > 0 else 0.0
+
+    values = {
+        "n_qubits": float(ir.n_qubits),
+        "n_cbits": float(ir.n_cbits),
+        "n_ops": float(ir.n_ops),
+
+        "n_gate_ops": float(n_gate),
+        "n_1q_gate_ops": float(n_1q),
+        "n_2q_gate_ops": float(n_2q),
+        "n_3p_gate_ops": float(n_3p),
+        "n_param_ops": float(n_param),
+        "n_custom_ops": float(n_custom),
+
+        "n_measure_ops": float(n_measure),
+        "n_barrier_ops": float(n_barrier),
+        "n_reset_ops": float(n_reset),
+
+        "estimated_depth": float(depth.estimated_depth),
+        "real_depth": float(depth.real_depth),
+        "avg_parallel_gates": float(depth.avg_parallel_gates),
+        "parallelism_factor": float(depth.parallelism_factor),
+
+        "ig_n_edges": float(n_edges),
+        "ig_edge_density": float(edge_density),
+
+        "span_avg": float(spans.avg_span),
+        "span_max": float(spans.max_span),
+        "span_std": float(spans.span_std),
+        "span_nearest_neighbor_ratio": float(spans.nearest_neighbor_ratio),
+        "span_long_range_ratio": float(spans.long_range_ratio),
+        "span_long_range_ratio_early": float(spans.long_range_ratio_early),
+        "span_long_range_ratio_late": float(spans.long_range_ratio_late),
+        "span_avg_early": float(spans.avg_span_early),
+        "span_avg_late": float(spans.avg_span_late),
+
+        # Phase 2: cut profile (natural qubit order only)
+        "cut_max": float(cuts.cut_max),
+        "cut_mean": float(cuts.cut_mean),
+        "cut_std": float(cuts.cut_std),
+        "cut_entropy": float(cuts.cut_entropy),
+        "n_active_cuts": float(cuts.n_active_cuts),
+        "max_span_in_order": float(cuts.max_span_in_order),
+
+        # Quantumness v1: gate set + angles + basis/diagonal
+        "n_basis_change_ops": float(gate_stats.n_basis_change_ops),
+        "basis_change_qubit_coverage": float(gate_stats.basis_change_qubit_coverage),
+        "n_diagonal_gate_ops": float(gate_stats.n_diagonal_gate_ops),
+        "diagonal_gate_fraction": float(gate_stats.diagonal_gate_fraction),
+        "n_t_like_ops": float(gate_stats.n_t_like_ops),
+        "n_distinct_angles": float(gate_stats.n_distinct_angles),
+        "angle_genericity_ratio": float(gate_stats.angle_genericity_ratio),
+        "is_certified_diagonal_only": float(gate_stats.is_certified_diagonal_only),
+
+        # Quantumness v1: IG degree/connectivity metrics (unweighted)
+        "ig_max_degree": float(ig_metrics.ig_max_degree),
+        "ig_avg_degree": float(ig_metrics.ig_avg_degree),
+        "ig_degree_std": float(ig_metrics.ig_degree_std),
+        "ig_degree_entropy": float(ig_metrics.ig_degree_entropy),
+        "ig_n_components": float(ig_metrics.ig_n_components),
+        "ig_largest_cc_frac": float(ig_metrics.ig_largest_cc_frac),
+        "ig_is_connected": float(ig_metrics.ig_is_connected),
+        "ig_pair_reuse_hhi": float(ig_metrics.ig_pair_reuse_hhi),
+        "ig_pair_reuse_top1_frac": float(ig_metrics.ig_pair_reuse_top1_frac),
+
+        # Quantumness v1: entangling depth/layers
+        "entangling_depth": float(ent_layers.entangling_depth),
+        "n_entangling_layers": float(ent_layers.n_entangling_layers),
+        "avg_2q_per_entangling_layer": float(ent_layers.avg_2q_per_entangling_layer),
+        "max_2q_per_entangling_layer": float(ent_layers.max_2q_per_entangling_layer),
+    }
+
+    feats = tuple(float(values.get(name, 0.0)) for name in SCHEMA_V0.feature_names)
+
+    return FeatureVector(
+        schema_version=SCHEMA_V0.version,
+        feature_names=SCHEMA_V0.feature_names,
+        features=feats,
+    )

qcoder/engines/feature_extraction/features/schema_v0.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from qcoder.core.schema import make_schema
+
+# Schema 0.4.0: PURE circuit-derived features (no backend/precision/threshold).
+FEATURE_NAMES_V0 = [
+    # basic sizes
+    "n_qubits",
+    "n_cbits",
+    "n_ops",
+
+    # gate arity counts (exclude measure/barrier/reset)
+    "n_gate_ops",
+    "n_1q_gate_ops",
+    "n_2q_gate_ops",
+    "n_3p_gate_ops",   # 3+ qubit gate ops
+    "n_param_ops",
+    "n_custom_ops",
+
+    # control ops
+    "n_measure_ops",
+    "n_barrier_ops",
+    "n_reset_ops",
+
+    # depth proxies
+    "estimated_depth",
+    "real_depth",
+    "avg_parallel_gates",
+    "parallelism_factor",
+
+    # interaction graph
+    "ig_n_edges",
+    "ig_edge_density",
+
+    # span stats (2Q only)
+    "span_avg",
+    "span_max",
+    "span_std",
+    "span_nearest_neighbor_ratio",
+    "span_long_range_ratio",
+
+    # Phase 2: cut profile (natural qubit order only)
+    "cut_max",
+    "cut_mean",
+    "cut_std",
+    "cut_entropy",
+    "n_active_cuts",
+    "max_span_in_order",
+
+    # Quantumness v1: gate set + angles + basis/diagonal
+    "n_basis_change_ops",
+    "basis_change_qubit_coverage",
+    "n_diagonal_gate_ops",
+    "diagonal_gate_fraction",
+    "n_t_like_ops",
+    "n_distinct_angles",
+    "angle_genericity_ratio",
+    "is_certified_diagonal_only",
+
+    # Quantumness v1: IG degree/connectivity metrics (unweighted)
+    "ig_max_degree",
+    "ig_avg_degree",
+    "ig_degree_std",
+    "ig_degree_entropy",
+    "ig_n_components",
+    "ig_largest_cc_frac",
+    "ig_is_connected",
+
+    # Quantumness v1: entangling depth/layers
+    "entangling_depth",
+    "n_entangling_layers",
+    "avg_2q_per_entangling_layer",
+    "max_2q_per_entangling_layer",
+
+    # Phase 3: temporal span + weighted pair-reuse features (append-only)
+    "span_long_range_ratio_early",
+    "span_long_range_ratio_late",
+    "span_avg_early",
+    "span_avg_late",
+    "ig_pair_reuse_hhi",
+    "ig_pair_reuse_top1_frac",
+]
+
+SCHEMA_V0 = make_schema(FEATURE_NAMES_V0)

qcoder/engines/feature_extraction/ir.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Sequence
+
+
+@dataclass(frozen=True)
+class Operation:
+    name: str
+    qubits: tuple[int, ...]
+    params: tuple[str, ...]
+    line_index: int
+    op_index: int
+    is_measure: bool = False
+    is_barrier: bool = False
+    is_reset: bool = False
+    is_custom: bool = False
+
+    @property
+    def arity(self) -> int:
+        return len(self.qubits)
+
+
+@dataclass(frozen=True)
+class CircuitIR:
+    n_qubits: int
+    n_cbits: int
+    operations: tuple[Operation, ...]
+    qasm_format: str  # "qasm2" | "qasm3" | "unknown"
+
+    @property
+    def source_format(self) -> str:
+        # Future-facing alias (QIR, QASM3, etc.)
+        return self.qasm_format
+
+    @property
+    def n_ops(self) -> int:
+        return len(self.operations)
+
+    def iter_ops(self) -> Sequence[Operation]:
+        return self.operations

qcoder/engines/feature_extraction/labeling.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from .ir import CircuitIR
+
+
+def _name_hint(name: str) -> str | None:
+    s = name.strip().lower()
+    if not s:
+        return None
+
+    # Small, deterministic keyword map (expand later as needed)
+    if "qft" in s:
+        return "qft"
+    if "qaoa" in s:
+        return "qaoa"
+    if "grover" in s:
+        return "grover"
+    if "ucc" in s or "vqe" in s:
+        return "vqe_ucc"
+    if "adder" in s or "arith" in s or "mult" in s:
+        return "arithmetic"
+    if "qnn" in s or "ansatz" in s or "vqc" in s:
+        return "variational"
+    return None
+
+
+def infer_function(circuit_name: str | None, ir: CircuitIR) -> tuple[str, str]:
+    """
+    Returns: (function_hint, source) where source ∈ {"name", "qasm", "unknown"}.
+
+    Keep categories small/stable. This is metadata for models to optionally consume.
+    """
+    if circuit_name:
+        h = _name_hint(circuit_name)
+        if h is not None:
+            return (h, "name")
+
+    # QASM-derived minimal heuristics (cheap + robust)
+    counts: dict[str, int] = {}
+    n_gate = 0
+    n_param = 0
+
+    for op in ir.operations:
+        if op.is_measure or op.is_barrier or op.is_reset:
+            continue
+        if not op.qubits:
+            continue
+        n_gate += 1
+        counts[op.name] = counts.get(op.name, 0) + 1
+        if op.params:
+            n_param += 1
+
+    ccx = counts.get("ccx", 0)
+    cp_like = counts.get("cp", 0) + counts.get("cu1", 0)
+    h = counts.get("h", 0)
+
+    if ccx > 0:
+        return ("arithmetic", "qasm")
+
+    # Very rough QFT signal: many controlled-phase-like ops + some H
+    if cp_like >= 3 and h >= 1 and cp_like >= int(0.25 * max(1, n_gate)):
+        return ("qft", "qasm")
+
+    # Variational-ish: lots of parameterized rotations
+    if n_gate >= 10 and n_param >= int(0.30 * n_gate):
+        return ("variational", "qasm")
+
+    return ("unknown", "unknown")

qcoder/engines/feature_extraction/parsers/__init__.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from ..ir import CircuitIR
+from ..qasm2_regex_parser import parse_qasm2_file, parse_qasm2_text
+
+__all__ = ["parse_circuit_file", "parse_qasm2_file", "parse_qasm2_text"]
+
+
+def parse_circuit_file(path: str) -> CircuitIR:
+    """
+    Parser routing point.
+    Today: OpenQASM2 (regex parser).
+    Future: OpenQASM3, QIR, other IR adapters.
+    """
+    ir = parse_qasm2_file(path)
+
+    # For now: we accept qasm2 and unknown headers (still parseable),
+    # but explicitly reject qasm3 until implemented.
+    if ir.qasm_format == "qasm3":
+        raise NotImplementedError("OpenQASM 3 parsing is not implemented yet.")
+    return ir

qcoder/engines/feature_extraction/qasm2_regex_parser.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from .ir import CircuitIR, Operation
+
+
+_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+([A-Za-z_]\w*)\s*\[\s*(\d+)\s*\]\s*;\s*$")
+_RE_OPENQASM2 = re.compile(r"^\s*OPENQASM\s+2(\.\d+)?\s*;\s*$", re.IGNORECASE)
+_RE_OPENQASM3 = re.compile(r"^\s*OPENQASM\s+3(\.\d+)?\s*;\s*$", re.IGNORECASE)
+_RE_INCLUDE = re.compile(r'^\s*include\s+"[^"]+"\s*;\s*$', re.IGNORECASE)
+
+# op forms: name(params?) q[i],q[j];
+_RE_OP = re.compile(
+    r"^\s*([A-Za-z_]\w*)\s*(\([^)]*\))?\s+(.+?)\s*;\s*$"
+)
+
+# qubit ref: q[12]
+_RE_QREF = re.compile(r"([A-Za-z_]\w*)\s*\[\s*(\d+)\s*\]")
+
+
+@dataclass(frozen=True)
+class _Regs:
+    qreg_base: dict[str, int]
+    qreg_size: dict[str, int]
+    n_qubits: int
+    n_cbits: int
+
+
+def _strip_inline_comment(line: str) -> str:
+    # QASM2 line comments start with //
+    idx = line.find("//")
+    return line[:idx] if idx >= 0 else line
+
+
+def _detect_format(lines: list[str]) -> str:
+    for raw in lines:
+        s = raw.strip()
+        if not s or s.startswith("//"):
+            continue
+        if _RE_OPENQASM3.match(s):
+            return "qasm3"
+        if _RE_OPENQASM2.match(s):
+            return "qasm2"
+        break
+    return "unknown"
+
+
+def _build_regs(lines: list[str]) -> _Regs:
+    qreg_base: dict[str, int] = {}
+    qreg_size: dict[str, int] = {}
+    n_qubits = 0
+    n_cbits = 0
+
+    for raw in lines:
+        s = raw.strip()
+        if not s:
+            continue
+
+        m = _RE_QREG.match(s)
+        if m:
+            name = m.group(1)
+            size = int(m.group(2))
+            if name not in qreg_base:
+                qreg_base[name] = n_qubits
+                qreg_size[name] = size
+                n_qubits += size
+            continue
+
+        m = _RE_CREG.match(s)
+        if m:
+            size = int(m.group(2))
+            n_cbits += size
+            continue
+
+    return _Regs(qreg_base=qreg_base, qreg_size=qreg_size, n_qubits=n_qubits, n_cbits=n_cbits)
+
+
+def _flatten_qubits(arg_str: str, regs: _Regs) -> tuple[int, ...]:
+    # find all qref occurrences in the operand string
+    out: list[int] = []
+    for reg_name, idx_str in _RE_QREF.findall(arg_str):
+        if reg_name not in regs.qreg_base:
+            continue
+        idx = int(idx_str)
+        size = regs.qreg_size[reg_name]
+        if 0 <= idx < size:
+            out.append(regs.qreg_base[reg_name] + idx)
+    return tuple(out)
+
+
+def _parse_qasm2_lines(lines: list[str]) -> CircuitIR:
+    fmt = _detect_format(lines)
+    regs = _build_regs(lines)
+
+    ops: list[Operation] = []
+    op_index = 0
+
+    for line_index, s in enumerate(lines):
+        if not s:
+            continue
+        if _RE_OPENQASM2.match(s) or _RE_OPENQASM3.match(s) or _RE_INCLUDE.match(s):
+            continue
+        if _RE_QREG.match(s) or _RE_CREG.match(s):
+            continue
+
+        # recognize common non-gate statements
+        low = s.lower()
+        if low.startswith("barrier"):
+            qubits = _flatten_qubits(s, regs)
+            ops.append(Operation("barrier", qubits, (), line_index, op_index, is_barrier=True))
+            op_index += 1
+            continue
+        if low.startswith("reset"):
+            qubits = _flatten_qubits(s, regs)
+            ops.append(Operation("reset", qubits, (), line_index, op_index, is_reset=True))
+            op_index += 1
+            continue
+        if low.startswith("measure"):
+            qubits = _flatten_qubits(s, regs)
+            ops.append(Operation("measure", qubits, (), line_index, op_index, is_measure=True))
+            op_index += 1
+            continue
+
+        m = _RE_OP.match(s)
+        if not m:
+            # unknown construct; count as a custom op with no qubits
+            ops.append(Operation("custom", (), (), line_index, op_index, is_custom=True))
+            op_index += 1
+            continue
+
+        name = m.group(1)
+        params_raw = (m.group(2) or "").strip()
+        operands = (m.group(3) or "").strip()
+
+        params: tuple[str, ...] = ()
+        if params_raw.startswith("(") and params_raw.endswith(")"):
+            inside = params_raw[1:-1].strip()
+            if inside:
+                params = tuple(x.strip() for x in inside.split(",") if x.strip())
+
+        qubits = _flatten_qubits(operands, regs)
+
+        is_custom = False
+        if not name or (not qubits and name not in {"id"}):
+            is_custom = True
+            name = "custom"
+
+        ops.append(Operation(name=name.lower(), qubits=qubits, params=params, line_index=line_index, op_index=op_index, is_custom=is_custom))
+        op_index += 1
+
+    return CircuitIR(
+        n_qubits=regs.n_qubits,
+        n_cbits=regs.n_cbits,
+        operations=tuple(ops),
+        qasm_format=fmt,
+    )
+
+
+def parse_qasm2_text(qasm_text: str, *, source_label: str | None = None) -> CircuitIR:
+    """
+    Parse OpenQASM 2 source from a string. Same IR as parse_qasm2_file for identical content.
+
+    Does not raise for OpenQASM 3 headers; consumers that need rejection should use
+    parse_circuit_file() or check ir.qasm_format.
+
+    source_label: optional provenance string for future diagnostics (unused today).
+    """
+    _ = source_label  # reserved for error-context diagnostics
+    raw_lines = qasm_text.splitlines()
+    lines: list[str] = []
+    for raw in raw_lines:
+        stripped = _strip_inline_comment(raw).strip()
+        lines.append(stripped)
+    return _parse_qasm2_lines(lines)
+
+
+def parse_qasm2_file(path: str) -> CircuitIR:
+    p = Path(path)
+    text = p.read_text(encoding="utf-8", errors="replace")
+    return parse_qasm2_text(text)