Skip to content

Qwen3.8-Flash-Next on any consumer hardware: one-click install for Windows / Linux. Strata inference engine, OpenAI/Anthropic API on localhost, optional image input.

C++
19.7 KB
Raw Blame
"""The hipBLASLt tuning tables in the AMD engine packages: what a package holds per card family, and the one rule that decides at a start
whether a table is used (strata_control/hipblaslt_tuning.py). Folders are throwaways; no GPU tool is run.

The packages' hipBLASLt versions below are the ones the 0.2.x release packages bundle (docs/AMD_HIP.md, Ready-made packages): Windows ROCm
10.2.0a20260930 carries 1.5.0 (100500), the Linux 7.10.0a20251120 wheels 1.2.0 (100200), Linux Strix Halo's 7.14.1 1.4.1 (100401)."""
from __future__ import annotations

import contextlib
import io
import json
import os
import sys
import tempfile
import unittest
from pathlib import Path
from unittest import mock

from strata_control import hipblaslt_tuning as ht

ROOT = Path(__file__).resolve().parents[2]
TABLES = ROOT / "tools" / "hip"
sys.path.insert(0, str(ROOT / "packaging"))
import package_engine  # noqa: E402
import stage_tuning  # noqa: E402

#: (platform, variant) -> (archs of the package, hipBLASLt version it bundles, architectures that must carry a table)
PACKAGES = {
    ("windows-x86_64", "rx9070"): (("gfx1200", "gfx1201"), 100500, {"gfx1201"}),
    ("windows-x86_64", "rdna3"): (("gfx1100", "gfx1101", "gfx1102", "gfx1151"), 100500, {"gfx1100", "gfx1151"}),
    ("linux-x86_64", "rx9070"): (("gfx1200", "gfx1201"), 100200, set()),                    # no table for 1.2.0 on RDNA4 (docs/AMD_HIP.md)
    ("linux-x86_64", "rx7900"): (("gfx1100", "gfx1101", "gfx1102"), 100200, {"gfx1100"}),
    ("linux-x86_64", "halo"): (("gfx1151",), 100401, {"gfx1151"}),
    # 0.2.2 RX 6000 packages: hipBLASLt ships no gfx1030 / gfx1031 kernels at any version, so no table, plain hipBLAS
    ("windows-x86_64", "rdna2"): (("gfx1030", "gfx1031"), 100500, set()),
    ("linux-x86_64", "rx6000"): (("gfx1030", "gfx1031"), 100400, set()),
}


ON = {ht.SWITCH: "on"}            # the switch that uses a matching table whatever "auto" does
AUTO = {}


def fake_table(folder: Path, arch: str, version: int, *, header: str | None = None) -> Path:
    folder.mkdir(parents=True, exist_ok=True)
    path = folder / ht.table_name(arch, version)
    path.write_text(f"# solution ids are scoped to this hipBLASLt version and device architecture\n"
                    f"{header or f'{ht.HEADER} {arch} {version}'}\nbf16 128 2560 128 4096 73754\n", encoding="utf-8")
    return path


def fake_package(root: Path, *, version: int | None = 100500, tables=(("gfx1201", 100500),), build=True) -> Path:
    folder = root / "0.2.1-pkg"
    folder.mkdir(parents=True)
    meta = {"version": "0.2.1", "backend": "hip"}
    if version is not None:
        meta["hipblaslt_version"] = version
    if build:
        (folder / "BUILD.json").write_text(json.dumps(meta), encoding="utf-8")
    for arch, ver in tables:
        fake_table(folder / ht.TABLE_DIR, arch, ver)
    return folder


class TempDir(unittest.TestCase):
    def setUp(self):
        self.dir = tempfile.TemporaryDirectory()
        self.addCleanup(self.dir.cleanup)
        self.root = Path(self.dir.name)


