torch-amd-setup 0.1.0__tar.gz

torch_amd_setup-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+.venv*/
+venv*/
+.env
+*.log
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage

torch_amd_setup-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ChharithOeun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

torch_amd_setup-0.1.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: torch-amd-setup
+Version: 0.1.0
+Summary: Auto-detects the best PyTorch compute device for AMD GPUs, with gfx1010 ROCm override support (RX 5700 XT, RX 5600 XT, Navi 10)
+Project-URL: Homepage, https://github.com/ChharithOeun/torch-amd-setup
+Project-URL: Repository, https://github.com/ChharithOeun/torch-amd-setup
+Project-URL: Issues, https://github.com/ChharithOeun/torch-amd-setup/issues
+Project-URL: Documentation, https://github.com/ChharithOeun/torch-amd-setup/tree/main/docs
+License: MIT
+License-File: LICENSE
+Keywords: amd,device-detection,directml,gfx1010,gpu,machine-learning,navi10,pytorch,rocm,rx5700xt
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Provides-Extra: cpu
+Requires-Dist: torch>=2.2.0; extra == 'cpu'
+Provides-Extra: cuda
+Requires-Dist: torch>=2.2.0; extra == 'cuda'
+Requires-Dist: torchaudio; extra == 'cuda'
+Requires-Dist: torchvision; extra == 'cuda'
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: directml
+Requires-Dist: torch-directml; extra == 'directml'
+Requires-Dist: torch==2.3.0; extra == 'directml'
+Provides-Extra: rocm
+Requires-Dist: torch>=2.2.0; extra == 'rocm'
+Requires-Dist: torchaudio; extra == 'rocm'
+Requires-Dist: torchvision; extra == 'rocm'
+Description-Content-Type: text/markdown
+
+# torch-amd-setup
+
+**Auto-detects the best PyTorch compute device for AMD GPUs** — with first-class support for cards that are not in ROCm's default allow-list (RX 5700 XT, RX 5600 XT, RX 5500 XT / gfx1010–gfx1012).
+
+One import. No manual env var hunting. Works on Windows, Linux, WSL2, and macOS.
+
+```python
+from torch_amd_setup import get_best_device, get_torch_device, get_dtype
+
+device_type = get_best_device()   # "rocm" | "dml" | "cuda" | "mps" | "cpu"
+device      = get_torch_device()  # torch.device ready for model.to()
+dtype       = get_dtype()         # torch.float16 or torch.float32
+```
+
+---
+
+## The problem this solves
+
+AMD GPUs that use the **gfx1010 architecture** (Navi 10 — RX 5700 XT, RX 5700, RX 5600 XT) are not in ROCm's default supported GPU list. PyTorch on ROCm will silently fall back to CPU unless you set:
+
+```bash
+export HSA_OVERRIDE_GFX_VERSION=10.3.0
+```
+
+...but it has to be set *before* Python imports torch, which means you either:
+- Remember to set it in every shell session, or
+- Bake it into a shell script wrapper, or
+- Set it in your Python script before the first `import torch`
+
+`torch-amd-setup` handles all of that automatically. It also detects DirectML on Windows (no ROCm required), Apple MPS on macOS, NVIDIA CUDA, and falls back to CPU — so you can ship one codebase that works everywhere.
+
+---
+
+## Detection priority
+
+| Priority | Backend        | Platform            | Requirement                          |
+|----------|---------------|---------------------|--------------------------------------|
+| 1        | NVIDIA CUDA   | Any                 | Standard `pip install torch`         |
+| 2        | AMD ROCm      | Linux / WSL2        | ROCm PyTorch + AMD driver ≥22.20     |
+| 3        | AMD DirectML  | Windows             | `pip install torch-directml`, Py≤3.11 |
+| 4        | Apple MPS     | macOS Apple Silicon | Standard `pip install torch`         |
+| 5        | CPU           | Any                 | Always available, always slow        |
+
+---
+
+## Install
+
+```bash
+pip install torch-amd-setup
+```
+
+> `torch` is not a hard dependency — install the appropriate torch variant for your hardware first (see [Tutorial](docs/tutorial.md)).
+
+---
+
+## Quick start
+
+```python
+from torch_amd_setup import get_best_device, get_torch_device, get_dtype
+import torch
+
+device_type = get_best_device()
+device      = get_torch_device(device_type)
+dtype       = get_dtype(device_type)
+
+print(f"Using: {device_type} → {device} @ {dtype}")
+
+# Load your model
+model = MyModel().to(device).to(dtype)
+```
+
+### Diagnostics CLI
+
+```bash
+python -m torch_amd_setup
+```
+
+Output:
+```
+── torch-amd-setup diagnostics ──────────────────────────────
+  python_version            3.10.12
+  platform                  Linux-6.6.x-WSL2-x86_64
+  best_device               rocm
+  cuda_available            True
+  cuda_device_name          AMD Radeon RX 5700 XT
+  cuda_vram_mb              8176
+  rocm_available            True
+  torch_version             2.6.0+rocm6.1
+  ...
+```
+
+---
+
+## API Reference
+
+### `get_best_device() → str`
+Returns the best available device type as a string: `"cuda"`, `"rocm"`, `"dml"`, `"mps"`, or `"cpu"`.
+
+### `get_torch_device(device_type=None) → torch.device`
+Returns a `torch.device` object (or a DirectML device object for `"dml"`) ready for `model.to()`. If `device_type` is `None`, calls `get_best_device()` automatically.
+
+### `get_dtype(device_type=None) → torch.dtype`
+Returns `torch.float16` for CUDA/ROCm/MPS, and `torch.float32` for DirectML/CPU. DirectML float16 support is unreliable; this keeps you safe.
+
+### `device_info() → dict`
+Returns a diagnostic dictionary with all detected hardware info. Useful for logging and bug reports.
+
+### `get_install_guide() → str`
+Returns platform-appropriate install instructions as a formatted string.
+
+### `get_wsl2_install_guide() → str`
+Returns the full WSL2 + ROCm setup walkthrough for AMD GPUs on Windows.
+
+### `AMD_ROCM_ENV: dict`
+The environment variable overrides applied for gfx1010 support. You can inspect or override these before calling `get_best_device()`.
+
+---
+
+## AMD GPU compatibility
+
+| GPU                     | Architecture | HSA Override   | Tested |
+|-------------------------|-------------|----------------|--------|
+| RX 5700 XT              | gfx1010     | `10.3.0`       | ✅     |
+| RX 5700                 | gfx1010     | `10.3.0`       | ✅     |
+| RX 5600 XT              | gfx1010     | `10.3.0`       | ✅     |
+| RX 5500 XT              | gfx1011     | `10.3.0`       | ⚠️ reported |
+| RX 6000 series (gfx1030+) | RDNA2    | Not needed     | ✅ native ROCm |
+| RX 7000 series (gfx1100+) | RDNA3    | Not needed     | ✅ native ROCm |
+
+If your card isn't listed, check `GFX_OVERRIDE_MAP` in `detect.py` and open a PR.
+
+---
+
+## Windows users: DirectML vs WSL2
+
+| Feature              | DirectML           | WSL2 + ROCm        |
+|----------------------|--------------------|--------------------|
+| Setup difficulty     | Easy               | Medium             |
+| float16 support      | ❌ (float32 only) | ✅                 |
+| Python version limit | 3.11 max           | Any                |
+| GPU memory usage     | ~1.5× higher       | Native             |
+| Best for             | Quick experiments  | Production workloads |
+
+---
+
+## Contributing
+
+PRs welcome. Especially interested in:
+- Verified gfx override values for additional GPU models
+- ROCm 6.2+ compatibility reports
+- Windows DirectML on NVIDIA/Intel test results
+
+Please open an issue before large PRs.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+## Background
+
+This package was extracted from a private AI music pipeline project. The gfx1010 ROCm workaround was discovered the hard way — through several hours of cascading PyTorch installs, ROCm SDK conflicts, and dependency hell. The goal is that nobody else has to spend that time.
+
+See [docs/lessons-learned.md](docs/lessons-learned.md) for the full story.

