qcoder 0.1.0a0__py3-none-any.whl

qcoder/engines/feature_extraction/reps/cut_profile.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+from typing import Dict, List
+
+from .interaction_graph import InteractionGraph
+
+
+@dataclass(frozen=True)
+class CutProfileStats:
+    # raw cut array (len = max(n_qubits-1, 0)), natural order only
+    cut_profile: tuple[float, ...]
+    # summary metrics
+    cut_max: float
+    cut_mean: float
+    cut_std: float
+    cut_entropy: float
+    n_active_cuts: int
+    max_span_in_order: int
+
+
+def compute_cut_profile_stats(ig: InteractionGraph) -> CutProfileStats:
+    """
+    Natural-order cut profile.
+
+    Qubit order: [0, 1, ..., n-1]
+    Cut k is between qubits k and k+1, for k=0..n-2.
+
+    For each interaction edge (u, v) with u < v and weight w:
+      it crosses cuts k in [u, v-1]
+      add w to each crossed cut bucket.
+    """
+    n = int(ig.n_qubits)
+    m = max(n - 1, 0)
+    cut: List[float] = [0.0] * m
+
+    max_span = 0
+
+    if m > 0:
+        for (u, v), w_int in ig.edges.items():
+            # ig guarantees u < v, but keep deterministic safety
+            a, b = (u, v) if u <= v else (v, u)
+            if a == b:
+                continue
+            if a < 0 or b < 0 or a >= n or b >= n:
+                continue
+
+            w = float(w_int)
+            if w == 0.0:
+                continue
+
+            span = b - a
+            if span > max_span:
+                max_span = span
+
+            # crosses cuts a, a+1, ..., b-1
+            # (each cut index k corresponds to boundary between k and k+1)
+            for k in range(a, b):
+                if 0 <= k < m:
+                    cut[k] += w
+
+    # metrics over ALL cuts (including zeros)
+    if not cut:
+        return CutProfileStats(
+            cut_profile=tuple(),
+            cut_max=0.0,
+            cut_mean=0.0,
+            cut_std=0.0,
+            cut_entropy=0.0,
+            n_active_cuts=0,
+            max_span_in_order=0,
+        )
+
+    cut_max = max(cut)
+    cut_mean = sum(cut) / len(cut)
+
+    # population std (matches spans.py style: divide by n)
+    var = sum((x - cut_mean) ** 2 for x in cut) / len(cut)
+    cut_std = var ** 0.5
+
+    n_active = sum(1 for x in cut if x > 0.0)
+
+    # normalized Shannon entropy over distribution p_i = cut_i / sum(cut)
+    total = sum(cut)
+    if total <= 0.0 or len(cut) <= 1:
+        cut_entropy = 0.0
+    else:
+        H = 0.0
+        for x in cut:
+            if x <= 0.0:
+                continue
+            p = x / total
+            H -= p * math.log(p)
+        denom = math.log(len(cut))
+        cut_entropy = (H / denom) if denom > 0.0 else 0.0
+
+    return CutProfileStats(
+        cut_profile=tuple(float(x) for x in cut),
+        cut_max=float(cut_max),
+        cut_mean=float(cut_mean),
+        cut_std=float(cut_std),
+        cut_entropy=float(cut_entropy),
+        n_active_cuts=int(n_active),
+        max_span_in_order=int(max_span),
+    )

qcoder/engines/feature_extraction/reps/depth.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..ir import CircuitIR
+
+
+@dataclass(frozen=True)
+class DepthStats:
+    estimated_depth: int   # gate statements count (excludes measure/barrier/reset)
+    real_depth: int        # per-qubit timeline depth proxy
+    avg_parallel_gates: float
+    parallelism_factor: float
+
+
+def compute_depth_stats(ir: CircuitIR) -> DepthStats:
+    t = [0] * max(ir.n_qubits, 1)
+
+    gate_ops = 0
+    for op in ir.operations:
+        if op.is_measure or op.is_barrier or op.is_reset:
+            continue
+        if not op.qubits:
+            continue
+        gate_ops += 1
+        mx = 0
+        for q in op.qubits:
+            if 0 <= q < len(t):
+                if t[q] > mx:
+                    mx = t[q]
+        nxt = mx + 1
+        for q in op.qubits:
+            if 0 <= q < len(t):
+                t[q] = nxt
+
+    real_depth = max(t) if t else 0
+    estimated_depth = gate_ops
+
+    avg_parallel = (gate_ops / real_depth) if real_depth > 0 else 0.0
+    parallelism_factor = (gate_ops / (real_depth * ir.n_qubits)) if (real_depth > 0 and ir.n_qubits > 0) else 0.0
+
+    return DepthStats(
+        estimated_depth=estimated_depth,
+        real_depth=real_depth,
+        avg_parallel_gates=float(avg_parallel),
+        parallelism_factor=float(parallelism_factor),
+    )

