[400Ping]

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
• New feature
• Refactoring
• Documentation
• 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 Add pure-PyTorch reference implementations #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 ([Feature][QDP] Add AMD GPU support via Triton backend #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 (qumat_qdp: intersect GPU compute capability with PyTorch's arch list #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 [QDP] Close AMD-vs-CUDA encoder parity: add iqp, iqp-z, phase #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

• Added or updated unit tests for all changes
• Added or updated documentation for all changes

[ryankert01]

lg, I thought it probably be okay.