torch-cuda-compat 0.1.0__tar.gz

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,27 @@
1
+ CC0 1.0 Universal — Public Domain Dedication
2
+
3
+ The person who associated a work with this deed has dedicated the work to the
4
+ public domain by waiving all of his or her rights to the work worldwide under
5
+ copyright law, including all related and neighboring rights, to the extent
6
+ allowed by law.
7
+
8
+ You can copy, modify, distribute and perform the work, even for commercial
9
+ purposes, all without asking permission.
10
+
11
+ Full text: https://creativecommons.org/publicdomain/zero/1.0/legalcode
12
+
13
+ ---
14
+
15
+ This dedication covers the compilation and the code in this package.
16
+
17
+ The underlying facts are taken from third-party sources, each of which is cited
18
+ by URL in the shipped data alongside the verbatim quote the value was read from:
19
+
20
+ * PyTorch's RELEASE.md and .ci/manywheel/build_cuda.sh — BSD-3-Clause
21
+ (pytorch/pytorch LICENSE)
22
+ * NVIDIA's CUDA Toolkit release notes and CUDA GPUs page — vendor technical
23
+ documentation
24
+
25
+ Facts are not copyrightable. What is reproduced from those sources is a fact
26
+ plus a short attributed quote linking back to it; neither document is
27
+ reproduced.
@@ -0,0 +1,130 @@
1
+ Metadata-Version: 2.4
2
+ Name: torch-cuda-compat
3
+ Version: 0.1.0
4
+ Summary: Which PyTorch wheel runs on which NVIDIA GPU, with the vendor's own words as evidence
5
+ Author: referencesource.org
6
+ License: CC0-1.0
7
+ Project-URL: Homepage, https://referencesource.org/torch-cuda-compat/
8
+ Project-URL: Source, https://referencesource.org/gpu-cuda-pytorch-compatibility/
9
+ Keywords: pytorch,cuda,nvidia,gpu,compute-capability,wheels
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
14
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
15
+ Requires-Python: >=3.8
16
+ Description-Content-Type: text/markdown
17
+ License-File: LICENSE
18
+ Dynamic: license-file
19
+
20
+ # torch-cuda-compat
21
+
22
+ Tells you which PyTorch wheel runs on a given NVIDIA GPU, and shows you the
23
+ line on NVIDIA's or PyTorch's own page that says so.
24
+
25
+ ```console
26
+ $ pip install torch-cuda-compat
27
+ $ torch-cuda-compat "RTX 5090" 2.7
28
+ GeForce RTX 5090 — compute capability 12.0
29
+ PyTorch 2.7
30
+
31
+ no CUDA 11.8 this build stops at compute capability 9.0; the card is
32
+ 12.0, so the wheel installs and then fails at the first
33
+ kernel launch
34
+ no CUDA 12.6 this build stops at compute capability 9.0; the card is
35
+ 12.0, so the wheel installs and then fails at the first
36
+ kernel launch
37
+ YES CUDA 12.8 compute capability 12.0 is compiled into this build
38
+
39
+ pip install torch --index-url https://download.pytorch.org/whl/cu128
40
+ needs an NVIDIA driver >= 525
41
+ ```
42
+
43
+ ```python
44
+ >>> from torch_cuda_compat import resolve
45
+ >>> r = resolve("RTX 5090", "2.7")
46
+ >>> r["recommended"]["cuda"]
47
+ '12.8'
48
+ >>> r["recommended"]["install"]
49
+ 'pip install torch --index-url https://download.pytorch.org/whl/cu128'
50
+ >>> r["recommended"]["evidence"][0]["quote"]
51
+ 'TORCH_CUDA_ARCH_LIST="7.5;8.0;8.6;9.0;10.0;12.0+PTX"'
52
+ ```
53
+
54
+ ## The thing this gets right
55
+
56
+ A PyTorch wheel only runs on a GPU whose **compute capability was compiled into
57
+ it**, and that list is not the same as "CUDA supports this card". An RTX 5090 is
58
+ compute capability 12.0; the `cu126` build of PyTorch 2.7 was compiled for 5.0
59
+ through 9.0. It installs perfectly and then dies at the first kernel launch.
60
+ `cu128` was compiled for 12.0 and works.
61
+
62
+ Three rules decide it, and all three are applied here:
63
+
64
+ - **Compiled in.** The wheel's `TORCH_CUDA_ARCH_LIST` names the card's compute
65
+ capability outright.
66
+ - **Binary compatibility.** A cubin runs on any later minor revision of the same
67
+ major architecture. This is why `cu126`, compiled for 8.0 and 8.6 and never
68
+ mentioning 8.9, runs fine on an RTX 4090 — the case a hand-written table
69
+ usually gets wrong. It does **not** cross a major: an sm_100 cubin
70
+ (data-centre Blackwell, a B200) does not run on an sm_120 card (consumer
71
+ Blackwell, a 5090), even though both are called Blackwell.
72
+ - **`+PTX`.** An architecture marked `+PTX` ships as JIT source too, so the
73
+ driver compiles it at first launch for any newer card. It works, after a pause
74
+ the first time.
75
+
76
+ Where no source states which architectures a build was compiled for, `runs` is
77
+ `None` — *not known*, rather than *no*.
78
+
79
+ ## Every value cites its source
80
+
81
+ ```python
82
+ >>> r = resolve("RTX 4090", "2.6")
83
+ >>> r["gpu_evidence"]["source"]
84
+ 'https://developer.nvidia.com/cuda/gpus'
85
+ >>> r["gpu_evidence"]["quote"] # the row the 8.9 was read out of
86
+ '8.9 | NVIDIA L4 NVIDIA L40 NVIDIA L40S | ... GeForce RTX 4090'
87
+ >>> {e["source"] for e in r["recommended"]["evidence"]}
88
+ {'https://raw.githubusercontent.com/pytorch/pytorch/release/2.6/.ci/manywheel/build_cuda.sh',
89
+ 'https://docs.nvidia.com/cuda/cuda-toolkit-release-notes/index.html'}
90
+ ```
91
+
92
+ That is the point of the package. The values come from NVIDIA's CUDA GPU list,
93
+ NVIDIA's CUDA Toolkit release notes and PyTorch's `RELEASE.md` and per-release
94
+ build scripts, and each one carries the URL and the verbatim quote it was read
95
+ from, so you can check it instead of trusting it. Nothing here is a value
96
+ somebody typed out from memory.
97
+
98
+ ## What is in it
99
+
100
+ 441 NVIDIA GPUs with their compute capability, and 45 (PyTorch release, CUDA
101
+ build) pairings covering PyTorch 1.12 through 2.14 and CUDA 11.3 through 13.2 —
102
+ each with the Python versions, the cuDNN version, the wheel index URL, the
103
+ compiled architecture list and the minimum NVIDIA driver. About 300 KB of JSON,
104
+ no dependencies, and no network access at runtime.
105
+
106
+ ## API
107
+
108
+ | | |
109
+ |---|---|
110
+ | `resolve(gpu, torch)` | the answer: every CUDA build of that release, each with `runs`, `why` and its evidence, plus `recommended` |
111
+ | `compute_capability(gpu)` | the GPU table entry; raises `GPUNotFound` rather than guessing |
112
+ | `architectures(pairing)` | the compute capabilities a build was compiled for |
113
+ | `gpus()`, `pairings()`, `data()` | the shipped dataset |
114
+
115
+ GPU names are matched leniently: `"RTX 5090"`, `"rtx-5090"` and the
116
+ `"NVIDIA GeForce RTX 5090"` that `torch.cuda.get_device_name()` returns all find
117
+ the same card. An ambiguous name raises and lists the candidates instead of
118
+ picking one.
119
+
120
+ ## Data and licence
121
+
122
+ Browse the dataset, one page per record, at
123
+ **<https://referencesource.org/gpu-cuda-pytorch-compatibility/>**.
124
+
125
+ The compilation is CC0-1.0. The underlying facts come from PyTorch (BSD-3-Clause)
126
+ and NVIDIA's technical documentation; each value cites its source, and short
127
+ attributed quotes are all that is reproduced.
128
+
129
+ A JavaScript port shipping the identical data is on npm as
130
+ [`torch-cuda-compat`](https://www.npmjs.com/package/torch-cuda-compat).
@@ -0,0 +1,111 @@
1
+ # torch-cuda-compat
2
+
3
+ Tells you which PyTorch wheel runs on a given NVIDIA GPU, and shows you the
4
+ line on NVIDIA's or PyTorch's own page that says so.
5
+
6
+ ```console
7
+ $ pip install torch-cuda-compat
8
+ $ torch-cuda-compat "RTX 5090" 2.7
9
+ GeForce RTX 5090 — compute capability 12.0
10
+ PyTorch 2.7
11
+
12
+ no CUDA 11.8 this build stops at compute capability 9.0; the card is
13
+ 12.0, so the wheel installs and then fails at the first
14
+ kernel launch
15
+ no CUDA 12.6 this build stops at compute capability 9.0; the card is
16
+ 12.0, so the wheel installs and then fails at the first
17
+ kernel launch
18
+ YES CUDA 12.8 compute capability 12.0 is compiled into this build
19
+
20
+ pip install torch --index-url https://download.pytorch.org/whl/cu128
21
+ needs an NVIDIA driver >= 525
22
+ ```
23
+
24
+ ```python
25
+ >>> from torch_cuda_compat import resolve
26
+ >>> r = resolve("RTX 5090", "2.7")
27
+ >>> r["recommended"]["cuda"]
28
+ '12.8'
29
+ >>> r["recommended"]["install"]
30
+ 'pip install torch --index-url https://download.pytorch.org/whl/cu128'
31
+ >>> r["recommended"]["evidence"][0]["quote"]
32
+ 'TORCH_CUDA_ARCH_LIST="7.5;8.0;8.6;9.0;10.0;12.0+PTX"'
33
+ ```
34
+
35
+ ## The thing this gets right
36
+
37
+ A PyTorch wheel only runs on a GPU whose **compute capability was compiled into
38
+ it**, and that list is not the same as "CUDA supports this card". An RTX 5090 is
39
+ compute capability 12.0; the `cu126` build of PyTorch 2.7 was compiled for 5.0
40
+ through 9.0. It installs perfectly and then dies at the first kernel launch.
41
+ `cu128` was compiled for 12.0 and works.
42
+
43
+ Three rules decide it, and all three are applied here:
44
+
45
+ - **Compiled in.** The wheel's `TORCH_CUDA_ARCH_LIST` names the card's compute
46
+ capability outright.
47
+ - **Binary compatibility.** A cubin runs on any later minor revision of the same
48
+ major architecture. This is why `cu126`, compiled for 8.0 and 8.6 and never
49
+ mentioning 8.9, runs fine on an RTX 4090 — the case a hand-written table
50
+ usually gets wrong. It does **not** cross a major: an sm_100 cubin
51
+ (data-centre Blackwell, a B200) does not run on an sm_120 card (consumer
52
+ Blackwell, a 5090), even though both are called Blackwell.
53
+ - **`+PTX`.** An architecture marked `+PTX` ships as JIT source too, so the
54
+ driver compiles it at first launch for any newer card. It works, after a pause
55
+ the first time.
56
+
57
+ Where no source states which architectures a build was compiled for, `runs` is
58
+ `None` — *not known*, rather than *no*.
59
+
60
+ ## Every value cites its source
61
+
62
+ ```python
63
+ >>> r = resolve("RTX 4090", "2.6")
64
+ >>> r["gpu_evidence"]["source"]
65
+ 'https://developer.nvidia.com/cuda/gpus'
66
+ >>> r["gpu_evidence"]["quote"] # the row the 8.9 was read out of
67
+ '8.9 | NVIDIA L4 NVIDIA L40 NVIDIA L40S | ... GeForce RTX 4090'
68
+ >>> {e["source"] for e in r["recommended"]["evidence"]}
69
+ {'https://raw.githubusercontent.com/pytorch/pytorch/release/2.6/.ci/manywheel/build_cuda.sh',
70
+ 'https://docs.nvidia.com/cuda/cuda-toolkit-release-notes/index.html'}
71
+ ```
72
+
73
+ That is the point of the package. The values come from NVIDIA's CUDA GPU list,
74
+ NVIDIA's CUDA Toolkit release notes and PyTorch's `RELEASE.md` and per-release
75
+ build scripts, and each one carries the URL and the verbatim quote it was read
76
+ from, so you can check it instead of trusting it. Nothing here is a value
77
+ somebody typed out from memory.
78
+
79
+ ## What is in it
80
+
81
+ 441 NVIDIA GPUs with their compute capability, and 45 (PyTorch release, CUDA
82
+ build) pairings covering PyTorch 1.12 through 2.14 and CUDA 11.3 through 13.2 —
83
+ each with the Python versions, the cuDNN version, the wheel index URL, the
84
+ compiled architecture list and the minimum NVIDIA driver. About 300 KB of JSON,
85
+ no dependencies, and no network access at runtime.
86
+
87
+ ## API
88
+
89
+ | | |
90
+ |---|---|
91
+ | `resolve(gpu, torch)` | the answer: every CUDA build of that release, each with `runs`, `why` and its evidence, plus `recommended` |
92
+ | `compute_capability(gpu)` | the GPU table entry; raises `GPUNotFound` rather than guessing |
93
+ | `architectures(pairing)` | the compute capabilities a build was compiled for |
94
+ | `gpus()`, `pairings()`, `data()` | the shipped dataset |
95
+
96
+ GPU names are matched leniently: `"RTX 5090"`, `"rtx-5090"` and the
97
+ `"NVIDIA GeForce RTX 5090"` that `torch.cuda.get_device_name()` returns all find
98
+ the same card. An ambiguous name raises and lists the candidates instead of
99
+ picking one.
100
+
101
+ ## Data and licence
102
+
103
+ Browse the dataset, one page per record, at
104
+ **<https://referencesource.org/gpu-cuda-pytorch-compatibility/>**.
105
+
106
+ The compilation is CC0-1.0. The underlying facts come from PyTorch (BSD-3-Clause)
107
+ and NVIDIA's technical documentation; each value cites its source, and short
108
+ attributed quotes are all that is reproduced.
109
+
110
+ A JavaScript port shipping the identical data is on npm as
111
+ [`torch-cuda-compat`](https://www.npmjs.com/package/torch-cuda-compat).
@@ -0,0 +1,34 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "torch-cuda-compat"
7
+ version = "0.1.0"
8
+ description = "Which PyTorch wheel runs on which NVIDIA GPU, with the vendor's own words as evidence"
9
+ readme = "README.md"
10
+ requires-python = ">=3.8"
11
+ license = { text = "CC0-1.0" }
12
+ authors = [{ name = "referencesource.org" }]
13
+ keywords = ["pytorch", "cuda", "nvidia", "gpu", "compute-capability", "wheels"]
14
+ classifiers = [
15
+ "Development Status :: 4 - Beta",
16
+ "Intended Audience :: Developers",
17
+ "Programming Language :: Python :: 3",
18
+ "Topic :: Scientific/Engineering :: Artificial Intelligence",
19
+ "Topic :: Software Development :: Libraries :: Python Modules",
20
+ ]
21
+ dependencies = []
22
+
23
+ [project.urls]
24
+ Homepage = "https://referencesource.org/torch-cuda-compat/"
25
+ Source = "https://referencesource.org/gpu-cuda-pytorch-compatibility/"
26
+
27
+ [project.scripts]
28
+ torch-cuda-compat = "torch_cuda_compat.__main__:main"
29
+
30
+ [tool.setuptools.packages.find]
31
+ where = ["src"]
32
+
33
+ [tool.setuptools.package-data]
34
+ torch_cuda_compat = ["data.json"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -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
+ }