hipbridge 0.1.0__py3-none-any.whl

hipbridge/__init__.py

@@ -0,0 +1,69 @@
+"""hipbridge: recognize CUDA kernels, substitute verified AMD implementations.
+
+Core imports cleanly with libclang alone. The heavy pieces live behind extras
+and are reached through hipbridge.kernels / hipbridge.verify, each of which exposes
+available() so callers can degrade instead of crashing.
+
+`parse_file` and `parse_source` are re-exported lazily. They come from
+frontend.parser, which imports clang.cindex at module level, and importing any
+submodule of a package runs that package's __init__ first. So an eager
+re-export here meant `import hipbridge.verify.provenance` loaded libclang: a
+dependency the [verify] extra does not declare and has no use for.
+
+Everything else stays eager, and cheaply: analysis is pure arithmetic over
+datasheet figures and frontend.ir is stdlib dataclasses.
+
+The recognizer package is `hipbridge.recognizers`, plural, so that `recognize`
+names one thing. It was `hipbridge.recognize`, which collided with the function
+re-exported here under the same name: two objects, one name, one namespace, and
+whichever was assigned last won. Eager assignment made the function win, so the
+collision was invisible until someone made the import lazy - and then it failed
+only in full runs, because a module-level __getattr__ is consulted after
+__dict__, and the import system writes a submodule into its parent's __dict__ on
+first load. `recognize(facts)` raised "'module' object is not callable" in a
+full test run and passed in isolation.
+"""
+
+from typing import TYPE_CHECKING
+
+from hipbridge.analysis import ARCHS, lds_padding, occupancy, roofline
+from hipbridge.frontend import KernelFacts, Pattern, Recognition
+from hipbridge.recognizers import recognize, registered
+
+__version__ = "0.1.0"
+
+# Defined in hipbridge.frontend.parser, which costs a libclang import.
+_LAZY = ("parse_file", "parse_source")
+
+if TYPE_CHECKING:  # pragma: no cover - for type checkers and editors only
+    from hipbridge.frontend import parse_file, parse_source
+
+
+def __getattr__(name: str):
+    if name not in _LAZY:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    from hipbridge import frontend
+
+    value = getattr(frontend, name)
+    globals()[name] = value  # resolved once, then a plain attribute
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)
+
+
+__all__ = [
+    "ARCHS",
+    "KernelFacts",
+    "Pattern",
+    "Recognition",
+    "__version__",
+    "lds_padding",
+    "occupancy",
+    "parse_file",
+    "parse_source",
+    "recognize",
+    "registered",
+    "roofline",
+]

hipbridge/analysis/__init__.py

@@ -0,0 +1,80 @@
+"""AMD hardware analysis. Pure arithmetic over published vendor specifications.
+
+Every number here is a datasheet figure, NOT a measurement on your device.
+Anything derived from these is a ceiling, not a result. Use hipbridge.verify to
+find out what your hardware actually does.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ArchSpec:
+    name: str
+    gfx: str
+    wavefront: int
+    simds_per_cu: int
+    vgprs_per_simd: int
+    lds_bytes_per_cu: int
+    hbm_tb_s: float
+    peak_fp16_tflops: float
+    source: str = "vendor datasheet"
+
+
+ARCHS: dict[str, ArchSpec] = {
+    "cdna3": ArchSpec("MI300X", "gfx942", 64, 4, 512, 65536, 5.3, 1307.4),
+    "cdna2": ArchSpec("MI250X", "gfx90a", 64, 4, 512, 65536, 3.2, 383.0),
+    "cdna1": ArchSpec("MI100", "gfx908", 64, 4, 256, 65536, 1.2, 184.6),
+    "rdna3": ArchSpec("RX 7900 XTX", "gfx1100", 32, 2, 512, 131072, 0.96, 122.8),
+}
+
+
+def occupancy(vgprs_per_thread: int, arch: str = "cdna3") -> dict:
+    """Wavefront occupancy per SIMD, which on AMD is VGPR limited."""
+    spec = ARCHS[arch]
+    if vgprs_per_thread <= 0:
+        raise ValueError("vgprs_per_thread must be positive")
+    max_waves = 8 if spec.wavefront == 64 else 16
+    waves = min(max_waves, spec.vgprs_per_simd // vgprs_per_thread)
+    return {
+        "arch": spec.name,
+        "gfx": spec.gfx,
+        "wavefronts_per_simd": waves,
+        "occupancy_pct": round(100.0 * waves / max_waves, 1),
+        "limited_by": "vgpr" if waves < max_waves else "none",
+        "basis": "datasheet, not measured",
+    }
+
+
+def roofline(flops: float, bytes_moved: float, arch: str = "cdna3") -> dict:
+    """Classify a kernel as compute or memory bound against the arch ceiling."""
+    spec = ARCHS[arch]
+    if bytes_moved <= 0:
+        raise ValueError("bytes_moved must be positive")
+    intensity = flops / bytes_moved
+    bw = spec.hbm_tb_s * 1e12
+    peak = spec.peak_fp16_tflops * 1e12
+    ridge = peak / bw
+    attainable = min(peak, intensity * bw)
+    return {
+        "arch": spec.name,
+        "arithmetic_intensity": round(intensity, 4),
+        "ridge_point": round(ridge, 2),
+        "bound": "compute" if intensity >= ridge else "memory",
+        "attainable_tflops": round(attainable / 1e12, 2),
+        "peak_tflops": spec.peak_fp16_tflops,
+        "basis": "datasheet ceiling, not measured",
+    }
+
+
+def lds_padding(row_elems: int, elem_bytes: int = 4, banks: int = 32) -> int:
+    """Padding in elements to break LDS bank conflicts on a 2D shared tile."""
+    if elem_bytes <= 0 or row_elems <= 0:
+        raise ValueError("row_elems and elem_bytes must be positive")
+    elems_per_bank_cycle = banks
+    return 0 if row_elems % elems_per_bank_cycle else 1
+
+
+__all__ = ["ARCHS", "ArchSpec", "lds_padding", "occupancy", "roofline"]