torch-cuda-compat 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,296 @@
1
+ """Which PyTorch wheel runs on which NVIDIA GPU — with the vendor's own words.
2
+
3
+ >>> from torch_cuda_compat import resolve
4
+ >>> r = resolve("RTX 5090", "2.7")
5
+ >>> [(o["cuda"], o["runs"]) for o in r["options"]]
6
+ [('11.8', False), ('12.6', False), ('12.8', True)]
7
+
8
+ The question this answers is the one people get wrong: a wheel only runs on a
9
+ GPU whose compute capability was *compiled into it*, and that list is not the
10
+ same as "CUDA supports the card". An RTX 5090 is compute capability 12.0; the
11
+ `cu126` build of PyTorch 2.7 was compiled for 5.0 through 9.0, so it installs
12
+ happily and then fails at the first kernel launch. The `cu128` build was
13
+ compiled for 12.0 and works.
14
+
15
+ Every answer carries the source URL and the verbatim quote each value came from,
16
+ so it can be checked rather than believed. Data:
17
+ https://referencesource.org/gpu-cuda-pytorch-compatibility/
18
+ """
19
+ from __future__ import annotations
20
+
21
+ import json
22
+ import pathlib
23
+ import re
24
+ from typing import Any, Dict, List, Optional
25
+
26
+ __all__ = ["resolve", "gpus", "pairings", "compute_capability",
27
+ "architectures", "data", "GPUNotFound", "__version__"]
28
+
29
+ __version__ = "0.1.0"
30
+
31
+ _DATA: Optional[Dict[str, Any]] = None
32
+
33
+
34
+ class GPUNotFound(LookupError):
35
+ """No GPU in the table matched the name given."""
36
+
37
+
38
+ def data() -> Dict[str, Any]:
39
+ """The shipped dataset, loaded once."""
40
+ global _DATA
41
+ if _DATA is None:
42
+ p = pathlib.Path(__file__).with_name("data.json")
43
+ _DATA = json.loads(p.read_text(encoding="utf-8"))
44
+ return _DATA
45
+
46
+
47
+ def gpus() -> List[Dict[str, Any]]:
48
+ return data()["gpus"]
49
+
50
+
51
+ def pairings() -> List[Dict[str, Any]]:
52
+ return data()["pairings"]
53
+
54
+
55
+ # --------------------------------------------------------------- GPU lookup
56
+
57
+ def _norm(s: str) -> str:
58
+ """Fold a GPU name to its comparable core.
59
+
60
+ People type "RTX 5090", "rtx-5090", "NVIDIA GeForce RTX 5090" and
61
+ "GeForce RTX 5090 Laptop GPU" for the same card, and `torch.cuda
62
+ .get_device_name()` returns "NVIDIA GeForce RTX 5090". The vendor prefix,
63
+ the product line word and punctuation are all noise for matching; the model
64
+ number is not.
65
+ """
66
+ s = s.lower().replace("*", " ")
67
+ s = re.sub(r"\b(nvidia|geforce|quadro|tesla)\b", " ", s)
68
+ s = re.sub(r"[^a-z0-9]+", " ", s)
69
+ return " ".join(s.split())
70
+
71
+
72
+ def compute_capability(gpu: str) -> Dict[str, Any]:
73
+ """The GPU table entry for `gpu`, matched leniently on the name.
74
+
75
+ Raises GPUNotFound rather than guessing. A wrong card silently substituted
76
+ would produce a confident wrong answer, which is the failure this package
77
+ exists to remove.
78
+ """
79
+ want = _norm(gpu)
80
+ if not want:
81
+ raise GPUNotFound("no GPU name given")
82
+ entries = gpus()
83
+ exact = [g for g in entries if _norm(g["model"]) == want]
84
+ if exact:
85
+ return exact[0]
86
+ # A distinctive model number is a strong match: "5090" appears in exactly
87
+ # one consumer card. A word that appears in dozens ("rtx") is not, so a
88
+ # containment match only counts when it pins down a single entry.
89
+ near = [g for g in entries
90
+ if want in _norm(g["model"]) or _norm(g["model"]) in want]
91
+ if len(near) == 1:
92
+ return near[0]
93
+ if near:
94
+ raise GPUNotFound(
95
+ "{0!r} matches {1} GPUs ({2}) — name it exactly".format(
96
+ gpu, len(near), ", ".join(g["model"] for g in near[:6])))
97
+ raise GPUNotFound("{0!r} is not in the table".format(gpu))
98
+
99
+
100
+ # ------------------------------------------------------- architecture lists
101
+
102
+ _CAP = re.compile(r"(\d+\.\d+)(\+PTX)?")
103
+
104
+
105
+ def _parse_list(s: str) -> Dict[str, Any]:
106
+ """Compute capabilities out of either notation the sources use.
107
+
108
+ PyTorch's release notes name them ("Turing(7.5), Ampere(8.0, 8.6)"); its
109
+ build scripts list them ("7.5;8.0;8.6;9.0;12.0+PTX"). Both reduce to the
110
+ same set, plus the subset that carries PTX.
111
+ """
112
+ caps, ptx = [], []
113
+ for m in _CAP.finditer(s or ""):
114
+ v = float(m.group(1))
115
+ caps.append(v)
116
+ if m.group(2):
117
+ ptx.append(v)
118
+ return {"caps": sorted(set(caps)), "ptx": sorted(set(ptx))}
119
+
120
+
121
+ _ARCH_IF = re.compile(
122
+ r'\$\(\s*\[\[\s*"?\$ARCH"?\s*==\s*"?aarch64"?\s*\]\]\s*&&\s*'
123
+ r'echo\s+"([^"]*)"\s*\|\|\s*echo\s+"([^"]*)"\s*\)')
124
+
125
+
126
+ def _expand(base: str, build: str) -> Optional[str]:
127
+ """The list a build-script line means, or None if it cannot be read.
128
+
129
+ The scripts compose the list from a shell variable, so the published record
130
+ carries both halves verbatim rather than an expansion nobody could check.
131
+ Three forms occur: plain substitution, bash's remove-pattern
132
+ (`${TORCH_CUDA_ARCH_LIST//10.0/}`), and a conditional that adds an
133
+ architecture only on aarch64 (`$([[ "$ARCH" == "aarch64" ]] && echo "11.0;"
134
+ || echo "")`). The record is the Linux x86_64 wheel — that is the index its
135
+ `wheel_index` names — so that last one takes its else branch. Anything else
136
+ returns None: a guess here would be exactly the invented value this package
137
+ is meant to replace.
138
+ """
139
+ m = re.search(r'TORCH_CUDA_ARCH_LIST="(.*)"\s*$', build or "")
140
+ if not m:
141
+ return None
142
+ body = _ARCH_IF.sub(lambda mm: mm.group(2), m.group(1))
143
+ bm = re.search(r'TORCH_CUDA_ARCH_LIST="([^"]*)"', base or "")
144
+ base_val = bm.group(1) if bm else None
145
+
146
+ def sub(mm: "re.Match") -> str:
147
+ if base_val is None:
148
+ raise ValueError("no base list")
149
+ remove = mm.group(1)
150
+ if remove is None:
151
+ return base_val
152
+ return base_val.replace(remove, "")
153
+
154
+ try:
155
+ out = re.sub(r"\$\{TORCH_CUDA_ARCH_LIST(?://([^/]*)/)?\}", sub, body)
156
+ except ValueError:
157
+ return None
158
+ if "$" in out:
159
+ return None
160
+ return ";".join(p for p in out.split(";") if p.strip())
161
+
162
+
163
+ def architectures(pairing: Dict[str, Any]) -> Dict[str, Any]:
164
+ """{"caps", "ptx", "text", "evidence"} for a pairing, or None caps if unknown.
165
+
166
+ `text` is what a source actually printed, never a value we assembled — where
167
+ the list had to be expanded from a build script, both halves are quoted.
168
+ """
169
+ if pairing.get("architectures"):
170
+ out = _parse_list(pairing["architectures"])
171
+ out["text"] = pairing["architectures"]
172
+ out["evidence"] = [pairing["evidence"].get("architectures")]
173
+ return out
174
+ base = pairing.get("arch_list_base")
175
+ build = pairing.get("arch_list_build")
176
+ if build:
177
+ expanded = _expand(base or "", build)
178
+ if expanded:
179
+ out = _parse_list(expanded)
180
+ out["text"] = expanded
181
+ out["expanded_from"] = {"base": base, "build": build}
182
+ out["evidence"] = [e for e in
183
+ (pairing["evidence"].get("arch_list_base"),
184
+ pairing["evidence"].get("arch_list_build"))
185
+ if e]
186
+ return out
187
+ return {"caps": [], "ptx": [], "text": None, "evidence": []}
188
+
189
+
190
+ # ---------------------------------------------------------- the CUDA rules
191
+
192
+ def _fmt(v: float) -> str:
193
+ return ("{0:.1f}".format(v)).rstrip("0").rstrip(".") if v % 1 else \
194
+ "{0:.1f}".format(v)
195
+
196
+
197
+ def _binary_compatible(caps: List[float], cc: float) -> Optional[float]:
198
+ """The compiled architecture whose cubin runs natively on `cc`, if any.
199
+
200
+ CUDA guarantees binary compatibility from one minor revision to the next
201
+ *within a major architecture*, upwards only: a cubin built for sm_86 runs on
202
+ an sm_89 card, and one built for sm_60 runs on sm_61. This is why PyTorch's
203
+ `cu126` wheels — which are compiled for 8.0 and 8.6 and never mention 8.9 —
204
+ run perfectly well on an RTX 4090, and getting it wrong makes the whole
205
+ answer wrong in the most common case there is.
206
+
207
+ It does not cross a major: an sm_100 cubin (data-centre Blackwell) does not
208
+ run on an sm_120 card (consumer Blackwell), which is a real trap because
209
+ both are called Blackwell.
210
+ """
211
+ same = [c for c in caps if int(c) == int(cc) and c <= cc]
212
+ return max(same) if same else None
213
+
214
+
215
+ # ------------------------------------------------------------------ resolve
216
+
217
+ def resolve(gpu: str, torch: str) -> Dict[str, Any]:
218
+ """Will PyTorch `torch` run on `gpu`, and which CUDA build should be used?
219
+
220
+ `torch` may be "2.7" or "2.7.1"; the table is per minor release, which is
221
+ the granularity PyTorch publishes CUDA builds at.
222
+
223
+ Returns every CUDA build that release ships, each with `runs` and the
224
+ evidence behind it, plus `recommended`: the newest build that runs, which is
225
+ the one to install. `recommended` is None when none of them do — for a card
226
+ newer than the release, that is the true answer and saying so is the point.
227
+ """
228
+ entry = compute_capability(gpu)
229
+ cc = float(entry["compute_capability"])
230
+ minor = ".".join(str(torch).split(".")[:2])
231
+
232
+ options = []
233
+ for p in pairings():
234
+ if p["torch"] != minor:
235
+ continue
236
+ arch = architectures(p)
237
+ caps, ptx = arch["caps"], arch["ptx"]
238
+ if not caps:
239
+ runs, why = None, (
240
+ "no source states which architectures this build was compiled "
241
+ "for, so this is not known rather than false")
242
+ elif cc in caps:
243
+ runs, why = True, (
244
+ "compute capability {0} is compiled into this build".format(
245
+ entry["compute_capability"]))
246
+ elif _binary_compatible(caps, cc) is not None:
247
+ runs, why = True, (
248
+ "compiled for {0}, and a cubin runs on any later minor "
249
+ "revision of the same architecture, so it runs on {1}".format(
250
+ _fmt(_binary_compatible(caps, cc)),
251
+ entry["compute_capability"]))
252
+ elif any(p_ <= cc for p_ in ptx):
253
+ runs, why = True, (
254
+ "compiled for {0}+PTX, which the driver compiles at first "
255
+ "launch for compute capability {1} — it works, after a pause "
256
+ "the first time".format(
257
+ _fmt(max(p_ for p_ in ptx if p_ <= cc)),
258
+ entry["compute_capability"]))
259
+ elif cc > max(caps):
260
+ runs, why = False, (
261
+ "this build stops at compute capability {0}; the card is {1}, "
262
+ "so the wheel installs and then fails at the first kernel "
263
+ "launch".format(max(caps), entry["compute_capability"]))
264
+ else:
265
+ runs, why = False, (
266
+ "compute capability {0} is not among the architectures this "
267
+ "build was compiled for ({1})".format(
268
+ entry["compute_capability"], arch["text"]))
269
+ options.append({
270
+ "cuda": p["cuda"],
271
+ "runs": runs,
272
+ "why": why,
273
+ "architectures": arch["text"],
274
+ "wheel_index": p.get("wheel_index"),
275
+ "install": "pip install torch --index-url {0}".format(
276
+ p["wheel_index"]) if p.get("wheel_index") else None,
277
+ "python": p.get("python"),
278
+ "cudnn": p.get("cudnn"),
279
+ "min_driver": p.get("min_driver_family"),
280
+ "page": p.get("page"),
281
+ "evidence": [e for e in (arch["evidence"] + [
282
+ p["evidence"].get("min_driver_family")]) if e],
283
+ })
284
+ options.sort(key=lambda o: [int(x) for x in o["cuda"].split(".")])
285
+
286
+ yes = [o for o in options if o["runs"]]
287
+ return {
288
+ "gpu": entry["model"],
289
+ "compute_capability": entry["compute_capability"],
290
+ "gpu_page": entry["page"],
291
+ "gpu_evidence": entry["evidence"],
292
+ "torch": minor,
293
+ "options": options,
294
+ "recommended": yes[-1] if yes else None,
295
+ "known": bool(options),
296
+ }
@@ -0,0 +1,79 @@
1
+ """`torch-cuda-compat "RTX 5090" 2.7` — the answer, and where it came from.
2
+
3
+ $ torch-cuda-compat "RTX 5090" 2.7
4
+ NVIDIA GeForce RTX 5090 — compute capability 12.0
5
+ PyTorch 2.7
6
+
7
+ no CUDA 11.8 this build stops at compute capability 9.0; the card is
8
+ 12.0, so the wheel installs and then fails at the first
9
+ kernel launch
10
+ no CUDA 12.6 ...
11
+ YES CUDA 12.8 compute capability 12.0 is compiled into this build
12
+
13
+ pip install torch --index-url https://download.pytorch.org/whl/cu128
14
+
15
+ Exit status is 0 when some build runs, 1 when none does and 2 when the GPU is
16
+ not in the table — so it is usable in a shell test.
17
+ """
18
+ from __future__ import annotations
19
+
20
+ import argparse
21
+ import json
22
+ import sys
23
+ import textwrap
24
+
25
+ from . import GPUNotFound, __version__, resolve
26
+
27
+
28
+ def _wrap(line: str, indent: int, width: int = 78) -> str:
29
+ return textwrap.fill(line, width=width, subsequent_indent=" " * indent)
30
+
31
+
32
+ def main(argv=None) -> int:
33
+ ap = argparse.ArgumentParser(
34
+ prog="torch-cuda-compat",
35
+ description="Which PyTorch wheel runs on which NVIDIA GPU.")
36
+ ap.add_argument("gpu", help='e.g. "RTX 5090", "A100", "GTX 1080 Ti"')
37
+ ap.add_argument("torch", help='PyTorch release, e.g. "2.7"')
38
+ ap.add_argument("--json", action="store_true",
39
+ help="the full answer, evidence included")
40
+ ap.add_argument("--version", action="version", version=__version__)
41
+ args = ap.parse_args(argv)
42
+
43
+ try:
44
+ r = resolve(args.gpu, args.torch)
45
+ except GPUNotFound as e:
46
+ print("torch-cuda-compat: {0}".format(e), file=sys.stderr)
47
+ return 2
48
+
49
+ if args.json:
50
+ json.dump(r, sys.stdout, indent=1)
51
+ sys.stdout.write("\n")
52
+ return 0 if r["recommended"] else 1
53
+
54
+ print("{0} — compute capability {1}".format(
55
+ r["gpu"], r["compute_capability"]))
56
+ print("PyTorch {0}".format(r["torch"]))
57
+ if not r["options"]:
58
+ print("\n no CUDA builds are recorded for PyTorch {0}".format(
59
+ r["torch"]))
60
+ return 1
61
+ print()
62
+ for o in r["options"]:
63
+ mark = {True: "YES", False: "no ", None: "? "}[o["runs"]]
64
+ print(_wrap(" {0} CUDA {1:<6} {2}".format(
65
+ mark, o["cuda"], o["why"]), 19))
66
+ rec = r["recommended"]
67
+ if rec:
68
+ print("\n{0}".format(rec["install"]))
69
+ if rec["min_driver"]:
70
+ print("needs an NVIDIA driver {0}".format(rec["min_driver"]))
71
+ else:
72
+ print("\nNo CUDA build of PyTorch {0} runs on this card.".format(
73
+ r["torch"]))
74
+ print("\nEvidence: {0}".format(r["gpu_page"]))
75
+ return 0 if rec else 1
76
+
77
+
78
+ if __name__ == "__main__":
79
+ raise SystemExit(main())