400Ping opened a new pull request, #1505:
URL: https://github.com/apache/mahout/pull/1505
[QDP] Builder backends name GPUs only; every encode result is a QdpTensor
### Related Issues
Related: #1177, #1189 (origin of the PyTorch reference), #1155, #1292 (AMD
route), #1320, #1323 (CPU fallback being removed), #1414 (`_qdp` importable ≠
GPU usable), #1467, #1331 (reference the old names / removed helper), #1477 /
#1483 (overlapping files, see below).
### Changes
- [ ] Bug fix
- [x] New feature
- [x] Refactoring
- [x] Documentation
- [x] Test
- [ ] CI/CD pipeline
- [ ] Other
### Why
QDP is GPU-only, but the Python builders made it look like it was not:
- `QuantumDataLoader` / `QdpBenchmark` took `.backend("pytorch")`, which ran
the pure-PyTorch reference from `torch_ref.py` — on CPU when no CUDA device was
found. The reference was added in #1189 as a benchmark baseline ("to compare
with current impl"), not as a backend, yet it was listed next to the real one
and people concluded "QDP runs on CPU with the PyTorch backend".
- The same backend was called `"rust"` on the builders and `"cuda"` on
`QdpEngine`.
- `QuantumDataLoader.backend("auto")` silently fell back to PyTorch (and
therefore CPU) when `_qdp` was missing, contradicting the docs ("PyTorch is not
used as an automatic fallback").
- The builders could not use the AMD route at all, although
`QdpEngine(backend="amd")` exists (#1155).
- `Backend` / `BACKEND` / `force_backend` and the `QdpTensor` facade were
exported but never used by any production code; `Backend.PYTORCH` reinforced
the misconception.
- The CUDA route returned the native `_qdp` tensor while the AMD route
returned a `torch.Tensor`, so switching backends changed the result type.
### How
**Backend selection (`loader.py`, `api.py`)**
- `.backend()` on both builders takes `"cuda"` (default) or `"amd"`; the
loader also takes `"auto"`.
- `"auto"` picks `"cuda"` when `_qdp.cuda_available()` is true, else `"amd"`
when `is_triton_amd_available()` is true, else raises `RuntimeError`. No CPU
fallback.
- `"rust"` and `"pytorch"` are rejected with `ValueError`. `torch_ref.py` is
unchanged and still used directly by the benchmark scripts and parity tests.
- New AMD paths: `QuantumDataLoader._create_amd_iterator` (synthetic and
`.npy` / `.pt` / `.pth` sources, batches built on CPU and moved by the engine)
and `QdpBenchmark._run_throughput_amd` (Python loop over
`TritonAmdEngine.encode`).
- `QdpBenchmark` defaults to f32, matching `QdpEngine` and the native
synthetic loader; the AMD loader mirrors the native precision rules (synthetic
f32, files f64, `.dtype()` honoured).
**Result type (`backend.py`, `loader.py`, `tensor.py`)**
- `QdpEngine.encode()` and every loader backend return `QdpTensor`; `.value`
is the backend-native object (`_qdp.QuantumTensor` on CUDA, `torch.Tensor` on
AMD), `.backend` is `"cuda"` or `"amd"`. `torch.from_dlpack(qt)` and
`qt.to_torch()` work on both.
- `QdpTensor.__dlpack__` forwards extra DLPack keyword arguments
(`max_version`, …).
**Removed / renamed**
- `Backend`, `BACKEND`, `force_backend`, `get_backend`, `require_backend`,
`get_torch` deleted; `_backend.py` → `_native.py` keeping only `get_qdp()`.
- `_select_torch_device` (#1323) deleted: the only path that used it is gone.
- `RustQdpEngine` → `NativeQdpEngine`; `is_cuda_available` →
`is_native_cuda_available`.
**Docs**
- `python-api.md`: backend model rewritten around `"cuda"` / `"amd"` /
`"auto"`, result type and `dtype()` documented, PyTorch reference no longer
presented as an encoder.
- AMD encoding support corrected to all six methods in `getting-started.md`,
`concepts.md`, `python-api.md` (stale since #1292); `TRITON_AMD_BACKEND.md` no
longer mentions the non-existent `QuantumTensorWrapper`.
- `qumat_qdp._backend` removed from `docs/api/qumat_qdp.yml`.
**Tests**
- `test_fallback.py` → `test_backend_selection.py`: selector validation and
`auto` routing, runnable without a GPU.
- New `qdp/qdp-python/tests/test_amd_builders.py` (`@pytest.mark.rocm`): AMD
loader synthetic and file sources, precision, `auto` on a ROCm host, benchmark
throughput/latency — real `TritonAmdEngine`, no fakes.
- Routing and Triton router tests updated to the `QdpTensor` contract.
### Breaking changes
- `.backend("rust")` → `.backend("cuda")`; `.backend("pytorch")` removed.
- `QuantumDataLoader.backend("auto")` raises instead of falling back to
PyTorch.
- `Backend`, `BACKEND`, `force_backend` removed from `qumat_qdp`.
- `RustQdpEngine` → `NativeQdpEngine`; `is_cuda_available` →
`is_native_cuda_available`.
- `QdpEngine.encode()` and `QuantumDataLoader` return `QdpTensor` on every
backend (use `.value` for the native object).
- `QdpBenchmark` default dtype is f32.
- `qumat_qdp._backend` → `qumat_qdp._native`.
## Checklist
- [x] Added or updated unit tests for all changes
- [x] Added or updated documentation for all changes
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