qcoder/engines/feature_extraction/reps/entangling_layers.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass
+from typing import List
+
+from ..ir import CircuitIR, Operation
+
+
+def _is_gate_op(op: Operation) -> bool:
+    return not (op.is_measure or op.is_barrier or op.is_reset) and len(op.qubits) > 0
+
+
+def _is_entangling_op(op: Operation) -> bool:
+    return _is_gate_op(op) and len(op.qubits) >= 2
+
+
+@dataclass(frozen=True)
+class EntanglingLayerStats:
+    entangling_depth: int
+    n_entangling_layers: int
+    avg_2q_per_entangling_layer: float
+    max_2q_per_entangling_layer: int
+
+
+def compute_entangling_layer_stats(ir: CircuitIR) -> EntanglingLayerStats:
+    n = max(ir.n_qubits, 1)
+    t: List[int] = [0] * n
+
+    # layer -> count of 2Q ops in that layer
+    layer_2q_count: dict[int, int] = defaultdict(int)
+    total_2q_ops = 0
+
+    for op in ir.operations:
+        if not _is_entangling_op(op):
+            continue
+        qubits = [q for q in op.qubits if 0 <= q < n]
+        if not qubits:
+            continue
+        layer = 1 + max(t[q] for q in qubits)
+        for q in qubits:
+            t[q] = layer
+        if op.arity == 2:
+            layer_2q_count[layer] += 1
+            total_2q_ops += 1
+
+    entangling_depth = max(t) if t else 0
+    n_entangling_layers = len(layer_2q_count)
+    avg_2q = total_2q_ops / max(n_entangling_layers, 1)
+    max_2q = max(layer_2q_count.values()) if layer_2q_count else 0
+
+    return EntanglingLayerStats(
+        entangling_depth=entangling_depth,
+        n_entangling_layers=n_entangling_layers,
+        avg_2q_per_entangling_layer=float(avg_2q),
+        max_2q_per_entangling_layer=max_2q,
+    )

qcoder/engines/feature_extraction/reps/gate_set_stats.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..ir import CircuitIR, Operation
+
+BASIS_CHANGE_NAMES = frozenset({"h", "rx", "ry", "u", "u1", "u2", "u3"})
+DIAGONAL_NAMES = frozenset({"z", "s", "sdg", "t", "tdg", "rz", "u1", "cp", "cz", "ccz", "rzz"})
+T_LIKE_NAMES = frozenset({"t", "tdg"})
+CLIFFORD_LIKE_ANGLE_TOKENS = frozenset({
+    "pi/2", "-pi/2", "pi", "-pi", "0", "pi/4", "-pi/4", "pi/8", "-pi/8", "0.0",
+})
+
+
+def _is_gate_op(op: Operation) -> bool:
+    return not (op.is_measure or op.is_barrier or op.is_reset) and len(op.qubits) > 0
+
+
+@dataclass(frozen=True)
+class GateSetStats:
+    n_basis_change_ops: int
+    basis_change_qubit_coverage: float
+    n_diagonal_gate_ops: int
+    diagonal_gate_fraction: float
+    n_t_like_ops: int
+    n_distinct_angles: int
+    angle_genericity_ratio: float
+    is_certified_diagonal_only: int  # 0 or 1
+
+
+def compute_gate_set_stats(ir: CircuitIR) -> GateSetStats:
+    gate_ops = [op for op in ir.operations if _is_gate_op(op)]
+    n_gate_ops = len(gate_ops)
+
+    n_basis_change_ops = 0
+    basis_change_qubits: set[int] = set()
+    n_diagonal_gate_ops = 0
+    n_t_like_ops = 0
+    all_diagonal = True
+
+    for op in gate_ops:
+        name = op.name.lower().strip()
+        if name in BASIS_CHANGE_NAMES:
+            n_basis_change_ops += 1
+            basis_change_qubits.update(op.qubits)
+        if name in DIAGONAL_NAMES:
+            n_diagonal_gate_ops += 1
+        else:
+            all_diagonal = False
+        if name in T_LIKE_NAMES:
+            n_t_like_ops += 1
+
+    n_q = max(ir.n_qubits, 1)
+    basis_change_qubit_coverage = len(basis_change_qubits) / n_q if n_q else 0.0
+    diagonal_gate_fraction = n_diagonal_gate_ops / max(n_gate_ops, 1)
+
+    angle_tokens: set[str] = set()
+    for op in gate_ops:
+        for p in op.params:
+            t = p.strip()
+            if t:
+                angle_tokens.add(t)
+
+    n_distinct_angles = len(angle_tokens)
+    if n_distinct_angles == 0:
+        angle_genericity_ratio = 0.0
+    else:
+        non_clifford = sum(1 for t in angle_tokens if t not in CLIFFORD_LIKE_ANGLE_TOKENS)
+        angle_genericity_ratio = non_clifford / n_distinct_angles
+
+    is_certified_diagonal_only = 1 if (n_gate_ops > 0 and all_diagonal) else 0
+
+    return GateSetStats(
+        n_basis_change_ops=n_basis_change_ops,
+        basis_change_qubit_coverage=basis_change_qubit_coverage,
+        n_diagonal_gate_ops=n_diagonal_gate_ops,
+        diagonal_gate_fraction=diagonal_gate_fraction,
+        n_t_like_ops=n_t_like_ops,
+        n_distinct_angles=n_distinct_angles,
+        angle_genericity_ratio=angle_genericity_ratio,
+        is_certified_diagonal_only=is_certified_diagonal_only,
+    )

