simdref 0.0.0__py3-none-any.whl

simdref/perf_sources/merge.py

@@ -0,0 +1,121 @@
+"""Attach ingested perf rows onto existing :class:`InstructionRecord` data."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Iterable
+
+from simdref.models import InstructionRecord
+
+
+@dataclass(frozen=True)
+class PerfRow:
+    """A single perf observation produced by a perf_sources ingester.
+
+    Attributes map onto the provenance keys stored in
+    ``InstructionRecord.arch_details[core]`` so :func:`merge_perf_rows` can
+    drop them in verbatim.
+    """
+
+    mnemonic: str
+    core: str
+    source: str
+    source_kind: str  # "measured" | "modeled"
+    source_version: str
+    architecture: str = ""
+    form: str = ""
+    latency: str = ""
+    cpi: str = ""
+    applies_to: str = "mnemonic"
+    citation_url: str = ""
+    extra_measurement: dict[str, str] = field(default_factory=dict)
+
+    def as_arch_details_entry(self) -> dict[str, Any]:
+        entry: dict[str, Any] = {
+            "source": self.source,
+            "source_kind": self.source_kind,
+            "source_version": self.source_version,
+            "applies_to": self.applies_to,
+            "citation_url": self.citation_url,
+        }
+        if self.latency:
+            entry["latencies"] = [{"cycles": self.latency}]
+        measurement: dict[str, str] = dict(self.extra_measurement)
+        if self.cpi:
+            # ``TP_loop`` is the column the TUI and CLI measurement tables
+            # already render under the "CPI" header, so modeled rows must
+            # land there to surface at all. ``TP`` is retained as a
+            # duplicate for any downstream consumer that still reads the
+            # legacy key.
+            measurement.setdefault("TP_loop", self.cpi)
+            measurement.setdefault("TP", self.cpi)
+        if measurement:
+            entry["measurement"] = measurement
+        return entry
+
+
+def _record_key(record: InstructionRecord) -> tuple[str, str, str]:
+    return (
+        record.architecture.casefold(),
+        record.mnemonic.casefold(),
+        record.form.strip().casefold(),
+    )
+
+
+def merge_perf_rows(
+    records: Iterable[InstructionRecord],
+    rows: Iterable[PerfRow],
+    *,
+    overwrite: bool = False,
+) -> int:
+    """Merge *rows* into matching records in-place.
+
+    Matching rule: a row attaches to every record with the same architecture
+    and mnemonic. If ``row.form`` is non-empty, only records with the
+    matching form are updated (case-insensitive). Otherwise the row applies
+    to every variant of the mnemonic (``applies_to="mnemonic"``).
+
+    ``overwrite=False`` (default) preserves existing ``arch_details[core]``
+    entries so measured data produced by earlier passes is never clobbered
+    by modeled data from a later pass.
+
+    Returns the number of ``arch_details[core]`` entries newly written.
+    """
+    records = list(records)
+    by_arch_mnemonic: dict[tuple[str, str], list[InstructionRecord]] = {}
+    for record in records:
+        by_arch_mnemonic.setdefault(
+            (record.architecture.casefold(), record.mnemonic.casefold()),
+            [],
+        ).append(record)
+
+    written = 0
+    for row in rows:
+        targets = by_arch_mnemonic.get(
+            (row.architecture.casefold() or _arch_guess(row.core), row.mnemonic.casefold()),
+            [],
+        )
+        if not targets:
+            continue
+        form_key = row.form.strip().casefold()
+        matched = [r for r in targets if not form_key or r.form.strip().casefold() == form_key]
+        if not matched and form_key:
+            matched = targets  # graceful fallback: attach to every variant
+        entry = row.as_arch_details_entry()
+        for record in matched:
+            if not overwrite and row.core in record.arch_details:
+                continue
+            record.arch_details[row.core] = entry
+            written += 1
+    return written
+
+
+def _arch_guess(core: str) -> str:
+    """Best-effort architecture lookup used when :class:`PerfRow` lacks one."""
+    from simdref.perf_sources.cores import core_architecture
+    arch = core_architecture(core)
+    if arch == "aarch64":
+        return "arm"
+    if arch == "riscv":
+        return "riscv"
+    return arch or ""

simdref/queries.py

@@ -0,0 +1,207 @@
+"""Shared record-linking and lookup helpers.
+
+Functions here resolve relationships between intrinsics and instructions,
+optionally using a SQLite connection for fast lookups or falling back to
+in-memory catalog scans.  They are used by the CLI, LSP, and man-page
+modules.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from typing import TYPE_CHECKING
+
+from simdref.perf import variant_perf_summary
+from simdref.storage import load_instruction_from_db
+
+SOURCE_KINDS: tuple[str, ...] = ("measured", "modeled", "any")
+
+
+def filter_arch_details_by_source_kind(
+    arch_details: dict[str, dict[str, object]],
+    source_kind: str,
+) -> dict[str, dict[str, object]]:
+    """Drop ``arch_details`` entries whose provenance does not match.
+
+    ``"any"`` (or empty) keeps everything; ``"measured"`` / ``"modeled"``
+    keep only entries whose ``source_kind`` field matches (legacy entries
+    without a ``source_kind`` key are treated as measured).
+    """
+    if source_kind in ("", "any"):
+        return arch_details
+    kept: dict[str, dict[str, object]] = {}
+    for core, details in arch_details.items():
+        kind = details.get("source_kind") or "measured"
+        if kind == source_kind:
+            kept[core] = details
+    return kept
+
+if TYPE_CHECKING:
+    from simdref.models import Catalog, InstructionRecord, IntrinsicRecord
+
+
+def linked_instruction_records(
+    catalog: Catalog | None,
+    intrinsic: IntrinsicRecord,
+    conn: sqlite3.Connection | None = None,
+) -> list[InstructionRecord]:
+    """Return instruction records linked to *intrinsic*.
+
+    When *conn* is provided, performs fast DB lookups by instruction key.
+    Otherwise falls back to scanning ``catalog.instructions``.
+    """
+    ref_keys = [
+        ref.get("key", "").strip()
+        for ref in intrinsic.instruction_refs
+        if isinstance(ref, dict) and ref.get("key", "").strip()
+    ]
+    if conn is not None:
+        linked: list[InstructionRecord] = []
+        keys = ref_keys or intrinsic.instructions
+        for instruction_key in keys:
+            instruction = load_instruction_from_db(conn, instruction_key)
+            if instruction is not None:
+                linked.append(instruction)
+        return linked
+    if catalog is None:
+        return []
+    return [
+        instruction
+        for instruction in catalog.instructions
+        if intrinsic.name in instruction.linked_intrinsics
+    ]
+
+
+def build_intrinsic_instruction_index(
+    catalog: Catalog,
+) -> dict[str, list[InstructionRecord]]:
+    """Invert ``catalog.instructions`` into an ``intrinsic name → instructions`` map.
+
+    One linear pass replaces the quadratic per-intrinsic scan performed by
+    :func:`instruction_rows_for_intrinsic`, turning ``O(intrinsics × instructions)``
+    into ``O(intrinsics + instructions)``.
+    """
+    index: dict[str, list[InstructionRecord]] = {}
+    for instruction in catalog.instructions:
+        for name in instruction.linked_intrinsics:
+            index.setdefault(name, []).append(instruction)
+    return index
+
+
+def _rows_from_linked_instructions(
+    linked: list[InstructionRecord],
+) -> list[dict]:
+    rows: list[dict] = []
+    for instruction in linked:
+        if instruction.metrics:
+            for arch, values in sorted(instruction.metrics.items()):
+                row = {"instruction": instruction.key, "uarch": arch}
+                row.update(values)
+                rows.append(row)
+        else:
+            rows.append({
+                "instruction": instruction.key,
+                "uarch": "-",
+                "latency": "-",
+                "throughput": "-",
+                "uops": "-",
+                "ports": "-",
+            })
+    return rows
+
+
+def instruction_rows_for_intrinsic_indexed(
+    linked: list[InstructionRecord],
+) -> list[dict]:
+    """Variant of :func:`instruction_rows_for_intrinsic` that takes a prebuilt list."""
+    return _rows_from_linked_instructions(linked)
+
+
+def instruction_rows_for_intrinsic(
+    catalog: Catalog,
+    intrinsic: IntrinsicRecord,
+) -> list[dict]:
+    """Build per-microarchitecture metric rows for an intrinsic's linked instructions.
+
+    Returns a list of dicts with keys ``instruction``, ``uarch``, and
+    whatever metric columns the instruction exposes (``latency``,
+    ``throughput``, ``uops``, ``ports``).
+    """
+    rows: list[dict] = []
+    for instruction in catalog.instructions:
+        if intrinsic.name not in instruction.linked_intrinsics:
+            continue
+        if instruction.metrics:
+            for arch, values in sorted(instruction.metrics.items()):
+                row = {"instruction": instruction.key, "uarch": arch}
+                row.update(values)
+                rows.append(row)
+        else:
+            rows.append({
+                "instruction": instruction.key,
+                "uarch": "-",
+                "latency": "-",
+                "throughput": "-",
+                "uops": "-",
+                "ports": "-",
+            })
+    return rows
+
+
+def intrinsic_perf_summary(
+    catalog: Catalog,
+    intrinsic: IntrinsicRecord,
+) -> tuple[str, str]:
+    """Return ``(best_latency, best_cpi)`` across all linked instruction variants.
+
+    Scans every instruction linked to *intrinsic* in the in-memory catalog.
+    """
+    from simdref.perf import best_numeric
+
+    linked = linked_instruction_records(catalog, intrinsic)
+    latencies: list[str] = []
+    throughput: list[str] = []
+    for item in linked:
+        lat, cpi = variant_perf_summary(item.arch_details)
+        if lat != "-":
+            latencies.append(lat)
+        if cpi != "-":
+            throughput.append(cpi)
+    return best_numeric(latencies), best_numeric(throughput)
+
+
+def intrinsic_perf_summary_runtime(
+    conn: sqlite3.Connection,
+    intrinsic: IntrinsicRecord,
+    instruction_map: dict[str, object],
+) -> tuple[str, str]:
+    """Like :func:`intrinsic_perf_summary` but uses DB + a mutable cache.
+
+    Resolves linked instructions via *instruction_map* (populated during
+    search) and falls back to ``load_instruction_from_db`` for cache misses.
+    """
+    from simdref.perf import best_numeric
+
+    ref_keys = [
+        ref.get("key", "").strip()
+        for ref in intrinsic.instruction_refs
+        if isinstance(ref, dict) and ref.get("key", "").strip()
+    ]
+    linked: list[InstructionRecord] = []
+    keys = ref_keys or intrinsic.instructions
+    for key in keys:
+        instruction = instruction_map.get(key)
+        if instruction is None:
+            instruction = load_instruction_from_db(conn, key)
+            if instruction is not None:
+                instruction_map[key] = instruction
+        if instruction is not None:
+            linked.append(instruction)
+    if not linked:
+        return "-", "-"
+    perf_pairs = [variant_perf_summary(record.arch_details) for record in linked]
+    latencies = [float(lat) for lat, _ in perf_pairs if lat not in {"-", ""}]
+    cpis = [float(cpi_value) for _, cpi_value in perf_pairs if cpi_value not in {"-", ""}]
+    lat = str(min(latencies)).rstrip("0").rstrip(".") if latencies else "-"
+    cpi = f"{min(cpis):.2f}" if cpis else "-"
+    return lat, cpi