qumat-qdp

GPU-accelerated quantum state encoding for Apache Mahout Qumat.

Installation

pip install qumat[qdp]

Requires one of:

• NVIDIA GPU (CUDA path via QdpEngine)
• AMD GPU with ROCm (AMD path via QdpEngine(backend="amd"))

Recommended environment setup:

python -m venv .venv
source .venv/bin/activate

# Install the GPU runtime for your platform first:
# - NVIDIA users: CUDA-compatible torch / triton
# - AMD users: ROCm-compatible torch / triton

uv sync --active --project qdp/qdp-python --group dev

Use --active so uv reuses the environment that already has the correct GPU runtime stack.

Usage

import qumat.qdp as qdp
import torch

# Initialize the unified QDP engine on GPU 0.
# Choose the backend explicitly.
engine = qdp.QdpEngine(device_id=0, backend="cuda")

# Encode data into quantum state
qtensor = engine.encode([1.0, 2.0, 3.0, 4.0], num_qubits=2, encoding_method="amplitude")

# Zero-copy transfer to PyTorch
tensor = torch.from_dlpack(qtensor)
print(tensor)  # Complex tensor on CUDA

AMD ROCm Usage

import qumat.qdp as qdp
import torch

# Unified AMD engine route
engine = qdp.QdpEngine(device_id=0, precision="float32", backend="amd")
qt = engine.encode(torch.randn(8, 4, device="cuda"), 2, "amplitude")
state = torch.from_dlpack(qt)
print(state.device, state.dtype)  # cuda:0, complex64

The public QdpEngine is a unified Python facade with explicit backend selection:

• backend="cuda" routes to the Rust _qdp.QdpEngine
• backend="amd" routes to the Triton AMD engine directly

See qdp/qdp-python/TRITON_AMD_BACKEND.md for Triton AMD setup and validation details.

Encoding Methods

Backend support boundary:

• CUDA (QdpEngine): amplitude, angle, basis, iqp, iqp-z, phase
  • phase is currently only reachable on the CUDA path via host inputs (Python list / NumPy / file / CPU torch tensor). The Python extension's CUDA-tensor validation does not yet allowlist phase; cuda-resident torch tensors must use .cpu() first when targeting phase. Tracked as a follow-up.
• AMD (QdpEngine(..., backend="amd")): amplitude, angle, basis, iqp, iqp-z, phase

Pipeline / loader dtype (Rust internals)

QuantumDataLoader and run_throughput_pipeline build a Rust PipelineConfig with an encoding plus a dtype (float32 vs float64). The prefetch thread can only keep an end-to-end float32 host batch for encodings whose GPU stack implements the batch f32 path (encode_batch_f32). Today that is amplitude only. Angle and basis still fall back to float64 for that loop until their batch f32 implementations exist. The eventual full matrix (e.g. angle/basis under supports_f32 once kernels are wired) is broader than what the pipeline uses today.

Input Sources

# Python list
qtensor = engine.encode([1.0, 2.0, 3.0, 4.0], 2, "amplitude")

# NumPy array
qtensor = engine.encode(np.array([[1, 2, 3, 4], [4, 3, 2, 1]]), 2, "amplitude")

# PyTorch tensor (CPU or CUDA)
qtensor = engine.encode(torch.tensor([1.0, 2.0, 3.0, 4.0]), 2, "amplitude")

# File formats
qtensor = engine.encode("data.parquet", 10, "amplitude")
qtensor = engine.encode("data.arrow", 10, "amplitude")
qtensor = engine.encode("data.npy", 10, "amplitude")
qtensor = engine.encode("data.pt", 10, "amplitude")

# Remote object storage URLs (requires building with remote-io feature)
qtensor = engine.encode("s3://my-bucket/data.parquet", 10, "amplitude")
qtensor = engine.encode("gs://my-bucket/data.parquet", 10, "amplitude")

Links

• Documentation
• GitHub
• Qumat Package

License

Apache License 2.0