qcoder/engines/feature_extraction/reps/interaction_graph.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..ir import CircuitIR
+
+
+@dataclass(frozen=True)
+class InteractionGraph:
+    n_qubits: int
+    edges: dict[tuple[int, int], int]  # (u,v)->weight, u<v
+
+
+def build_interaction_graph(ir: CircuitIR) -> InteractionGraph:
+    edges: dict[tuple[int, int], int] = {}
+    for op in ir.operations:
+        if op.is_measure or op.is_barrier or op.is_reset:
+            continue
+        if len(op.qubits) < 2:
+            continue
+        qs = op.qubits
+        # connect all pairs for multi-qubit ops
+        for i in range(len(qs)):
+            for j in range(i + 1, len(qs)):
+                u, v = qs[i], qs[j]
+                if u == v:
+                    continue
+                a, b = (u, v) if u < v else (v, u)
+                edges[(a, b)] = edges.get((a, b), 0) + 1
+    return InteractionGraph(n_qubits=ir.n_qubits, edges=edges)

qcoder/engines/feature_extraction/reps/interaction_graph_metrics.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import math
+from collections import Counter, deque
+from dataclasses import dataclass
+from typing import List
+
+from .interaction_graph import InteractionGraph
+
+
+@dataclass(frozen=True)
+class InteractionGraphMetrics:
+    ig_max_degree: int
+    ig_avg_degree: float
+    ig_degree_std: float
+    ig_degree_entropy: float
+    ig_n_components: int
+    ig_largest_cc_frac: float
+    ig_is_connected: int  # 0 or 1
+    ig_pair_reuse_hhi: float
+    ig_pair_reuse_top1_frac: float
+
+
+def compute_interaction_graph_metrics(ig: InteractionGraph) -> InteractionGraphMetrics:
+    n = max(1, ig.n_qubits)  # treat n_qubits <= 0 as 1 node for safety
+
+    if n == 1:
+        return InteractionGraphMetrics(
+            ig_max_degree=0,
+            ig_avg_degree=0.0,
+            ig_degree_std=0.0,
+            ig_degree_entropy=0.0,
+            ig_n_components=1,
+            ig_largest_cc_frac=1.0,
+            ig_is_connected=1,
+            ig_pair_reuse_hhi=0.0,
+            ig_pair_reuse_top1_frac=0.0,
+        )
+
+    # Build adjacency lists (undirected); nodes 0..n-1
+    adj: List[List[int]] = [[] for _ in range(n)]
+    for (u, v), _ in ig.edges.items():
+        if 0 <= u < n and 0 <= v < n and u != v:
+            adj[u].append(v)
+            adj[v].append(u)
+
+    # Unweighted degree = number of unique neighbors
+    degrees = [len(neighbors) for neighbors in adj]
+
+    # Components via BFS
+    visited = [False] * n
+    components: List[List[int]] = []
+    for start in range(n):
+        if visited[start]:
+            continue
+        comp: List[int] = []
+        q: deque[int] = deque([start])
+        visited[start] = True
+        while q:
+            node = q.popleft()
+            comp.append(node)
+            for nei in adj[node]:
+                if not visited[nei]:
+                    visited[nei] = True
+                    q.append(nei)
+        components.append(comp)
+
+    ig_n_components = len(components)
+    largest_size = max(len(c) for c in components) if components else 0
+    ig_largest_cc_frac = largest_size / n
+    ig_is_connected = 1 if ig_n_components == 1 else 0
+
+    # Degree stats
+    ig_max_degree = max(degrees)
+    ig_avg_degree = sum(degrees) / n
+    variance = sum((d - ig_avg_degree) ** 2 for d in degrees) / n
+    ig_degree_std = math.sqrt(variance) if variance >= 0 else 0.0
+
+    # Normalized degree entropy: distribution over degree values
+    # p_k = count(nodes with degree k) / n; H = -sum p_k log(p_k); normalize by log(m), m = distinct degree values
+    hist = Counter(degrees)
+    distinct_degree_values = len(hist)
+    if distinct_degree_values <= 1:
+        ig_degree_entropy = 0.0
+    else:
+        h = 0.0
+        for k, count in hist.items():
+            p_k = count / n
+            if p_k > 0:
+                h -= p_k * math.log(p_k)
+        ig_degree_entropy = h / math.log(distinct_degree_values)
+
+    # Weighted interaction-pair reuse concentration from pair counts.
+    total_pair_count = sum(int(w) for w in ig.edges.values() if int(w) > 0)
+    if total_pair_count > 0:
+        probs = [int(w) / total_pair_count for w in ig.edges.values() if int(w) > 0]
+        ig_pair_reuse_hhi = sum(p * p for p in probs)
+        ig_pair_reuse_top1_frac = max(int(w) for w in ig.edges.values() if int(w) > 0) / total_pair_count
+    else:
+        ig_pair_reuse_hhi = 0.0
+        ig_pair_reuse_top1_frac = 0.0
+
+    return InteractionGraphMetrics(
+        ig_max_degree=ig_max_degree,
+        ig_avg_degree=ig_avg_degree,
+        ig_degree_std=ig_degree_std,
+        ig_degree_entropy=ig_degree_entropy,
+        ig_n_components=ig_n_components,
+        ig_largest_cc_frac=ig_largest_cc_frac,
+        ig_is_connected=ig_is_connected,
+        ig_pair_reuse_hhi=ig_pair_reuse_hhi,
+        ig_pair_reuse_top1_frac=ig_pair_reuse_top1_frac,
+    )