class Decision(TempDir):
    """Match, mismatch, switch, the person's own choice."""

    def test_a_table_for_this_card_and_this_hipblaslt_is_used(self):
        pkg = fake_package(self.root)
        d = ht.resolve(pkg, ["gfx1201"], environ=ON)
        self.assertEqual(d.path, pkg / "tuning" / "gfx1201-hipblaslt-100500.txt")
        self.assertIn("gfx1201-hipblaslt-100500.txt", d.message)
        self.assertIn(ht.SWITCH, d.message)               # the line tells how to turn it off
        self.assertEqual(d.level, "info")

    def test_a_table_for_another_hipblaslt_version_is_not_used_and_the_log_says_why(self):
        pkg = fake_package(self.root, version=100200, tables=(("gfx1201", 100500),))
        d = ht.resolve(pkg, ["gfx1201"], environ=ON)
        self.assertIsNone(d.path)
        self.assertEqual(d.level, "warn")
        self.assertIn("100200", d.message)
        self.assertIn("100500", d.message)
        self.assertIn("plain hipBLAS", d.message)

    def test_a_card_without_a_table_in_the_package_gets_plain_hipblas_and_one_line(self):
        pkg = fake_package(self.root)
        d = ht.resolve(pkg, ["gfx1200"], environ=ON)
        self.assertIsNone(d.path)
        self.assertIn("none for gfx1200", d.message)

    def test_the_card_that_has_a_table_is_found_among_several(self):
        pkg = fake_package(self.root, tables=(("gfx1100", 100500), ("gfx1151", 100500)))
        self.assertEqual(ht.resolve(pkg, ["gfx1101", "gfx1151"], environ=ON).path.name, "gfx1151-hipblaslt-100500.txt")

    def test_a_package_that_does_not_say_its_hipblaslt_is_not_guessed_at(self):
        pkg = fake_package(self.root, version=None)
        d = ht.resolve(pkg, ["gfx1201"], environ=ON)
        self.assertIsNone(d.path)
        self.assertEqual(d.level, "warn")
        self.assertIn("hipblaslt_version", d.message)

    def test_an_unreadable_card_is_a_note_not_a_guess(self):
        d = ht.resolve(fake_package(self.root), [], environ=ON)
        self.assertIsNone(d.path)
        self.assertIn("could not be read", d.message)

    def test_a_table_whose_header_disagrees_with_its_name_is_not_used(self):
        pkg = fake_package(self.root, tables=())
        fake_table(pkg / "tuning", "gfx1201", 100500, header=f"{ht.HEADER} gfx1201 100401")
        d = ht.resolve(pkg, ["gfx1201"], environ=ON)
        self.assertIsNone(d.path)
        self.assertIn("header", d.message)

    def test_the_switch_turns_it_off_in_the_environment_and_in_the_run_config(self):
        pkg = fake_package(self.root)
        for word in ("off", "OFF", "0", "no", "false", "none"):
            d = ht.resolve(pkg, ["gfx1201"], environ={ht.SWITCH: word})
            self.assertIsNone(d.path, word)
            self.assertIn("off", d.message)
        self.assertIsNone(ht.resolve(pkg, ["gfx1201"], environ=AUTO, cfg={"hipblaslt_table": False}).path)
        self.assertIsNotNone(ht.resolve(pkg, ["gfx1201"], environ=AUTO, cfg={"hipblaslt_table": True}).path)
        self.assertIsNone(ht.resolve(pkg, ["gfx1201"], environ={ht.SWITCH: "off"}, cfg={"hipblaslt_table": True}).path)   # the environment wins
        for word in ("on", "ON", "1", "yes", "true"):
            self.assertIsNotNone(ht.resolve(pkg, ["gfx1201"], environ={ht.SWITCH: word}).path, word)

    def test_auto_follows_the_one_constant_and_says_what_is_available(self):
        pkg = fake_package(self.root)
        with mock.patch.object(ht, "AUTO_USES_TABLE", False):
            d = ht.resolve(pkg, ["gfx1201"], environ=AUTO)
            self.assertIsNone(d.path)
            self.assertIn("gfx1201-hipblaslt-100500.txt", d.message)
            self.assertIn(f"{ht.SWITCH}=on", d.message)
            self.assertEqual(ht.mode(AUTO), "auto")
        with mock.patch.object(ht, "AUTO_USES_TABLE", True):
            d = ht.resolve(pkg, ["gfx1201"], environ=AUTO)
            self.assertEqual(d.path, pkg / "tuning" / "gfx1201-hipblaslt-100500.txt")
            self.assertIsNone(ht.resolve(pkg, ["gfx1201"], environ={ht.SWITCH: "off"}).path)

    def test_the_default_is_the_owners_decision(self):
        """A table changes the bits of the prompt's dense GEMMs (notes-021-hip.md); the owner chose: on by default for Strix Halo only."""
        self.assertFalse(ht.AUTO_USES_TABLE)
        self.assertEqual(ht.AUTO_ARCHS, ("gfx1151",))

    def test_auto_uses_the_table_on_strix_halo_only(self):
        for arch, used in (("gfx1151", True), ("gfx1201", False), ("gfx1100", False)):
            root = self.root / arch
            root.mkdir()
            pkg = fake_package(root, tables=((arch, 100500),))
            d = ht.resolve(pkg, [arch], environ=AUTO)
            self.assertEqual(d.path is not None, used, (arch, d.message))
            self.assertIsNone(ht.resolve(pkg, [arch], environ={ht.SWITCH: "off"}).path)

    def test_a_table_the_person_set_is_never_replaced(self):
        pkg = fake_package(self.root)
        mine = str(self.root / "mine.txt")
        for environ, cfg in (({ht.ENGINE_VAR: mine}, {}), ({}, {"env": {ht.ENGINE_VAR: mine}})):
            d = ht.resolve(pkg, ["gfx1201"], environ=environ, cfg=cfg)
            self.assertIsNone(d.path)
            self.assertIn(mine, d.message)
            out = ht.apply({"backend": "hip", **cfg}, pkg, ["gfx1201"], environ=environ, say=lambda line: None)
            self.assertEqual((out.get("env") or {}).get(ht.ENGINE_VAR, mine), mine)


