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++

GPU roles: one shared rule for Main / Helper / Off (recommend, set, order, mirror, warnings) with shared test vectors

Niko12212219cc99bf29
diff --git a/strata_control/gpu_roles.py b/strata_control/gpu_roles.py
new file mode 100644
index 000000000..6b9aaea34
--- /dev/null
+++ b/strata_control/gpu_roles.py
@@ -0,0 +1,418 @@
+"""Main / Helper / Off for every graphics card: ONE place for the app, `strata launch`, setup and the server.
+
+A card has one of three roles:
+* Main - the card that runs the LAST stage of the layer split: the output head, the draft layer and the check of its guesses. Exactly one.
+* Helper - holds a share of the model, so more of it fits on graphics cards instead of being read from the drive.
+* Off - Strata does not touch it.
+
+The engine takes the cards in stage order (`"gpu": [helper, ..., main]` with `"gpu_order": "as_given"`), so the Main card is the LAST one. This
+module turns roles into that list (and back), recommends roles, and words the few warnings a person could not work out alone.
+The app has the same rules in apps/host/src/lib/gpu-roles.ts; both run tests/data/gpu_roles_vectors.json.
+
+Pure functions, no I/O.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from strata_control import gpu_fit
+
+ROLES = ("main", "helper", "off")
+OFF_AT_OR_BELOW_GB = 8.0 # owner rule: a card with 8 GB or less starts Off (it is not a helper unless the person turns it on)
+SAME_SPEED = 1.05 # serve/server.py ordered_gpus: cards within 5% of each other are the same card
+MEMORY_GUARD_SPEED = 0.5 # a card with more memory takes Main from a faster one only when it is at least half as fast (#1576)
+
+CPU_ONLY_LINE = "Performance is degraded on CPU only."
+NO_CARD_LINE = "This engine needs a graphics card to start. Turn one on."
+
+
+def _idx(c: dict) -> int:
+ return int(c.get("index", 0))
+
+
+def _mem(c: dict) -> float:
+ return float(c.get("vram_gb") or 0)
+
+
+def _speed(c: dict) -> float:
+ v = c.get("speed")
+ return float(v) if isinstance(v, (int, float)) and not isinstance(v, bool) and v > 0 else 0.0
+
+
+def _shares(c: dict) -> bool:
+ return gpu_fit._shares_memory(c)
+
+
+def _can_run(c: dict) -> bool:
+ return c.get("usable") is not False
+
+
+def short_name(c: dict) -> str:
+ n = str(c.get("name") or f"GPU {_idx(c) + 1}")
+ for junk in ("NVIDIA GeForce ", "NVIDIA ", "GeForce ", "AMD Radeon ", "AMD ", "Intel(R) ", "Intel "):
+ if n.startswith(junk):
+ n = n[len(junk):]
+ break
+ return n.strip()
+
+
+def gpu_label(c: dict) -> str:
+ """The number the screens show: GPU 1 is card 0 (Monitor, the model picker, the loaded list)."""
+ return f"GPU {_idx(c) + 1}"
+
+
+def rows(cards: list[dict], vendor: str | None = None) -> list[dict]:
+ """The cards shown as rows: every card the engine's make can name, in card order. The other make is `gpu_fit.for_vendor(...)[1]` (a muted line)."""
+ vendor = vendor or gpu_fit.pick_vendor(cards)
+ mine = gpu_fit.for_vendor(cards, vendor)[0]
+ return sorted(mine, key=_idx)
+
+
+def _eligible(cs: list[dict]) -> list[dict]:
+ """The cards that can be Main: run Strata, have memory of their own and at least MIN_CARD_GB of it; an integrated chip only when it is the
+ only device (a Strix Halo PC, a mini PC)."""
+ real = [c for c in cs if _can_run(c) and not _shares(c) and _mem(c) >= gpu_fit.MIN_CARD_GB]
+ if real:
+ return real
+ return [c for c in cs if _can_run(c)]
+
+
+def pick_main(cs: list[dict]) -> tuple[dict | None, str]:
+ """(the Main card, why) why: only | faster | same | memory. The faster card, cards within 5% being the same card (the one with more memory,
+ then the lower number); a card with clearly more memory wins when it is at least half as fast (#1576)."""
+ pool = _eligible(cs)
+ if not pool:
+ return None, "none"
+ if len(pool) == 1:
+ return pool[0], "only"
+ top = max(_speed(c) for c in pool)
+ group = [c for c in pool if _speed(c) * SAME_SPEED >= top] if top > 0 else list(pool)
+ main = sorted(group, key=lambda c: (-round(_mem(c)), _idx(c)))[0]
+ why = "faster" if len(group) == 1 else "same"
+ if top <= 0 and len({round(_mem(c)) for c in pool}) > 1:
+ why = "memory" # speeds unknown: the card with the most memory
+ bigger = [c for c in pool if round(_mem(c)) > round(_mem(main)) and (top <= 0 or _speed(c) >= MEMORY_GUARD_SPEED * top)]
+ if bigger:
+ main = sorted(bigger, key=lambda c: (-round(_mem(c)), _idx(c)))[0]
+ why = "memory"
+ return main, why
+
+
+def recommend(cards: list[dict], vendor: str | None = None) -> dict[str, Any]:
+ """The recommended roles: {"roles": {index: role}, "main": index|None, "why": code, "reasons": {index: code}}.
+ The best card is Main, every other card starts as Helper, EXCEPT a card with 8 GB or less, an integrated chip beside a card with memory of
+ its own, and a card the engine cannot run: those start Off."""
+ cs = rows(cards, vendor)
+ main, why = pick_main(cs)
+ roles: dict[int, str] = {}
+ reasons: dict[int, str] = {}
+ for c in cs:
+ i = _idx(c)
+ if main is not None and c is main:
+ roles[i], reasons[i] = "main", why
+ elif not _can_run(c):
+ roles[i], reasons[i] = "off", "cannot_run"
+ elif _shares(c) and main is not None:
+ roles[i], reasons[i] = "off", "igpu"
+ elif round(_mem(c)) <= OFF_AT_OR_BELOW_GB:
+ roles[i], reasons[i] = "off", "small"
+ else:
+ roles[i], reasons[i] = "helper", "helper"
+ return {"roles": roles, "main": _idx(main) if main is not None else None, "why": why, "reasons": reasons}
+
+
+def _on(roles: dict[int, str]) -> list[int]:
+ return [i for i, r in roles.items() if r != "off"]
+
+
+def normalize(roles: dict[int, str], cards: list[dict]) -> dict[int, str]:
+ """Exactly one Main among the cards that are on: none -> the fastest card that is on; more than one -> the first keeps it. A lone card that
+ is on is Main."""
+ cs = {_idx(c): c for c in cards}
+ out = {i: (r if r in ROLES else "off") for i, r in roles.items() if i in cs}
+ on = _on(out)
+ mains = [i for i in on if out[i] == "main"]
+ if on and not mains:
+ best = sorted(on, key=lambda i: (-_speed(cs[i]), -round(_mem(cs[i])), i))[0]
+ out[best] = "main"
+ for extra in mains[1:]:
+ out[extra] = "helper"
+ if len(on) == 1:
+ out[on[0]] = "main"
+ return out
+
+
+def set_role(roles: dict[int, str], cards: list[dict], idx: int, role: str) -> tuple[dict[int, str], str | None]:
+ """One click: the new roles and a code for the quiet line the app/Terminal may show (None: nothing to say).
+ Codes: old_main_helper:<i> (the old Main became a Helper), promoted:<i> (this card became Main because the Main left), only_main (refused)."""
+ cs = {_idx(c): c for c in cards}
+ out = dict(roles)
+ note: str | None = None
+ if idx not in cs or role not in ROLES:
+ return out, None
+ if role == "main":
+ old = next((i for i in out if i != idx and out[i] == "main"), None)
+ out[idx] = "main"
+ if old is not None:
+ out[old] = "helper"
+ note = f"old_main_helper:{old}"
+ elif role == "helper":
+ if out.get(idx) == "main":
+ others = sorted([i for i in out if i != idx and out[i] == "helper"], key=lambda i: (-_speed(cs[i]), i))
+ if not others:
+ return out, "only_main"
+ out[idx] = "helper"
+ out[others[0]] = "main"
+ note = f"promoted:{others[0]}"
+ else:
+ out[idx] = "helper"
+ else:
+ was_main = out.get(idx) == "main"
+ out[idx] = "off"
+ if was_main:
+ nxt = sorted([i for i in out if out[i] == "helper"], key=lambda i: (-_speed(cs[i]), i))
+ if nxt:
+ out[nxt[0]] = "main"
+ note = f"promoted:{nxt[0]}"
+ on = _on(out)
+ if len(on) == 1:
+ out[on[0]] = "main"
+ elif on and not any(out[i] == "main" for i in on):
+ out[on[0]] = "main"
+ return out, note
+
+
+def order(roles: dict[int, str], cards: list[dict]) -> list[int]:
+ """The engine's card list: Helpers (slowest first, ties by number), then the Main card LAST; Off cards left out."""
+ cs = {_idx(c): c for c in cards}
+ roles = normalize(roles, cards)
+ helpers = sorted([i for i, r in roles.items() if r == "helper"], key=lambda i: (_speed(cs[i]), i))
+ return helpers + [i for i, r in roles.items() if r == "main"]
+
+
+def mirror(roles: dict[int, str], cards: list[dict]) -> dict[str, Any]:
+ """What a writer stores: "gpu_roles" plus the legacy mirror older engines and the Monitor read. Nothing on: "gpu": [] and "gpu_none": true."""
+ roles = normalize(roles, cards)
+ lst = order(roles, cards)
+ out: dict[str, Any] = {"gpu_roles": {str(i): roles[i] for i in sorted(roles)}}
+ if lst:
+ out["gpu"] = lst[0] if len(lst) == 1 else lst
+ out["gpu_order"] = "as_given"
+ else:
+ out["gpu"] = []
+ out["gpu_none"] = True
+ out["gpu_cards"] = {str(_idx(c)): "|".join(x for x in (short_name(c), str(c.get("bus") or "")) if x) for c in cards if _idx(c) in roles}
+ return out
+
+
+def parse_roles(text: str, cards: list[dict] | None = None) -> dict[int, str]:
+ """`1=main,0=helper,2=off` (also `1:main`) -> {1: "main", 0: "helper", 2: "off"}. ValueError with a plain message otherwise."""
+ out: dict[int, str] = {}
+ for part in str(text or "").replace(";", ",").split(","):
+ part = part.strip()
+ if not part:
+ continue
+ sep = "=" if "=" in part else ":" if ":" in part else None
+ if sep is None:
+ raise ValueError(f"{part!r}: write each card as number=role, e.g. 1=main,0=helper,2=off")
+ k, v = (x.strip().lower() for x in part.split(sep, 1))
+ if not k.isdigit() or v not in ROLES:
+ raise ValueError(f"{part!r}: a card number and one of main, helper, off, e.g. 1=main")
+ if int(k) in out:
+ raise ValueError(f"card {k} is named twice")
+ out[int(k)] = v
+ if not out:
+ raise ValueError("no cards named; write e.g. 1=main,0=helper")
+ mains = [i for i, r in out.items() if r == "main"]
+ if len(mains) > 1:
+ raise ValueError("only one card can be Main")
+ if cards is not None:
+ known = {_idx(c) for c in cards}
+ missing = [i for i in out if i not in known]
+ if missing:
+ raise ValueError("no card " + ", ".join(str(i) for i in missing) + " on this computer (cards: " + ", ".join(str(i) for i in sorted(known)) + ")")
+ return out
+
+
+def roles_from_text(text: str, cards: list[dict]) -> dict[int, str]:
+ """A command line's roles: the cards named get their role; every card NOT named is Off (an explicit command means only what was named);
+ no Main named -> the fastest named card that is on becomes Main."""
+ named = parse_roles(text, cards)
+ full = {_idx(c): named.get(_idx(c), "off") for c in cards}
+ return normalize(full, cards)
+
+
+def from_legacy(gpu: Any, cards: list[dict], gpu_order: str | None = None, speed_order: bool = True) -> dict[int, str]:
+ """Roles of an old "gpu" setting, for display: the LAST card of the engine's order is Main, earlier ones are Helpers, unlisted cards are Off.
+ `gpu` None / "" / []: the recommendation (nothing was chosen)."""
+ items: list[int] = []
+ if isinstance(gpu, (list, tuple)):
+ items = [int(x) for x in gpu]
+ elif gpu is not None and str(gpu).strip() != "":
+ items = [int(x) for x in str(gpu).split(",") if x.strip() != ""]
+ cs = {_idx(c): c for c in cards}
+ items = [i for i in items if i in cs]
+ if not items:
+ return dict(recommend(cards)["roles"])
+ if len(items) > 1 and gpu_order != "as_given" and speed_order:
+ if max(_speed(cs[i]) for i in items) >= SAME_SPEED * max(1e-9, min(_speed(cs[i]) for i in items)) and all(_speed(cs[i]) for i in items):
+ items = sorted(items, key=lambda i: _speed(cs[i])) # the engine puts the faster card last (#1352)
+ roles = {i: "off" for i in cs}
+ for i in items[:-1]:
+ roles[i] = "helper"
+ roles[items[-1]] = "main"
+ return roles
+
+
+def is_recommended(roles: dict[int, str], cards: list[dict], vendor: str | None = None) -> bool:
+ rec = recommend(cards, vendor)["roles"]
+ return {i: r for i, r in roles.items() if i in rec} == rec
+
+
+# ---- warnings: only what a person could not know -------------------------------------------------------------------------------------------
+
+def warnings(roles: dict[int, str], cards: list[dict], *, spill_gb: float = 0.0, engine_runs_cpu_only: bool = False) -> list[dict]:
+ """[{"code", "card"|None, "text", "fix": {"card": i, "role": r}|None}] - one short line each, never blocking.
+ * igpu_main built-in graphics as Main (fix: the real card becomes Main)
+ * cannot_run a card the engine cannot run is on (fix: turn it off)
+ * low_memory too little memory for the chosen setup (part of the model would be read from the drive)
+ * cpu_only every card is Off"""
+ cs = {_idx(c): c for c in cards}
+ out: list[dict] = []
+ for i in sorted(roles):
+ c, role = cs.get(i), roles[i]
+ if c is None or role == "off":
+ continue
+ if not _can_run(c):
+ out.append({"code": "cannot_run", "card": i, "text": f"{short_name(c)} cannot run Strata.", "fix": {"card": i, "role": "off"}})
+ elif role == "main" and _shares(c) and any(not _shares(x) and _can_run(x) for x in cs.values()):
+ real = sorted([x for x in cs.values() if not _shares(x) and _can_run(x)], key=lambda x: (-_speed(x), -_mem(x), _idx(x)))[0]
+ out.append({"code": "igpu_main", "card": i, "text": f"{short_name(c)} is built-in graphics; it is slow as Main.",
+ "fix": {"card": _idx(real), "role": "main"}})
+ if not _on(roles):
+ out.append({"code": "cpu_only", "card": None, "text": CPU_ONLY_LINE if engine_runs_cpu_only else NO_CARD_LINE, "fix": None})
+ elif spill_gb >= 1.0:
+ out.append({"code": "low_memory", "card": None, "text": f"Not enough memory for this setup: about {spill_gb:.0f} GB is read from the drive.", "fix": None})
+ return out
+
+
+def spill_for(roles: dict[int, str], cards: list[dict], memory_gb: float | None, ram_gb: float | None) -> float:
+ """About how many GB of the model would be read from the drive with the cards that are on (0 when unknown): gpu_fit's arithmetic, every
+ extra card costing its own dense layers."""
+ if not memory_gb or not ram_gb:
+ return 0.0
+ cs = {_idx(c): c for c in cards}
+ on = [cs[i] for i in _on(roles) if i in cs and not _shares(cs[i])]
+ vram = sum(_mem(c) for c in on) - gpu_fit.SPLIT_CARD_OVERHEAD_GB * max(0, len(on) - 1)
+ return float(gpu_fit.fit(float(memory_gb), float(ram_gb), max(0.0, vram))["spill_gb"])
+
+
+def note_text(code: str | None, cards: list[dict]) -> str:
+ """The quiet line for a `set_role` code."""
+ if not code:
+ return ""
+ cs = {_idx(c): c for c in cards}
+ kind, _, arg = code.partition(":")
+ c = cs.get(int(arg)) if arg.isdigit() else None
+ name = short_name(c) if c else "That card"
+ if kind == "old_main_helper":
+ return f"{name} is now a Helper."
+ if kind == "promoted":
+ return f"{name} is now Main."
+ if kind == "only_main":
+ return "The only card that is on has to be Main."
+ return ""
+
+
+# ---- the sentence above the cards ----------------------------------------------------------------------------------------------------------
+
+def sentence(cards: list[dict], vendor: str | None = None) -> str:
+ """One plain line for the recommendation: who is Main and why, who helps, who starts Off."""
+ cs = rows(cards, vendor)
+ rec = recommend(cards, vendor)
+ byi = {_idx(c): c for c in cs}
+ if rec["main"] is None:
+ return "No graphics card that Strata can use was found."
+ m = byi[rec["main"]]
+ if len(cs) == 1:
+ return f"Strata will use your {short_name(m)}."
+ helpers = [byi[i] for i, r in rec["roles"].items() if r == "helper"]
+ why = {"same": "the cards are alike, so the lower number is Main", "memory": "it has more memory", "faster": "it is faster", "only": "it is the only card"}[rec["why"]]
+ s = f"{short_name(m)} is Main: {why}."
+ if helpers:
+ s += " " + " and ".join(short_name(h) for h in helpers) + (" help." if len(helpers) > 1 else " helps.")
+ for i, r in rec["roles"].items():
+ if r == "off":
+ code = rec["reasons"][i]
+ c = byi[i]
+ s += f" {short_name(c)} starts Off: " + ("Strata cannot run it." if code == "cannot_run" else "built-in graphics." if code == "igpu" else f"{OFF_AT_OR_BELOW_GB:.0f} GB or less.")
+ return s
+
+
+# ---- reading saved settings (server, launch, app) ---------------------------------------------------------------------------------------
+
+def _int_list(g: Any) -> list[int]:
+ if g is None or g == "":
+ return []
+ items = g if isinstance(g, (list, tuple)) else str(g).split(",")
+ return [int(str(x).strip()) for x in items if str(x).strip() != ""]
+
+
+def parse_saved(value: Any) -> dict[int, str] | None:
+ """A saved "gpu_roles" object -> {index: role}; None when it is not one (the setting is then ignored)."""
+ if not isinstance(value, dict) or not value:
+ return None
+ out: dict[int, str] = {}
+ for k, v in value.items():
+ try:
+ i = int(str(k).strip())
+ except ValueError:
+ return None
+ if str(v).lower() not in ROLES:
+ return None
+ out[i] = str(v).lower()
+ if sum(1 for r in out.values() if r == "main") > 1:
+ return None
+ return out
+
+
+def saved_roles(cfg: dict) -> tuple[dict[int, str] | None, str | None]:
+ """(the roles a run settings dict carries, a problem line or None). Roles win when the legacy "gpu" is the mirror of them, or when "gpu" is
+ missing; a "gpu" that was edited by hand (it names other cards, or another Main) wins and the roles are ignored (#3256: a file that names
+ its GPUs keeps them)."""
+ roles = parse_saved(cfg.get("gpu_roles"))
+ if roles is None:
+ return None, ("run settings: gpu_roles is not {card: main|helper|off} with one main; ignored" if cfg.get("gpu_roles") is not None else None)
+ try:
+ gl = _int_list(cfg.get("gpu"))
+ except ValueError:
+ return None, "run settings: gpu is not a card number or a list; gpu_roles ignored"
+ on = [i for i, r in roles.items() if r != "off"]
+ main = next((i for i, r in roles.items() if r == "main"), None)
+ if cfg.get("gpu_none") and not on:
+ return roles, None
+ if not gl:
+ return (roles, None) if on else (None, None)
+ if sorted(gl) != sorted(on) or (main is not None and gl[-1] != main):
+ return None, "run settings: gpu was edited by hand, gpu_roles ignored"
+ return roles, None
+
+
+def engine_order(roles: dict[int, str], speeds: dict[int, float] | None = None) -> list[int]:
+ """The card list of saved roles for the server: Helpers slowest first (ties by number), then Main. Used where only numbers and
+ (maybe) measured speeds are known."""
+ sp = speeds or {}
+ helpers = sorted([i for i, r in roles.items() if r == "helper"], key=lambda i: (sp.get(i, 0.0), i))
+ return helpers + sorted(i for i, r in roles.items() if r == "main")
+
+
+def describe(roles: dict[int, str], cards: list[dict]) -> str:
+ """`Main: GPU 2 RTX 4070 Ti. Helper: GPU 1 RTX 3060.` (the line launch and setup print)"""
+ cs = {_idx(c): c for c in cards}
+ parts = []
+ for role, word in (("main", "Main"), ("helper", "Helper"), ("off", "Off")):
+ names = [f"GPU {i + 1} {short_name(cs[i])}" if i in cs else f"GPU {i + 1}" for i in sorted(roles) if roles[i] == role]
+ if names:
+ parts.append(f"{word}: {', '.join(names)}.")
+ return " ".join(parts)
diff --git a/tests/data/gpu_roles_vectors.json b/tests/data/gpu_roles_vectors.json
new file mode 100644
index 000000000..41dd5ed8f
--- /dev/null
+++ b/tests/data/gpu_roles_vectors.json
@@ -0,0 +1,69 @@
+{
+ "_about": "Shared by tests/terminal/test_gpu_roles.py (strata_control/gpu_roles.py) and apps/host/tests/gpu-roles.test.mjs (apps/host/src/lib/gpu-roles.ts). Roles are keyed by card number.",
+ "hw": {
+ "one": [{"index": 0, "name": "NVIDIA GeForce RTX 4070 Ti", "vram_gb": 12, "speed": 100}],
+ "two": [{"index": 0, "name": "NVIDIA GeForce RTX 3060", "vram_gb": 12, "speed": 60}, {"index": 1, "name": "NVIDIA GeForce RTX 4070 Ti", "vram_gb": 12, "speed": 100}],
+ "equal": [{"index": 0, "name": "NVIDIA RTX A4000", "vram_gb": 16, "speed": 50}, {"index": 1, "name": "NVIDIA RTX A4000", "vram_gb": 16, "speed": 50.5}],
+ "three": [{"index": 0, "name": "NVIDIA GeForce RTX 3060", "vram_gb": 12, "speed": 60}, {"index": 1, "name": "NVIDIA GeForce RTX 4070 Ti", "vram_gb": 16, "speed": 100}, {"index": 2, "name": "NVIDIA GeForce RTX 2060", "vram_gb": 6, "speed": 45}],
+ "igpu": [{"index": 0, "name": "Intel(R) UHD Graphics 770", "vram_gb": 0, "integrated": true, "speed": 12}, {"index": 1, "name": "NVIDIA GeForce RTX 4060", "vram_gb": 8, "speed": 70}],
+ "igpu_only": [{"index": 0, "name": "AMD Radeon 780M", "vram_gb": 0, "integrated": true, "speed": 12}],
+ "bigger_slower": [{"index": 0, "name": "NVIDIA GeForce RTX 3090", "vram_gb": 24, "speed": 90}, {"index": 1, "name": "NVIDIA GeForce RTX 4070", "vram_gb": 12, "speed": 100}],
+ "small_second": [{"index": 0, "name": "NVIDIA GeForce RTX 4070 Ti", "vram_gb": 12, "speed": 100}, {"index": 1, "name": "NVIDIA GeForce RTX 3070", "vram_gb": 8, "speed": 70}],
+ "cannot": [{"index": 0, "name": "NVIDIA GeForce GTX 1060", "vram_gb": 6, "usable": false, "problem": "too old"}, {"index": 1, "name": "NVIDIA GeForce RTX 4070 Ti", "vram_gb": 12, "speed": 100}],
+ "nospeed": [{"index": 0, "name": "NVIDIA GeForce RTX 3060", "vram_gb": 12}, {"index": 1, "name": "NVIDIA GeForce RTX 3090", "vram_gb": 24}]
+ },
+ "recommend": [
+ {"hw": "one", "roles": {"0": "main"}, "main": 0, "why": "only"},
+ {"hw": "two", "roles": {"0": "helper", "1": "main"}, "main": 1, "why": "faster"},
+ {"hw": "equal", "roles": {"0": "main", "1": "helper"}, "main": 0, "why": "same"},
+ {"hw": "three", "roles": {"0": "helper", "1": "main", "2": "off"}, "main": 1, "why": "faster"},
+ {"hw": "igpu", "roles": {"0": "off", "1": "main"}, "main": 1, "why": "only"},
+ {"hw": "igpu_only", "roles": {"0": "main"}, "main": 0, "why": "only"},
+ {"hw": "bigger_slower", "roles": {"0": "main", "1": "helper"}, "main": 0, "why": "memory"},
+ {"hw": "small_second", "roles": {"0": "main", "1": "off"}, "main": 0, "why": "faster"},
+ {"hw": "cannot", "roles": {"0": "off", "1": "main"}, "main": 1, "why": "only"},
+ {"hw": "nospeed", "roles": {"0": "helper", "1": "main"}, "main": 1, "why": "memory"}
+ ],
+ "set_role": [
+ {"hw": "two", "roles": {"0": "helper", "1": "main"}, "card": 0, "role": "main", "after": {"0": "main", "1": "helper"}, "note": "old_main_helper:1"},
+ {"hw": "two", "roles": {"0": "helper", "1": "main"}, "card": 1, "role": "off", "after": {"0": "main", "1": "off"}, "note": "promoted:0"},
+ {"hw": "two", "roles": {"0": "helper", "1": "main"}, "card": 1, "role": "helper", "after": {"0": "main", "1": "helper"}, "note": "promoted:0"},
+ {"hw": "two", "roles": {"0": "off", "1": "main"}, "card": 1, "role": "helper", "after": {"0": "off", "1": "main"}, "note": "only_main"},
+ {"hw": "two", "roles": {"0": "helper", "1": "main"}, "card": 0, "role": "off", "after": {"0": "off", "1": "main"}, "note": null},
+ {"hw": "two", "roles": {"0": "off", "1": "main"}, "card": 0, "role": "helper", "after": {"0": "helper", "1": "main"}, "note": null},
+ {"hw": "two", "roles": {"0": "off", "1": "off"}, "card": 0, "role": "helper", "after": {"0": "main", "1": "off"}, "note": null},
+ {"hw": "three", "roles": {"0": "helper", "1": "main", "2": "off"}, "card": 2, "role": "helper", "after": {"0": "helper", "1": "main", "2": "helper"}, "note": null},
+ {"hw": "three", "roles": {"0": "helper", "1": "main", "2": "helper"}, "card": 1, "role": "off", "after": {"0": "main", "1": "off", "2": "helper"}, "note": "promoted:0"}
+ ],
+ "order": [
+ {"hw": "two", "roles": {"0": "helper", "1": "main"}, "gpu": [0, 1]},
+ {"hw": "two", "roles": {"0": "main", "1": "helper"}, "gpu": [1, 0]},
+ {"hw": "two", "roles": {"0": "off", "1": "main"}, "gpu": [1]},
+ {"hw": "three", "roles": {"0": "helper", "1": "main", "2": "helper"}, "gpu": [2, 0, 1]},
+ {"hw": "two", "roles": {"0": "off", "1": "off"}, "gpu": []}
+ ],
+ "warnings": [
+ {"hw": "igpu", "roles": {"0": "main", "1": "helper"}, "codes": ["igpu_main"], "fix": {"card": 1, "role": "main"}},
+ {"hw": "igpu", "roles": {"0": "off", "1": "main"}, "codes": []},
+ {"hw": "cannot", "roles": {"0": "helper", "1": "main"}, "codes": ["cannot_run"]},
+ {"hw": "two", "roles": {"0": "off", "1": "off"}, "codes": ["cpu_only"]},
+ {"hw": "two", "roles": {"0": "helper", "1": "main"}, "spill_gb": 7, "codes": ["low_memory"]},
+ {"hw": "two", "roles": {"0": "main", "1": "helper"}, "codes": []}
+ ],
+ "saved": [
+ {"cfg": {"gpu_roles": {"0": "helper", "1": "main"}, "gpu": [0, 1]}, "roles": {"0": "helper", "1": "main"}},
+ {"cfg": {"gpu_roles": {"0": "helper", "1": "main"}}, "roles": {"0": "helper", "1": "main"}},
+ {"cfg": {"gpu_roles": {"0": "helper", "1": "main"}, "gpu": [1, 0]}, "roles": null, "problem": "edited by hand"},
+ {"cfg": {"gpu_roles": {"0": "off", "1": "main"}, "gpu": 1}, "roles": {"0": "off", "1": "main"}},
+ {"cfg": {"gpu_roles": {"0": "off", "1": "off"}, "gpu": [], "gpu_none": true}, "roles": {"0": "off", "1": "off"}},
+ {"cfg": {"gpu_roles": {"0": "main", "1": "main"}}, "roles": null, "problem": "ignored"},
+ {"cfg": {"gpu": [1, 0]}, "roles": null}
+ ],
+ "legacy": [
+ {"hw": "two", "gpu": null, "roles": {"0": "helper", "1": "main"}},
+ {"hw": "two", "gpu": [1, 0], "gpu_order": "as_given", "roles": {"0": "main", "1": "helper"}},
+ {"hw": "two", "gpu": 1, "roles": {"0": "off", "1": "main"}},
+ {"hw": "two", "gpu": [1, 0], "roles": {"0": "helper", "1": "main"}},
+ {"hw": "equal", "gpu": [1, 0], "roles": {"0": "main", "1": "helper"}}
+ ]
+}
diff --git a/tests/terminal/test_gpu_roles.py b/tests/terminal/test_gpu_roles.py
new file mode 100644
index 000000000..99dc8c31c
--- /dev/null
+++ b/tests/terminal/test_gpu_roles.py
@@ -0,0 +1,127 @@
+"""strata_control/gpu_roles.py: Main / Helper / Off for every graphics card (the rules the app, `strata launch`, setup and the server share)."""
+
+from __future__ import annotations
+
+import json
+import unittest
+from pathlib import Path
+
+from strata_control import gpu_roles as R
+
+ROOT = Path(__file__).resolve().parents[2]
+V = json.loads((ROOT / "tests" / "data" / "gpu_roles_vectors.json").read_text(encoding="utf-8"))
+
+
+def roles(d):
+ return None if d is None else {int(k): v for k, v in d.items()}
+
+
+class Vectors(unittest.TestCase):
+ """tests/data/gpu_roles_vectors.json is also run by apps/host/tests/gpu-roles.test.mjs against gpu-roles.ts."""
+
+ def test_recommend(self):
+ for c in V["recommend"]:
+ with self.subTest(c["hw"]):
+ r = R.recommend(V["hw"][c["hw"]])
+ self.assertEqual(r["roles"], roles(c["roles"]))
+ self.assertEqual((r["main"], r["why"]), (c["main"], c["why"]))
+
+ def test_set_role(self):
+ for c in V["set_role"]:
+ with self.subTest(c):
+ out, note = R.set_role(roles(c["roles"]), V["hw"][c["hw"]], c["card"], c["role"])
+ self.assertEqual(out, roles(c["after"]))
+ self.assertEqual(note, c["note"])
+
+ def test_order(self):
+ for c in V["order"]:
+ with self.subTest(c):
+ self.assertEqual(R.order(roles(c["roles"]), V["hw"][c["hw"]]), c["gpu"])
+
+ def test_warnings(self):
+ for c in V["warnings"]:
+ with self.subTest(c):
+ w = R.warnings(roles(c["roles"]), V["hw"][c["hw"]], spill_gb=c.get("spill_gb", 0.0))
+ self.assertEqual([x["code"] for x in w], c["codes"])
+ if c.get("fix"):
+ self.assertEqual(w[0]["fix"], c["fix"])
+
+ def test_saved(self):
+ for c in V["saved"]:
+ with self.subTest(c):
+ got, problem = R.saved_roles(c["cfg"])
+ self.assertEqual(got, roles(c["roles"]))
+ if c.get("problem"):
+ self.assertIn(c["problem"], problem or "")
+
+ def test_legacy(self):
+ for c in V["legacy"]:
+ with self.subTest(c):
+ self.assertEqual(R.from_legacy(c["gpu"], V["hw"][c["hw"]], c.get("gpu_order")), roles(c["roles"]))
+
+
+class Words(unittest.TestCase):
+ def test_warnings_are_one_short_line_and_say_only_what_a_person_cannot_know(self):
+ two = V["hw"]["two"]
+ # a slower card as Main is NOT warned about: people understand it (owner rule)
+ self.assertEqual(R.warnings({0: "main", 1: "helper"}, two), [])
+ for case in V["warnings"]:
+ for w in R.warnings(roles(case["roles"]), V["hw"][case["hw"]], spill_gb=case.get("spill_gb", 0.0)):
+ self.assertLess(len(w["text"]), 90, w["text"])
+ self.assertNotIn("slower", w["text"].replace("is slow as Main", ""))
+
+ def test_cpu_only_line(self):
+ w = R.warnings({0: "off", 1: "off"}, V["hw"]["two"], engine_runs_cpu_only=True)
+ self.assertEqual(w[0]["text"], "Performance is degraded on CPU only.")
+ w = R.warnings({0: "off", 1: "off"}, V["hw"]["two"])
+ self.assertEqual(w[0]["text"], R.NO_CARD_LINE)
+
+ def test_sentence_and_describe(self):
+ self.assertEqual(R.sentence(V["hw"]["one"]), "Strata will use your RTX 4070 Ti.")
+ s = R.sentence(V["hw"]["three"])
+ self.assertIn("RTX 4070 Ti is Main: it is faster.", s)
+ self.assertIn("RTX 2060 starts Off: 8 GB or less.", s)
+ self.assertEqual(R.describe({0: "helper", 1: "main"}, V["hw"]["two"]), "Main: GPU 2 RTX 4070 Ti. Helper: GPU 1 RTX 3060.")
+
+ def test_cards_with_8_gb_or_less_start_off_but_a_lone_8_gb_card_is_main(self):
+ self.assertEqual(R.recommend([{"index": 0, "name": "RTX 4060", "vram_gb": 8}])["roles"], {0: "main"})
+ r = R.recommend([{"index": 0, "name": "A", "vram_gb": 12, "speed": 9}, {"index": 1, "name": "B", "vram_gb": 8, "speed": 5}, {"index": 2, "name": "C", "vram_gb": 10, "speed": 5}])
+ self.assertEqual(r["roles"], {0: "main", 1: "off", 2: "helper"})
+
+
+class MirrorAndParse(unittest.TestCase):
+ def test_mirror_writes_roles_and_the_legacy_fields_with_main_last(self):
+ m = R.mirror({0: "helper", 1: "main"}, V["hw"]["two"])
+ self.assertEqual(m["gpu_roles"], {"0": "helper", "1": "main"})
+ self.assertEqual((m["gpu"], m["gpu_order"]), ([0, 1], "as_given"))
+ self.assertNotIn("gpu_none", m)
+ one = R.mirror({0: "off", 1: "main"}, V["hw"]["two"])
+ self.assertEqual(one["gpu"], 1) # one card is a number, never a list (#3203)
+ none = R.mirror({0: "off", 1: "off"}, V["hw"]["two"])
+ self.assertEqual((none["gpu"], none["gpu_none"]), ([], True))
+
+ def test_parse_roles(self):
+ cards = V["hw"]["three"]
+ self.assertEqual(R.parse_roles("1=main, 0=helper,2=off", cards), {1: "main", 0: "helper", 2: "off"})
+ self.assertEqual(R.roles_from_text("1=main,0=helper", cards), {0: "helper", 1: "main", 2: "off"}) # unnamed cards are Off
+ self.assertEqual(R.roles_from_text("0=helper", cards), {0: "main", 1: "off", 2: "off"}) # a lone card on is Main
+ for bad in ("", "1", "1=boss", "x=main", "0=main,1=main", "7=main"):
+ with self.subTest(bad), self.assertRaises(ValueError):
+ R.parse_roles(bad, cards)
+
+ def test_normalize(self):
+ two = V["hw"]["two"]
+ self.assertEqual(R.normalize({0: "helper", 1: "helper"}, two), {0: "helper", 1: "main"})
+ self.assertEqual(R.normalize({0: "main", 1: "main"}, two), {0: "main", 1: "helper"})
+ self.assertEqual(R.normalize({0: "helper", 1: "off"}, two), {0: "main", 1: "off"})
+
+ def test_spill_uses_the_cards_that_are_on(self):
+ two = [{"index": 0, "name": "A", "vram_gb": 12}, {"index": 1, "name": "B", "vram_gb": 12}]
+ a = R.spill_for({0: "main", 1: "helper"}, two, 44.0, 32.0)
+ b = R.spill_for({0: "main", 1: "off"}, two, 44.0, 32.0)
+ self.assertLess(a, b)
+ self.assertEqual(R.spill_for({0: "main", 1: "off"}, two, None, 32.0), 0.0)
+
+
+if __name__ == "__main__":
+ unittest.main()