qcoder/engines/feature_extraction/reps/spans.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..ir import CircuitIR
+
+
+@dataclass(frozen=True)
+class SpanStats:
+    avg_span: float
+    max_span: int
+    span_std: float
+    nearest_neighbor_ratio: float
+    long_range_ratio: float  # span > 1
+    long_range_ratio_early: float
+    long_range_ratio_late: float
+    avg_span_early: float
+    avg_span_late: float
+
+
+def compute_span_stats(ir: CircuitIR) -> SpanStats:
+    gate_ops = [
+        op
+        for op in ir.operations
+        if (not op.is_measure and not op.is_barrier and not op.is_reset and bool(op.qubits))
+    ]
+    split = len(gate_ops) // 2
+    early_gate_ops = gate_ops[:split]
+    late_gate_ops = gate_ops[split:]
+
+    def _half_stats(ops: list) -> tuple[float, float]:
+        half_spans: list[int] = []
+        for op in ops:
+            if len(op.qubits) != 2:
+                continue
+            a, b = op.qubits
+            half_spans.append(abs(a - b))
+        if not half_spans:
+            return 0.0, 0.0
+        n_half = len(half_spans)
+        avg_half = sum(half_spans) / n_half
+        lr_half = sum(1 for x in half_spans if x > 1) / n_half
+        return float(lr_half), float(avg_half)
+
+    long_range_ratio_early, avg_span_early = _half_stats(early_gate_ops)
+    long_range_ratio_late, avg_span_late = _half_stats(late_gate_ops)
+
+    spans: list[int] = []
+    for op in ir.operations:
+        if op.is_measure or op.is_barrier or op.is_reset:
+            continue
+        if len(op.qubits) != 2:
+            continue
+        a, b = op.qubits
+        spans.append(abs(a - b))
+
+    if not spans:
+        return SpanStats(
+            0.0,
+            0,
+            0.0,
+            0.0,
+            0.0,
+            long_range_ratio_early,
+            long_range_ratio_late,
+            avg_span_early,
+            avg_span_late,
+        )
+
+    n = len(spans)
+    avg = sum(spans) / n
+    mx = max(spans)
+    var = sum((x - avg) ** 2 for x in spans) / n
+    std = var ** 0.5
+
+    nn = sum(1 for x in spans if x == 1) / n
+    lr = sum(1 for x in spans if x > 1) / n
+
+    return SpanStats(
+        float(avg),
+        int(mx),
+        float(std),
+        float(nn),
+        float(lr),
+        long_range_ratio_early,
+        long_range_ratio_late,
+        avg_span_early,
+        avg_span_late,
+    )

