This is an automated email from the ASF dual-hosted git repository.
guanmingchiu pushed a commit to branch v0.5-stable
in repository https://gitbox.apache.org/repos/asf/mahout.git
The following commit(s) were added to refs/heads/v0.5-stable by this push:
new eba451199 [v0.5-stable] update qdp readme to make it up-to-date (#980)
(#985)
eba451199 is described below
commit eba45119954f4675ea3bea566d2a7a86b65bdc27
Author: Guan-Ming (Wesley) Chiu <[email protected]>
AuthorDate: Thu Jan 29 21:23:55 2026 +0800
[v0.5-stable] update qdp readme to make it up-to-date (#980) (#985)
(cherry picked from commit 15037cf4df80b7e208020f37057198e023f1b656)
Co-authored-by: Ryan Huang <[email protected]>
---
qdp/qdp-python/README.md | 96 ++++++++++++++++++++++++------------------------
1 file changed, 47 insertions(+), 49 deletions(-)
diff --git a/qdp/qdp-python/README.md b/qdp/qdp-python/README.md
index 3558c6f23..6f47b9fea 100644
--- a/qdp/qdp-python/README.md
+++ b/qdp/qdp-python/README.md
@@ -1,68 +1,66 @@
-# qdp-python
+# qumat-qdp
-PyO3 Python bindings for Apache Mahout QDP.
+GPU-accelerated quantum state encoding for [Apache Mahout
Qumat](https://github.com/apache/mahout).
+
+## Installation
+
+```bash
+pip install qumat[qdp]
+```
+
+Requires CUDA-capable GPU.
## Usage
```python
-from _qdp import QdpEngine
-
-# Initialize on GPU 0 (defaults to float32 output)
-engine = QdpEngine(0)
+import qumat.qdp as qdp
+import torch
-# Optional: request float64 output if you need higher precision
-# engine = QdpEngine(0, precision="float64")
+# Initialize engine on GPU 0
+engine = qdp.QdpEngine(device_id=0)
-# Encode data from Python list
-data = [0.5, 0.5, 0.5, 0.5]
-qtensor = engine.encode(data, num_qubits=2, encoding_method="amplitude")
+# Encode data into quantum state
+qtensor = engine.encode([1.0, 2.0, 3.0, 4.0], num_qubits=2,
encoding_method="amplitude")
-# Or encode from file formats
-tensor_parquet = engine.encode("data.parquet", 10, "amplitude")
-tensor_arrow = engine.encode("data.arrow", 10, "amplitude")
+# Zero-copy transfer to PyTorch
+tensor = torch.from_dlpack(qtensor)
+print(tensor) # Complex tensor on CUDA
```
-## Build from source
-```bash
-# add a uv python 3.11 environment
-uv venv -p python3.11
-source .venv/bin/activate
-```
-```bash
-uv sync --group dev
-uv run maturin develop
-```
+## Encoding Methods
-## Encoding methods
+| Method | Description |
+|--------|-------------|
+| `amplitude` | Normalize input as quantum amplitudes |
+| `angle` | Map values to rotation angles (one per qubit) |
+| `basis` | Encode integer as computational basis state |
+| `iqp` | IQP-style encoding with entanglement |
-- `"amplitude"` - Amplitude encoding
-- `"angle"` - Angle encoding
-- `"basis"` - Basis encoding
+## Input Sources
-## File format support
+```python
+# Python list
+qtensor = engine.encode([1.0, 2.0, 3.0, 4.0], 2, "amplitude")
-- **Parquet** - `.parquet` files
-- **Arrow IPC** - `.arrow` or `.feather` files
-- **NumPy** - `.npy` files
-- **PyTorch** - `.pt` or `.pth` files
-- **TensorFlow** - `.pb` files (TensorProto format)
+# NumPy array
+qtensor = engine.encode(np.array([[1, 2, 3, 4], [4, 3, 2, 1]]), 2, "amplitude")
-## Adding new bindings
+# PyTorch tensor (CPU or CUDA)
+qtensor = engine.encode(torch.tensor([1.0, 2.0, 3.0, 4.0]), 2, "amplitude")
-1. Add method to `#[pymethods]` in `src/lib.rs`:
-```rust
-#[pymethods]
-impl QdpEngine {
- fn my_method(&self, arg: f64) -> PyResult<String> {
- Ok(format!("Result: {}", arg))
- }
-}
+# 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")
```
-2. Rebuild: `uv run maturin develop`
+## Links
-3. Use in Python:
-```python
-engine = QdpEngine(0)
-result = engine.my_method(42.0)
-```
+- [Documentation](https://mahout.apache.org/)
+- [GitHub](https://github.com/apache/mahout)
+- [Qumat Package](https://pypi.org/project/qumat/)
+
+## License
+
+Apache License 2.0