class Apply(TempDir):
    def test_apply_puts_the_table_in_a_copy_of_the_config_and_says_so_once(self):
        pkg = fake_package(self.root)
        cfg = {"backend": "hip", "env": {"STRATA_RESIDENT_PIN": "0"}}
        lines = []
        out = ht.apply(cfg, pkg, ["gfx1201"], environ=ON, say=lines.append)
        self.assertEqual(out["env"][ht.ENGINE_VAR], str(pkg / "tuning" / "gfx1201-hipblaslt-100500.txt"))
        self.assertEqual(out["env"]["STRATA_RESIDENT_PIN"], "0")
        self.assertNotIn(ht.ENGINE_VAR, cfg["env"])        # the caller's config is untouched
        self.assertEqual(len(lines), 1)
        self.assertTrue(lines[0].startswith("[strata] hipBLASLt tuning table"))

    def test_apply_with_a_mismatch_leaves_the_config_alone_and_warns(self):
        pkg = fake_package(self.root, version=100200)
        cfg = {"backend": "hip"}
        lines = []
        self.assertIs(ht.apply(cfg, pkg, ["gfx1201"], environ=ON, say=lines.append), cfg)
        self.assertEqual(len(lines), 1)
        self.assertIn("note", lines[0])

    def test_other_backends_and_packages_without_tables_are_silent(self):
        lines = []
        pkg = fake_package(self.root)
        cfg = {"backend": "cuda"}
        self.assertIs(ht.apply(cfg, pkg, ["gfx1201"], environ=ON, say=lines.append), cfg)
        bare = self.root / "cuda-pkg"
        bare.mkdir()
        (bare / "BUILD.json").write_text(json.dumps({"version": "0.2.1"}), encoding="utf-8")
        out = ht.apply({"backend": "hip"}, bare, ["gfx1201"], environ=ON, say=lines.append)
        self.assertNotIn("env", out)
        self.assertEqual(lines, [])

    def test_the_server_start_applies_it_for_a_component_engine(self):
        from serve import server
        pkg = fake_package(self.root)
        (pkg / "strata").write_text("x", encoding="utf-8")
        cfg = {"exe": "component:strata-engine", "backend": "hip"}
        out = io.StringIO()
        with mock.patch.object(server.engine_component, "expand", return_value=str(pkg / "strata")), \
                mock.patch.object(ht, "present_archs", return_value=["gfx1201"]), \
                mock.patch.dict(os.environ, {}, clear=False), contextlib.redirect_stdout(out):
            os.environ.pop(ht.SWITCH, None)
            os.environ.pop(ht.ENGINE_VAR, None)
            self.assertNotIn(ht.ENGINE_VAR, server.child_env(server.with_component_engine(cfg)))     # "auto" is off by default
            os.environ[ht.SWITCH] = "on"
            started = server.with_component_engine(cfg)
            env = server.child_env(started)
            self.assertEqual(env[ht.ENGINE_VAR], str(pkg / "tuning" / "gfx1201-hipblaslt-100500.txt"))
            os.environ[ht.SWITCH] = "off"
            self.assertNotIn(ht.ENGINE_VAR, server.child_env(server.with_component_engine(cfg)))
        self.assertIn("hipBLASLt tuning table", out.getvalue())

    def test_present_archs_picks_the_configured_card_on_linux(self):
        with mock.patch("strata_control.engine_component.hip_archs_present", return_value=["gfx1100", "gfx1201"]):
            if os.name != "nt":
                self.assertEqual(ht.present_archs({"gpu": 1}), ["gfx1201"])
                self.assertEqual(ht.present_archs({"gpu": [1, 0]}), ["gfx1201", "gfx1100"])
            self.assertEqual(ht.present_archs({}), ["gfx1100", "gfx1201"])