torch_amd_setup-0.1.0/README.md

@@ -0,0 +1,167 @@
+# torch-amd-setup
+
+**Auto-detects the best PyTorch compute device for AMD GPUs** — with first-class support for cards that are not in ROCm's default allow-list (RX 5700 XT, RX 5600 XT, RX 5500 XT / gfx1010–gfx1012).
+
+One import. No manual env var hunting. Works on Windows, Linux, WSL2, and macOS.
+
+```python
+from torch_amd_setup import get_best_device, get_torch_device, get_dtype
+
+device_type = get_best_device()   # "rocm" | "dml" | "cuda" | "mps" | "cpu"
+device      = get_torch_device()  # torch.device ready for model.to()
+dtype       = get_dtype()         # torch.float16 or torch.float32
+```
+
+---
+
+## The problem this solves
+
+AMD GPUs that use the **gfx1010 architecture** (Navi 10 — RX 5700 XT, RX 5700, RX 5600 XT) are not in ROCm's default supported GPU list. PyTorch on ROCm will silently fall back to CPU unless you set:
+
+```bash
+export HSA_OVERRIDE_GFX_VERSION=10.3.0
+```
+
+...but it has to be set *before* Python imports torch, which means you either:
+- Remember to set it in every shell session, or
+- Bake it into a shell script wrapper, or
+- Set it in your Python script before the first `import torch`
+
+`torch-amd-setup` handles all of that automatically. It also detects DirectML on Windows (no ROCm required), Apple MPS on macOS, NVIDIA CUDA, and falls back to CPU — so you can ship one codebase that works everywhere.
+
+---
+
+## Detection priority
+
+| Priority | Backend        | Platform            | Requirement                          |
+|----------|---------------|---------------------|--------------------------------------|
+| 1        | NVIDIA CUDA   | Any                 | Standard `pip install torch`         |
+| 2        | AMD ROCm      | Linux / WSL2        | ROCm PyTorch + AMD driver ≥22.20     |
+| 3        | AMD DirectML  | Windows             | `pip install torch-directml`, Py≤3.11 |
+| 4        | Apple MPS     | macOS Apple Silicon | Standard `pip install torch`         |
+| 5        | CPU           | Any                 | Always available, always slow        |
+
+---
+
+## Install
+
+```bash
+pip install torch-amd-setup
+```
+
+> `torch` is not a hard dependency — install the appropriate torch variant for your hardware first (see [Tutorial](docs/tutorial.md)).
+
+---
+
+## Quick start
+
+```python
+from torch_amd_setup import get_best_device, get_torch_device, get_dtype
+import torch
+
+device_type = get_best_device()
+device      = get_torch_device(device_type)
+dtype       = get_dtype(device_type)
+
+print(f"Using: {device_type} → {device} @ {dtype}")
+
+# Load your model
+model = MyModel().to(device).to(dtype)
+```
+
+### Diagnostics CLI
+
+```bash
+python -m torch_amd_setup
+```
+
+Output:
+```
+── torch-amd-setup diagnostics ──────────────────────────────
+  python_version            3.10.12
+  platform                  Linux-6.6.x-WSL2-x86_64
+  best_device               rocm
+  cuda_available            True
+  cuda_device_name          AMD Radeon RX 5700 XT
+  cuda_vram_mb              8176
+  rocm_available            True
+  torch_version             2.6.0+rocm6.1
+  ...
+```
+
+---
+
+## API Reference
+
+### `get_best_device() → str`
+Returns the best available device type as a string: `"cuda"`, `"rocm"`, `"dml"`, `"mps"`, or `"cpu"`.
+
+### `get_torch_device(device_type=None) → torch.device`
+Returns a `torch.device` object (or a DirectML device object for `"dml"`) ready for `model.to()`. If `device_type` is `None`, calls `get_best_device()` automatically.
+
+### `get_dtype(device_type=None) → torch.dtype`
+Returns `torch.float16` for CUDA/ROCm/MPS, and `torch.float32` for DirectML/CPU. DirectML float16 support is unreliable; this keeps you safe.
+
+### `device_info() → dict`
+Returns a diagnostic dictionary with all detected hardware info. Useful for logging and bug reports.
+
+### `get_install_guide() → str`
+Returns platform-appropriate install instructions as a formatted string.
+
+### `get_wsl2_install_guide() → str`
+Returns the full WSL2 + ROCm setup walkthrough for AMD GPUs on Windows.
+
+### `AMD_ROCM_ENV: dict`
+The environment variable overrides applied for gfx1010 support. You can inspect or override these before calling `get_best_device()`.
+
+---
+
+## AMD GPU compatibility
+
+| GPU                     | Architecture | HSA Override   | Tested |
+|-------------------------|-------------|----------------|--------|
+| RX 5700 XT              | gfx1010     | `10.3.0`       | ✅     |
+| RX 5700                 | gfx1010     | `10.3.0`       | ✅     |
+| RX 5600 XT              | gfx1010     | `10.3.0`       | ✅     |
+| RX 5500 XT              | gfx1011     | `10.3.0`       | ⚠️ reported |
+| RX 6000 series (gfx1030+) | RDNA2    | Not needed     | ✅ native ROCm |
+| RX 7000 series (gfx1100+) | RDNA3    | Not needed     | ✅ native ROCm |
+
+If your card isn't listed, check `GFX_OVERRIDE_MAP` in `detect.py` and open a PR.
+
+---
+
+## Windows users: DirectML vs WSL2
+
+| Feature              | DirectML           | WSL2 + ROCm        |
+|----------------------|--------------------|--------------------|
+| Setup difficulty     | Easy               | Medium             |
+| float16 support      | ❌ (float32 only) | ✅                 |
+| Python version limit | 3.11 max           | Any                |
+| GPU memory usage     | ~1.5× higher       | Native             |
+| Best for             | Quick experiments  | Production workloads |
+
+---
+
+## Contributing
+
+PRs welcome. Especially interested in:
+- Verified gfx override values for additional GPU models
+- ROCm 6.2+ compatibility reports
+- Windows DirectML on NVIDIA/Intel test results
+
+Please open an issue before large PRs.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+## Background
+
+This package was extracted from a private AI music pipeline project. The gfx1010 ROCm workaround was discovered the hard way — through several hours of cascading PyTorch installs, ROCm SDK conflicts, and dependency hell. The goal is that nobody else has to spend that time.
+
+See [docs/lessons-learned.md](docs/lessons-learned.md) for the full story.