qcoder/engines/prediction_model/__init__.py

@@ -0,0 +1,16 @@
+# Path: src/qcoder/engines/prediction_model/__init__.py
+from __future__ import annotations
+
+from .artifact import load_artifact, save_artifact
+from .engine import predict
+from .policy import expected_score_for_rung, score_matrix_value
+from .schema_alignment import align_features_to_artifact
+
+__all__ = [
+    "align_features_to_artifact",
+    "expected_score_for_rung",
+    "load_artifact",
+    "predict",
+    "save_artifact",
+    "score_matrix_value",
+]

qcoder/engines/prediction_model/artifact.py

@@ -0,0 +1,85 @@
+# Path: src/qcoder/engines/prediction_model/artifact.py
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+ARTIFACT_VERSION = "0.1.0"
+
+
+def load_artifact(path: str | Path) -> dict[str, Any]:
+    """Load artifact from JSON file."""
+    p = Path(path)
+    text = p.read_text(encoding="utf-8")
+    return json.loads(text)
+
+
+def save_artifact(artifact: dict[str, Any], path: str | Path) -> None:
+    """Write artifact to JSON file."""
+    p = Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(json.dumps(artifact, indent=2, sort_keys=True), encoding="utf-8")
+
+
+def artifact_structure(
+    *,
+    qcoder_schema_version: str,
+    feature_names: list[str],
+    threshold_rungs: list[float],
+    threshold_policy: str = "expected_score",
+    runtime_feature_names: list[str],
+    runtime_intercept: float,
+    runtime_coef: list[float],
+    # fidelity_curve mode (optional); threshold_grid must be integers
+    threshold_stage_mode: str = "ladder",
+    threshold_grid: list[int] | list[float] | None = None,
+    fidelity_target: float = 0.7,
+    fidelity_metric: str = "mirror_fidelity",
+    fidelity_curve_value: float = 0.0,
+    selection_policy: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """
+    Build artifact dict with required keys:
+    artifact_version, qcoder_schema_version, feature_names,
+    threshold_stage (rungs + policy config; mode ladder | fidelity_curve),
+    runtime_stage (threshold-derived feature list + model params).
+    If mode is missing when loading, treat as "ladder" (backward compatible).
+    threshold_grid elements must be integers (validated for fidelity_curve).
+    """
+    thr_stage: dict[str, Any] = {
+        "rungs": list(threshold_rungs),
+        "policy": threshold_policy,
+    }
+    if threshold_stage_mode == "fidelity_curve":
+        raw_grid = list(threshold_grid or threshold_rungs)
+        int_grid: list[int] = []
+        for v in raw_grid:
+            i = int(v)
+            if i != v:
+                raise ValueError(f"threshold_grid must contain integers only, got {v!r}")
+            int_grid.append(i)
+        thr_stage["mode"] = "fidelity_curve"
+        thr_stage["threshold_grid"] = int_grid
+        thr_stage["fidelity_target"] = float(fidelity_target)
+        thr_stage["fidelity_metric"] = str(fidelity_metric)
+        thr_stage["model"] = "ConstantFidelityCurveModel"
+        thr_stage["fidelity_curve_value"] = float(fidelity_curve_value)
+        thr_stage["selection_policy"] = selection_policy or {
+            "type": "min_runtime_subject_to_fidelity",
+            "min_fidelity": float(fidelity_target),
+        }
+    # else: no "mode" key → backward compat as "ladder"
+
+    return {
+        "artifact_version": ARTIFACT_VERSION,
+        "qcoder_schema_version": qcoder_schema_version,
+        "feature_names": list(feature_names),
+        "threshold_stage": thr_stage,
+        "runtime_stage": {
+            "threshold_derived_feature_names": list(runtime_feature_names),
+            "intercept": float(runtime_intercept),
+            "coef": list(runtime_coef),
+        },
+    }