class PackageContents(TempDir):
    """What each package of the release matrix carries, from the real tables of tools/hip."""

    def test_every_release_package_carries_the_tables_its_cards_have(self):
        for (platform, variant), (archs, version, wanted) in PACKAGES.items():
            stage = self.root / f"{platform}-{variant}"
            stage.mkdir()
            copied = ht.stage_tables(stage, archs, version, TABLES)
            self.assertEqual({n.split("-")[0] for n in copied}, wanted, (platform, variant))
            on_disk = {p.name for p in (stage / "tuning").glob("*.txt")} if (stage / "tuning").is_dir() else set()
            self.assertEqual(on_disk, set(copied), (platform, variant))
            for arch in wanted:                           # the file the engine start will pick is there and its own header agrees
                self.assertTrue(ht.header_ok(stage / "tuning" / ht.table_name(arch, version), arch, version), (platform, arch))

    def test_the_missing_report_names_the_architectures_without_a_table(self):
        left = ht.missing_report(("gfx1100", "gfx1101", "gfx1102"), 100200, TABLES)
        self.assertEqual(sorted(left), ["gfx1101", "gfx1102"])
        self.assertEqual(ht.missing_report(("gfx1201",), 100200, TABLES), {"gfx1201": [100202, 100500]})

    def test_every_table_in_the_repo_has_a_header_that_matches_its_name(self):
        tables = ht.tables_in(TABLES)
        self.assertGreater(len(tables), 8)
        for (arch, version), path in tables.items():
            self.assertTrue(ht.header_ok(path, arch, version), path.name)

    def test_version_from_header_reads_the_rocm_tree(self):
        inc = self.root / "include" / "hipblaslt"
        inc.mkdir(parents=True)
        (inc / "hipblaslt-version.h").write_text("#define HIPBLASLT_VERSION_MAJOR 1\n#define HIPBLASLT_VERSION_MINOR 5\n"
                                                 "#define HIPBLASLT_VERSION_PATCH 0\n", encoding="utf-8")
        self.assertEqual(ht.version_from_header(self.root), 100500)
        self.assertIsNone(ht.version_from_header(self.root / "nowhere"))

    def test_stage_tuning_writes_the_version_and_the_tables(self):
        stage = self.root / "stage"
        stage.mkdir()
        (stage / "BUILD.json").write_text(json.dumps({"version": "0.2.1", "archs": ["gfx1151"]}), encoding="utf-8")
        with contextlib.redirect_stdout(io.StringIO()):
            self.assertEqual(stage_tuning.main(["--stage", str(stage), "--archs", "gfx1151", "--version", "100401"]), 0)
        meta = json.loads((stage / "BUILD.json").read_text(encoding="utf-8"))
        self.assertEqual(meta["hipblaslt_version"], 100401)
        self.assertEqual(meta["archs"], ["gfx1151"])      # what was there stays
        self.assertTrue((stage / "tuning" / "gfx1151-hipblaslt-100401.txt").is_file())

    def test_stage_tuning_can_demand_a_table(self):
        stage = self.root / "stage"
        stage.mkdir()
        with contextlib.redirect_stdout(io.StringIO()), self.assertRaises(SystemExit) as caught:
            stage_tuning.main(["--stage", str(stage), "--archs", "gfx1201", "--version", "100200", "--expect", "gfx1201"])
        self.assertIn("gfx1201", str(caught.exception))

    def test_stage_tuning_refuses_a_rocm_whose_version_it_cannot_read(self):
        stage = self.root / "stage"
        stage.mkdir()
        with self.assertRaises(SystemExit):
            stage_tuning.main(["--stage", str(stage), "--archs", "gfx1201", "--rocm", str(self.root / "no-rocm")])