torch_amd_setup-0.1.0/docs/lessons-learned.md

@@ -0,0 +1,155 @@
+# Lessons Learned: Building AMD ROCm + PyTorch Support from Scratch
+
+**Date:** 2026-03-23
+**Context:** Extracting `torch-amd-setup` from a private AI audio pipeline project.
+**Hardware:** AMD Radeon RX 5700 XT (gfx1010 / Navi 10), Windows 11, WSL2 Ubuntu 22.04.
+
+This document is a raw account of every mistake made, every dependency wall hit, and every workaround discovered while getting AMD GPU acceleration working with PyTorch and Seamless M4T. Written so you don't have to spend the same time.
+
+---
+
+## 1. The gfx1010 problem — your GPU exists but ROCm ignores it
+
+The single biggest source of confusion: the AMD RX 5700 XT is a capable GPU, it's supported by the AMD Adrenalin driver, and it works fine for gaming. But ROCm (AMD's GPU compute stack) has an explicit list of officially supported GPU architectures, and gfx1010 is not on it.
+
+When you install the ROCm version of PyTorch and run `torch.cuda.is_available()`, it returns `False`. No error, no explanation — just `False`. This led to hours of assuming the ROCm install was broken, when the actual issue was a single missing environment variable:
+
+```bash
+export HSA_OVERRIDE_GFX_VERSION=10.3.0
+```
+
+This has to be set **before Python imports torch**. Setting it after `import torch` does nothing. The reason: ROCm checks the GPU architecture at init time and caches the result. If the env var isn't present at that moment, the GPU is invisible for the rest of the process.
+
+**Lesson:** If `torch.cuda.is_available()` returns False on ROCm, check the env var before anything else. Don't re-install ROCm.
+
+---
+
+## 2. Ubuntu 22.04 ships its own broken rocminfo
+
+Ubuntu 22.04's default `apt` repos include `rocminfo 5.0.0-1`. This package exists to provide stub implementations of ROCm tools. When you add AMD's official ROCm 6.1 repository and try to install `rocm-hip-sdk`, apt sees the conflict and fails:
+
+```
+rocm-hip-runtime: Depends: rocminfo (= 1.0.0.60100-82~22.04)
+                  but 5.0.0-1 is to be installed
+```
+
+The version numbers look backwards (5.0.0 > 1.0.0) but they're not comparable — AMD's rocminfo uses a different versioning scheme entirely. `5.0.0-1` is Ubuntu's stub; `1.0.0.60100` is AMD's real package at ROCm 6.1.
+
+**Fix:** Remove Ubuntu's ROCm stubs before installing from AMD's repo, then pin the AMD repo to priority 1001 so it always wins in future apt operations. See [Troubleshooting](troubleshooting.md#rocm-61-install-blocked-by-ubuntus-rocminfo-500).
+
+**Lesson:** Always purge Ubuntu's ROCm stubs before adding AMD's ROCm repo. Add the apt pin immediately.
+
+---
+
+## 3. set -e + grep = silent script death
+
+When writing the automated setup script (`wsl2_rocm_setup.sh`), the script was configured with `set -euo pipefail` for safety. However, certain commands that pipe through `grep -v` would cause the entire script to silently exit with no error message.
+
+The cause: when `apt-get -qq` runs with nothing to output (the package is already installed, or there are no packages matching), the `grep -v` that follows gets empty input and returns exit code 1 — "no lines matched the invert pattern." With `set -e`, exit code 1 from any command is fatal. The script dies silently at the first line that runs `| grep -v anything` on empty input.
+
+The debug session was confusing because there was no error — just a prompt returning after printing one progress message.
+
+**Fix:** `|| true` after any `grep` in a pipeline where empty output is possible. Also drop `-u` from `set -euo pipefail` if you have variables that might be unset legitimately.
+
+**Lesson:** When a `set -e` script exits silently, check every pipe for commands that could return non-zero on "no results" — grep, awk, wc -l comparisons, etc.
+
+---
+
+## 4. Dependency packages silently replace your ROCm torch
+
+Installing packages with PyPI dependencies that pin specific PyTorch versions will overwrite your ROCm build. This happened twice:
+
+- `fairseq2==0.3.0` pins `torch==2.5.1`. pip fetched that version from PyPI, which is the standard CUDA build. ROCm build gone.
+- After reinstalling ROCm torch 2.6.0, torchaudio 2.2.2 was installed separately, causing a version mismatch (`libcudart.so.13` error from the torchaudio build expecting torch 2.2.x).
+
+Each iteration added 10–20 minutes of reinstall time and debugging.
+
+**Lesson:** Install torch last, always. Use `--no-deps` for packages that try to pull their own torch. After any package install, verify `torch.version.hip` is still set. Consider using pip constraints or a lock file.
+
+---
+
+## 5. fairseq2n CPU binary doesn't exist for 0.2.1
+
+`seamless_communication 1.0.0` requires `fairseq2==0.2.*`. `fairseq2 0.2.1` requires `fairseq2n==0.2.1` (a C extension binary). The `fairseq2n` package on PyPI ships a CUDA-linked binary — it needs `libcudart.so.12` to import.
+
+Meta provides a CPU build server: `https://fair-src-fairseq2-build-publish.s3.amazonaws.com/whl/cpu/index.html` — but it only has builds for fairseq2n 0.3.x, not 0.2.1. So the official CPU binary for the version required by seamless_communication simply does not exist.
+
+The solution that worked: install `nvidia-cuda-runtime-cu12` via pip, which provides `libcudart.so.12` inside the venv's site-packages, then set `LD_LIBRARY_PATH` to point at it. This lets the CUDA-linked `fairseq2n.so` load correctly even on a machine with no NVIDIA GPU.
+
+**Lesson:** When a package claims to need CUDA but you don't have CUDA, try installing the CUDA runtime stub wheel first before assuming you need to rebuild from source.
+
+---
+
+## 6. torch-directml requires Python ≤3.11
+
+`torch-directml` is Microsoft's DirectML backend for PyTorch. It provides AMD (and any DirectX 12) GPU acceleration on Windows without needing ROCm. It's genuinely useful and easy to install — but it has a hard Python version ceiling of 3.11.
+
+This is a significant limitation because many projects now target Python 3.12+. The workaround is to maintain a separate `venv311` environment specifically for DirectML workloads. This is awkward but workable.
+
+The underlying reason is that `torch-directml` contains compiled C extensions that were built against Python 3.11's ABI. Microsoft hasn't released 3.12 wheels as of the time of writing.
+
+**Lesson:** Plan for a separate Python 3.11 venv on Windows if DirectML is on your path. Build your code to be venv-agnostic so switching is easy.
+
+---
+
+## 7. numpy 2.x breaks fairseq2 0.2.1
+
+`fairseq2 0.2.1` was compiled against NumPy 1.x. NumPy 2.0 introduced breaking C extension ABI changes. If pip installs NumPy 2.x (which it does by default now), importing `fairseq2` crashes:
+
+```
+A module that was compiled using NumPy 1.x cannot be run in NumPy 2.2.6
+_ARRAY_API not found
+```
+
+Fix: `pip install "numpy~=1.23" --force-reinstall`.
+
+**Lesson:** Any package with compiled C extensions and a `numpy~=1.x` pin is going to break if pip installs numpy 2.x before it. Add an explicit numpy pin to your requirements file before installing such packages.
+
+---
+
+## 8. WSL2 GPU passthrough needs /dev/kfd
+
+Even with a recent AMD driver, `/dev/kfd` (the AMD GPU compute device node) may not appear in WSL2 if:
+- The AMD Adrenalin driver version is below 22.20
+- The Windows version is below 10 21H2
+
+In our case, `/dev/kfd` was missing because the driver hadn't been verified yet. This caused `rocminfo` inside WSL2 to report no agents, even though ROCm was installed correctly.
+
+**Lesson:** Verify `/dev/kfd` exists before troubleshooting anything else. If it doesn't exist, the fix is a driver update in Windows — nothing inside WSL2 will help.
+
+---
+
+## 9. ROCm uses the CUDA compatibility layer — model.to("cuda") works
+
+ROCm PyTorch exposes AMD GPUs through a CUDA compatibility layer. From the Python API perspective, `torch.cuda.is_available()` returns `True`, `torch.cuda.get_device_name(0)` returns the AMD card name, and `model.to("cuda:0")` puts the model on the AMD GPU.
+
+This is intentional and by design. The practical consequence: code written for NVIDIA CUDA often works on AMD ROCm with zero changes. The catch is that some CUDA-specific operations (`torch.cuda.amp`, certain custom CUDA kernels) may not be supported.
+
+**Lesson:** Don't create separate "CUDA" and "ROCm" code paths. Use `get_torch_device()` which returns `torch.device("cuda:0")` for both — the ROCm PyTorch build handles the rest.
+
+---
+
+## 10. The model download hits the disk hard
+
+The SeamlessM4T v2 large model is ~8.5GB for the main checkpoint plus ~160MB for the vocoder. On first run, it downloads to `~/.cache/huggingface/hub/`. This is inside the WSL2 virtual disk, which lives on the Windows C: drive.
+
+On a machine with limited C: drive space, this is immediately a problem. The WSL2 virtual disk is also not easily inspectable from Windows Explorer, so users may not realize a 9GB file just appeared.
+
+**Lesson:** Warn users about the model download size before first run. Consider setting `HF_HOME` to redirect the cache to a larger drive. On a machine with an external drive, this is essential.
+
+---
+
+## Summary: What the setup actually requires
+
+Getting AMD ROCm + fairseq2 + seamless_communication working requires touching at least 8 separate failure points that are not documented together anywhere:
+
+1. Remove Ubuntu's conflicting ROCm stubs
+2. Pin the ROCm apt repo to priority 1001
+3. Set `HSA_OVERRIDE_GFX_VERSION=10.3.0` before importing torch
+4. Add user to `render` and `video` groups
+5. Install PyTorch from the ROCm-specific index URL
+6. Install `nvidia-cuda-runtime-cu12` for the CUDA stub
+7. Set `LD_LIBRARY_PATH` to the stub's lib directory
+8. Pin numpy to `~=1.23` before installing fairseq2
+
+None of these steps are individually complex. But they're scattered across AMD documentation, Meta's fairseq2 GitHub issues, Ubuntu Launchpad bug reports, and Stack Overflow threads. The goal of `torch-amd-setup` is to encode as much of this as possible so future projects don't start from scratch.