class PackagedAndHashed(TempDir):
    """packaging/package_engine.py: the tables are files of the package (hashed, so signed with it) and a bad AMD stage is refused."""

    def stage(self, **kw):
        src = self.root / "src"
        src.mkdir()
        (src / "strata").write_bytes(b"engine" * 100)
        (src / "libamdhip64.so.7").write_bytes(b"hip" * 100)
        (src / "BUILD.json").write_text(json.dumps({"version": "0.2.1", **kw}), encoding="utf-8")
        return src

    def build(self, src, archs=("gfx1201",), tree=False):
        out = self.root / "out"
        out.mkdir(exist_ok=True)
        with mock.patch.object(package_engine, "_bundle_missing_libraries", return_value=[]):
            return package_engine.build(src, "hip", "0.2.1", "linux-x86_64", out, entry="strata", archs=archs, build_id="t", tree=tree,
                                        variant="rx9070")

    def test_the_tables_are_listed_and_hashed_in_the_manifest_even_without_tree(self):
        src = self.stage(hipblaslt_version=100500)
        fake_table(src / "tuning", "gfx1201", 100500)
        folder = self.build(src)
        listed = {f["path"]: f for f in json.loads((folder / "engine-component.json").read_text(encoding="utf-8"))["files"]}
        self.assertIn("tuning/gfx1201-hipblaslt-100500.txt", listed)
        self.assertEqual(len(listed["tuning/gfx1201-hipblaslt-100500.txt"]["sha256"]), 64)
        (folder / "tuning" / "gfx1201-hipblaslt-100500.txt").write_text("changed", encoding="utf-8")   # a swapped table fails the start's hash check
        from strata_control import engine_component as ec
        with self.assertRaises(ec.ComponentProblem):
            ec.verify(ec.read_manifest(folder), full=True)

    def test_an_amd_stage_without_a_hipblaslt_version_is_refused(self):
        src = self.stage()
        with self.assertRaises(SystemExit) as caught:
            self.build(src)
        self.assertIn("hipblaslt_version", str(caught.exception))

    def test_a_table_for_another_version_or_card_than_the_package_is_refused(self):
        src = self.stage(hipblaslt_version=100500)
        fake_table(src / "tuning", "gfx1201", 100202)
        with self.assertRaises(SystemExit) as caught:
            self.build(src)
        self.assertIn("100202", str(caught.exception))
        other = self.root / "other"
        other.mkdir()
        src2 = other / "src"
        src2.mkdir()
        (src2 / "strata").write_bytes(b"e")
        (src2 / "BUILD.json").write_text(json.dumps({"hipblaslt_version": 100500}), encoding="utf-8")
        fake_table(src2 / "tuning", "gfx1100", 100500)
        with mock.patch.object(package_engine, "_bundle_missing_libraries", return_value=[]), self.assertRaises(SystemExit) as caught:
            package_engine.build(src2, "hip", "0.2.1", "linux-x86_64", other / "out", entry="strata", archs=("gfx1201",), build_id="t")
        self.assertIn("gfx1100", str(caught.exception))

    def test_a_cuda_package_needs_no_hipblaslt_version(self):
        src = self.stage()
        out = self.root / "out"
        out.mkdir()
        with mock.patch.object(package_engine, "_bundle_missing_libraries", return_value=[]):
            package_engine.build(src, "cuda", "0.2.1", "linux-x86_64", out, entry="strata", archs=("sm_86",), build_id="t")


class SetupFindsThePackageTable(TempDir):
    """setup.py outside the app (a git checkout, or the old Windows zip that START-HERE unpacks): the engine folder's own tuning/ comes first."""

    def load_setup(self):
        import importlib.util
        spec = importlib.util.spec_from_file_location("setup_hipblaslt_copy", ROOT / "setup.py")
        module = importlib.util.module_from_spec(spec)
        spec.loader.exec_module(module)
        return module

    def test_the_engine_folders_table_wins_over_tools_hip_and_the_switch_turns_it_off(self):
        setup = self.load_setup()
        pkg = self.root / "engine"
        fake_table(pkg / "tuning", "gfx1201", 100500)
        seen = []
        with mock.patch.object(setup, "ok", seen.append), mock.patch.object(setup, "say", seen.append), \
                mock.patch.object(setup, "warn", seen.append), mock.patch.dict(os.environ, {}, clear=False):
            os.environ.pop(ht.SWITCH, None)
            self.assertEqual(setup.hipblaslt_table("gfx1201", [], 100500, [pkg / "tuning"]), pkg / "tuning" / "gfx1201-hipblaslt-100500.txt")
            self.assertEqual(setup.hipblaslt_table("gfx1201", [], 100500), TABLES / "gfx1201-hipblaslt-100500.txt")
            self.assertIsNone(setup.hipblaslt_table("gfx1201", [], 100200, [pkg / "tuning"]))      # no table for 1.2.0: warned, plain
            os.environ[ht.SWITCH] = "off"
            self.assertIsNone(setup.hipblaslt_table("gfx1201", [], 100500, [pkg / "tuning"]))
        self.assertTrue(any("no hipBLASLt tuning table" in str(line) for line in seen))


if __name__ == "__main__":
    unittest.main()