You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@mahout.apache.org by "400Ping (via GitHub)" <gi...@apache.org> on 2026/01/21 18:27:20 UTC
[PR] [Docs] Add API Reference [mahout]
400Ping opened a new pull request, #902:
URL: https://github.com/apache/mahout/pull/902
### Purpose of PR
As title
### Related Issues or PRs
<!-- Add links to related issues or PRs. -->
<!-- - Closes #123 -->
<!-- - Related to #123 -->
Closes #858
### Changes Made
<!-- Please mark one with an "x" -->
- [ ] Bug fix
- [ ] New feature
- [ ] Refactoring
- [x] Documentation
- [ ] Test
- [ ] CI/CD pipeline
- [ ] Other
### Breaking Changes
<!-- Does this PR introduce a breaking change? -->
- [ ] Yes
- [x] No
### Checklist
<!-- Please mark each item with an "x" when complete -->
<!-- If not all items are complete, please open this as a **Draft PR**.
Once all requirements are met, mark as ready for review. -->
- [ ] Added or updated unit tests for all changes
- [ ] Added or updated documentation for all changes
- [ ] Successfully built and ran all unit tests or manual tests locally
- [ ] PR title follows "MAHOUT-XXX: Brief Description" format (if related to an issue)
- [ ] Code follows ASF guidelines
--
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: dev-unsubscribe@mahout.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add API Reference [mahout]
Posted by "rich7420 (via GitHub)" <gi...@apache.org>.
rich7420 commented on PR #902:
URL: https://github.com/apache/mahout/pull/902#issuecomment-3789017625
thanks for the update , overall LGTM
--
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: dev-unsubscribe@mahout.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add API Reference [mahout]
Posted by "guan404ming (via GitHub)" <gi...@apache.org>.
guan404ming merged PR #902:
URL: https://github.com/apache/mahout/pull/902
--
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: dev-unsubscribe@mahout.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add API Reference [mahout]
Posted by "400Ping (via GitHub)" <gi...@apache.org>.
400Ping commented on code in PR #902:
URL: https://github.com/apache/mahout/pull/902#discussion_r2721765501
##########
website/qumat/qdp/api/index.md:
##########
@@ -5,4 +5,130 @@ title: API Reference - QDP
# API Reference
-<!-- TODO: Add API reference documentation for QDP -->
+Mahout QDP (Quantum Data Plane) provides GPU-accelerated quantum state encoding.
+It writes classical data directly into GPU memory and returns a DLPack-compatible
+handle for zero-copy integration with downstream frameworks.
+
+## Quickstart
Review Comment:
ok
--
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: dev-unsubscribe@mahout.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add API Reference [mahout]
Posted by "ryankert01 (via GitHub)" <gi...@apache.org>.
ryankert01 commented on code in PR #902:
URL: https://github.com/apache/mahout/pull/902#discussion_r2724026231
##########
website/qumat/qdp/api/index.md:
##########
@@ -5,4 +5,130 @@ title: API Reference - QDP
# API Reference
-<!-- TODO: Add API reference documentation for QDP -->
+Mahout QDP (Quantum Data Plane) provides GPU-accelerated quantum state encoding.
+It writes classical data directly into GPU memory and returns a DLPack-compatible
+handle for zero-copy integration with downstream frameworks.
+
+## Quickstart
Review Comment:
@400Ping can you send a pr of that example? (w/ a local run snippet) Thanks!
--
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: dev-unsubscribe@mahout.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add API Reference [mahout]
Posted by "400Ping (via GitHub)" <gi...@apache.org>.
400Ping commented on code in PR #902:
URL: https://github.com/apache/mahout/pull/902#discussion_r2722210335
##########
website/qumat/qdp/api/index.md:
##########
@@ -5,4 +5,130 @@ title: API Reference - QDP
# API Reference
-<!-- TODO: Add API reference documentation for QDP -->
+Mahout QDP (Quantum Data Plane) provides GPU-accelerated quantum state encoding.
+It writes classical data directly into GPU memory and returns a DLPack-compatible
+handle for zero-copy integration with downstream frameworks.
+
+## Quickstart
Review Comment:
done
--
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: dev-unsubscribe@mahout.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add API Reference [mahout]
Posted by "guan404ming (via GitHub)" <gi...@apache.org>.
guan404ming commented on code in PR #902:
URL: https://github.com/apache/mahout/pull/902#discussion_r2721704729
##########
website/qumat/qdp/api/index.md:
##########
@@ -5,4 +5,130 @@ title: API Reference - QDP
# API Reference
-<!-- TODO: Add API reference documentation for QDP -->
+Mahout QDP (Quantum Data Plane) provides GPU-accelerated quantum state encoding.
+It writes classical data directly into GPU memory and returns a DLPack-compatible
+handle for zero-copy integration with downstream frameworks.
+
+## Quickstart
Review Comment:
I think this part appear in lots of place. Should we not have this here?
--
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: dev-unsubscribe@mahout.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add API Reference [mahout]
Posted by "guan404ming (via GitHub)" <gi...@apache.org>.
guan404ming commented on code in PR #902:
URL: https://github.com/apache/mahout/pull/902#discussion_r2721761367
##########
website/qumat/qdp/api/index.md:
##########
@@ -5,4 +5,130 @@ title: API Reference - QDP
# API Reference
-<!-- TODO: Add API reference documentation for QDP -->
+Mahout QDP (Quantum Data Plane) provides GPU-accelerated quantum state encoding.
+It writes classical data directly into GPU memory and returns a DLPack-compatible
+handle for zero-copy integration with downstream frameworks.
+
+## Quickstart
Review Comment:
I think we could make it in example, wdyt?
--
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: dev-unsubscribe@mahout.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add API Reference [mahout]
Posted by "ryankert01 (via GitHub)" <gi...@apache.org>.
ryankert01 commented on PR #902:
URL: https://github.com/apache/mahout/pull/902#issuecomment-3797421259
Please help rebase!
--
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: dev-unsubscribe@mahout.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add API Reference [mahout]
Posted by "400Ping (via GitHub)" <gi...@apache.org>.
400Ping commented on PR #902:
URL: https://github.com/apache/mahout/pull/902#issuecomment-3783018539
cc @guan404ming @rich7420 @ryankert01
--
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: dev-unsubscribe@mahout.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add API Reference [mahout]
Posted by "ryankert01 (via GitHub)" <gi...@apache.org>.
ryankert01 commented on PR #902:
URL: https://github.com/apache/mahout/pull/902#issuecomment-3797866565
Wait for it go green
--
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: dev-unsubscribe@mahout.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add API Reference [mahout]
Posted by "ryankert01 (via GitHub)" <gi...@apache.org>.
ryankert01 commented on code in PR #902:
URL: https://github.com/apache/mahout/pull/902#discussion_r2724026231
##########
website/qumat/qdp/api/index.md:
##########
@@ -5,4 +5,130 @@ title: API Reference - QDP
# API Reference
-<!-- TODO: Add API reference documentation for QDP -->
+Mahout QDP (Quantum Data Plane) provides GPU-accelerated quantum state encoding.
+It writes classical data directly into GPU memory and returns a DLPack-compatible
+handle for zero-copy integration with downstream frameworks.
+
+## Quickstart
Review Comment:
@400Ping can you send a pr of that example?
--
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: dev-unsubscribe@mahout.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add API Reference [mahout]
Posted by "rich7420 (via GitHub)" <gi...@apache.org>.
rich7420 commented on code in PR #902:
URL: https://github.com/apache/mahout/pull/902#discussion_r2719944796
##########
website/qumat/qdp/api/index.md:
##########
@@ -5,4 +5,131 @@ title: API Reference - QDP
# API Reference
-<!-- TODO: Add API reference documentation for QDP -->
+Mahout QDP (Quantum Data Plane) provides GPU-accelerated quantum state encoding.
+It writes classical data directly into GPU memory and returns a DLPack-compatible
+handle for zero-copy integration with downstream frameworks.
+
+## Quickstart
+
+```python
+import qumat.qdp as qdp
+import torch
+
+engine = qdp.QdpEngine(device_id=0, precision="float32")
+qtensor = engine.encode([0.1, 0.2, 0.3, 0.4], num_qubits=2, encoding_method="amplitude")
+tensor = torch.utils.dlpack.from_dlpack(qtensor) # single-use, zero-copy
Review Comment:
Both work, but I think `torch.from_dlpack()` is cleaner and more commonly used.
--
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: dev-unsubscribe@mahout.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add API Reference [mahout]
Posted by "400Ping (via GitHub)" <gi...@apache.org>.
400Ping commented on code in PR #902:
URL: https://github.com/apache/mahout/pull/902#discussion_r2724363838
##########
website/qumat/qdp/api/index.md:
##########
@@ -5,4 +5,130 @@ title: API Reference - QDP
# API Reference
-<!-- TODO: Add API reference documentation for QDP -->
+Mahout QDP (Quantum Data Plane) provides GPU-accelerated quantum state encoding.
+It writes classical data directly into GPU memory and returns a DLPack-compatible
+handle for zero-copy integration with downstream frameworks.
+
+## Quickstart
Review Comment:
> @400Ping can you send a pr of that example? (w/ a local run snippet) Thanks!
not very sure what you mean?
--
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: dev-unsubscribe@mahout.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add API Reference [mahout]
Posted by "400Ping (via GitHub)" <gi...@apache.org>.
400Ping commented on PR #902:
URL: https://github.com/apache/mahout/pull/902#issuecomment-3797970341
cc @guan404ming @ryankert01 for merge
--
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: dev-unsubscribe@mahout.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add API Reference [mahout]
Posted by "ryankert01 (via GitHub)" <gi...@apache.org>.
ryankert01 commented on code in PR #902:
URL: https://github.com/apache/mahout/pull/902#discussion_r2724026231
##########
website/qumat/qdp/api/index.md:
##########
@@ -5,4 +5,130 @@ title: API Reference - QDP
# API Reference
-<!-- TODO: Add API reference documentation for QDP -->
+Mahout QDP (Quantum Data Plane) provides GPU-accelerated quantum state encoding.
+It writes classical data directly into GPU memory and returns a DLPack-compatible
+handle for zero-copy integration with downstream frameworks.
+
+## Quickstart
Review Comment:
@400Ping can you send a pr of that example? (w/ a local run snippet)
--
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: dev-unsubscribe@mahout.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add API Reference [mahout]
Posted by "guan404ming (via GitHub)" <gi...@apache.org>.
guan404ming commented on code in PR #902:
URL: https://github.com/apache/mahout/pull/902#discussion_r2724320910
##########
website/qumat/qdp/api/index.md:
##########
@@ -5,4 +5,130 @@ title: API Reference - QDP
# API Reference
-<!-- TODO: Add API reference documentation for QDP -->
+Mahout QDP (Quantum Data Plane) provides GPU-accelerated quantum state encoding.
+It writes classical data directly into GPU memory and returns a DLPack-compatible
+handle for zero-copy integration with downstream frameworks.
+
+## Quickstart
Review Comment:
Hi @400Ping I means the quick start part should be removed , sorry for the confusion.
--
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: dev-unsubscribe@mahout.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add API Reference [mahout]
Posted by "viiccwen (via GitHub)" <gi...@apache.org>.
viiccwen commented on code in PR #902:
URL: https://github.com/apache/mahout/pull/902#discussion_r2725621396
##########
website/qumat/qdp/api/index.md:
##########
@@ -5,4 +5,117 @@ title: API Reference - QDP
# API Reference
-<!-- TODO: Add API reference documentation for QDP -->
+Mahout QDP (Quantum Data Plane) provides GPU-accelerated quantum state encoding.
+It writes classical data directly into GPU memory and returns a DLPack-compatible
+handle for zero-copy integration with downstream frameworks.
+
+## Module: `qumat.qdp`
+
+Prefer importing from `qumat.qdp`; the native extension is `_qdp`.
+
+```python
+import qumat.qdp as qdp
+# or: from _qdp import QdpEngine, QuantumTensor
+```
+
+## Class: `QdpEngine`
+
+### `QdpEngine(device_id=0, precision="float32")`
+
+Create a GPU encoder instance.
+
+**Parameters**
+- `device_id` (int): CUDA device ID, default `0`.
+- `precision` (str): `"float32"` or `"float64"`.
+
+**Raises**
+- `RuntimeError`: Initialization failure or unsupported precision.
+
+### `encode(data, num_qubits, encoding_method="amplitude") -> QuantumTensor`
+
+Encode classical input into a quantum state and return a DLPack tensor on GPU.
+
+**Parameters**
+- `data`: Supported inputs
+ - `list[float]`
+ - `numpy.ndarray` (1D/2D, dtype=float64, C-contiguous)
+ - `torch.Tensor` (CPU, float64, contiguous)
+ - `str` / `pathlib.Path` file path
+ - `.parquet`, `.arrow` / `.feather`, `.npy`, `.pt` / `.pth`, `.pb`
+- `num_qubits` (int): Number of qubits, range 1–30.
+- `encoding_method` (str): `"amplitude" | "angle" | "basis"` (lowercase).
+
+**Returns**
+- `QuantumTensor` with 2D shape:
+ - single sample: `[1, 2^num_qubits]`
+ - batch: `[batch_size, 2^num_qubits]`
+
+**Notes**
+- Output dtype is `complex64` (`precision="float32"`) or `complex128` (`precision="float64"`).
+- Parquet streaming currently supports `"amplitude"` and `"basis"`.
+
+**Raises**
+- `RuntimeError`: Invalid inputs, shapes, dtypes, or unsupported formats.
+
+### `encode_from_tensorflow(path, num_qubits, encoding_method="amplitude") -> QuantumTensor`
+
+Encode directly from a TensorFlow TensorProto file (`.pb`).
+
+## Class: `QuantumTensor`
+
+DLPack wrapper for GPU-resident quantum states.
+
+### `__dlpack__(stream=None)`
+
+Return a DLPack PyCapsule. This can be consumed only once.
+
+### `__dlpack_device__()`
+
+Return `(device_type, device_id)`; CUDA devices report `(2, gpu_id)`.
+
+**Ownership & Lifetime**
+- If not consumed, memory is freed when the object is dropped.
+- If consumed, ownership transfers to the consumer (e.g., PyTorch).
+
+## Encoding Methods
+
+### `amplitude`
+
+- Input length `<= 2^num_qubits`; remaining entries are zero-padded.
+- L2 normalization is applied.
+- Zero vectors / NaN / Inf raise errors.
+
+### `angle`
+
+- Each sample must provide exactly `num_qubits` angles.
+- NaN / Inf raise errors.
+
+### `basis`
+
+- Each sample provides one integer index in `[0, 2^num_qubits)`.
+
+## Supported File Formats
+
+- **Parquet**: `.parquet`
+- **Arrow IPC**: `.arrow`, `.feather`
+- **NumPy**: `.npy`
+- **PyTorch**: `.pt`, `.pth`
+- **TensorFlow**: `.pb` (TensorProto)
+
+## Common Errors
+
+- `num_qubits` out of range.
+- Input length exceeds `2^num_qubits`.
+- Non-`float64` NumPy/Torch inputs.
+- Torch tensors not on CPU or not contiguous.
Review Comment:
yes but no, currently supports `"amplitude"` method.
Support for other encoding methods (angle, basis, iqp, iqp-z) is planned.
##########
website/qumat/qdp/api/index.md:
##########
@@ -5,4 +5,117 @@ title: API Reference - QDP
# API Reference
-<!-- TODO: Add API reference documentation for QDP -->
+Mahout QDP (Quantum Data Plane) provides GPU-accelerated quantum state encoding.
+It writes classical data directly into GPU memory and returns a DLPack-compatible
+handle for zero-copy integration with downstream frameworks.
+
+## Module: `qumat.qdp`
+
+Prefer importing from `qumat.qdp`; the native extension is `_qdp`.
+
+```python
+import qumat.qdp as qdp
+# or: from _qdp import QdpEngine, QuantumTensor
+```
+
+## Class: `QdpEngine`
+
+### `QdpEngine(device_id=0, precision="float32")`
+
+Create a GPU encoder instance.
+
+**Parameters**
+- `device_id` (int): CUDA device ID, default `0`.
+- `precision` (str): `"float32"` or `"float64"`.
+
+**Raises**
+- `RuntimeError`: Initialization failure or unsupported precision.
+
+### `encode(data, num_qubits, encoding_method="amplitude") -> QuantumTensor`
+
+Encode classical input into a quantum state and return a DLPack tensor on GPU.
+
+**Parameters**
+- `data`: Supported inputs
+ - `list[float]`
+ - `numpy.ndarray` (1D/2D, dtype=float64, C-contiguous)
+ - `torch.Tensor` (CPU, float64, contiguous)
+ - `str` / `pathlib.Path` file path
+ - `.parquet`, `.arrow` / `.feather`, `.npy`, `.pt` / `.pth`, `.pb`
+- `num_qubits` (int): Number of qubits, range 1–30.
+- `encoding_method` (str): `"amplitude" | "angle" | "basis"` (lowercase).
+
+**Returns**
+- `QuantumTensor` with 2D shape:
+ - single sample: `[1, 2^num_qubits]`
+ - batch: `[batch_size, 2^num_qubits]`
+
+**Notes**
+- Output dtype is `complex64` (`precision="float32"`) or `complex128` (`precision="float64"`).
+- Parquet streaming currently supports `"amplitude"` and `"basis"`.
+
+**Raises**
+- `RuntimeError`: Invalid inputs, shapes, dtypes, or unsupported formats.
+
+### `encode_from_tensorflow(path, num_qubits, encoding_method="amplitude") -> QuantumTensor`
+
+Encode directly from a TensorFlow TensorProto file (`.pb`).
+
+## Class: `QuantumTensor`
+
+DLPack wrapper for GPU-resident quantum states.
+
+### `__dlpack__(stream=None)`
+
+Return a DLPack PyCapsule. This can be consumed only once.
+
+### `__dlpack_device__()`
+
+Return `(device_type, device_id)`; CUDA devices report `(2, gpu_id)`.
+
+**Ownership & Lifetime**
+- If not consumed, memory is freed when the object is dropped.
+- If consumed, ownership transfers to the consumer (e.g., PyTorch).
+
+## Encoding Methods
+
+### `amplitude`
+
+- Input length `<= 2^num_qubits`; remaining entries are zero-padded.
+- L2 normalization is applied.
+- Zero vectors / NaN / Inf raise errors.
+
+### `angle`
+
+- Each sample must provide exactly `num_qubits` angles.
+- NaN / Inf raise errors.
+
+### `basis`
+
+- Each sample provides one integer index in `[0, 2^num_qubits)`.
Review Comment:
could u also add `iqp` / `iqp-z`?
##########
website/qumat/qdp/api/index.md:
##########
@@ -5,4 +5,117 @@ title: API Reference - QDP
# API Reference
-<!-- TODO: Add API reference documentation for QDP -->
+Mahout QDP (Quantum Data Plane) provides GPU-accelerated quantum state encoding.
+It writes classical data directly into GPU memory and returns a DLPack-compatible
+handle for zero-copy integration with downstream frameworks.
+
+## Module: `qumat.qdp`
+
+Prefer importing from `qumat.qdp`; the native extension is `_qdp`.
+
+```python
+import qumat.qdp as qdp
+# or: from _qdp import QdpEngine, QuantumTensor
+```
+
+## Class: `QdpEngine`
+
+### `QdpEngine(device_id=0, precision="float32")`
+
+Create a GPU encoder instance.
+
+**Parameters**
+- `device_id` (int): CUDA device ID, default `0`.
+- `precision` (str): `"float32"` or `"float64"`.
+
+**Raises**
+- `RuntimeError`: Initialization failure or unsupported precision.
+
+### `encode(data, num_qubits, encoding_method="amplitude") -> QuantumTensor`
+
+Encode classical input into a quantum state and return a DLPack tensor on GPU.
+
+**Parameters**
+- `data`: Supported inputs
+ - `list[float]`
+ - `numpy.ndarray` (1D/2D, dtype=float64, C-contiguous)
+ - `torch.Tensor` (CPU, float64, contiguous)
+ - `str` / `pathlib.Path` file path
+ - `.parquet`, `.arrow` / `.feather`, `.npy`, `.pt` / `.pth`, `.pb`
+- `num_qubits` (int): Number of qubits, range 1–30.
+- `encoding_method` (str): `"amplitude" | "angle" | "basis"` (lowercase).
+
+**Returns**
+- `QuantumTensor` with 2D shape:
+ - single sample: `[1, 2^num_qubits]`
+ - batch: `[batch_size, 2^num_qubits]`
+
+**Notes**
+- Output dtype is `complex64` (`precision="float32"`) or `complex128` (`precision="float64"`).
+- Parquet streaming currently supports `"amplitude"` and `"basis"`.
Review Comment:
and `angle`
##########
website/qumat/qdp/api/index.md:
##########
@@ -5,4 +5,117 @@ title: API Reference - QDP
# API Reference
-<!-- TODO: Add API reference documentation for QDP -->
+Mahout QDP (Quantum Data Plane) provides GPU-accelerated quantum state encoding.
+It writes classical data directly into GPU memory and returns a DLPack-compatible
+handle for zero-copy integration with downstream frameworks.
+
+## Module: `qumat.qdp`
+
+Prefer importing from `qumat.qdp`; the native extension is `_qdp`.
+
+```python
+import qumat.qdp as qdp
+# or: from _qdp import QdpEngine, QuantumTensor
+```
+
+## Class: `QdpEngine`
+
+### `QdpEngine(device_id=0, precision="float32")`
+
+Create a GPU encoder instance.
+
+**Parameters**
+- `device_id` (int): CUDA device ID, default `0`.
+- `precision` (str): `"float32"` or `"float64"`.
+
+**Raises**
+- `RuntimeError`: Initialization failure or unsupported precision.
+
+### `encode(data, num_qubits, encoding_method="amplitude") -> QuantumTensor`
+
+Encode classical input into a quantum state and return a DLPack tensor on GPU.
+
+**Parameters**
+- `data`: Supported inputs
+ - `list[float]`
+ - `numpy.ndarray` (1D/2D, dtype=float64, C-contiguous)
+ - `torch.Tensor` (CPU, float64, contiguous)
+ - `str` / `pathlib.Path` file path
+ - `.parquet`, `.arrow` / `.feather`, `.npy`, `.pt` / `.pth`, `.pb`
+- `num_qubits` (int): Number of qubits, range 1–30.
+- `encoding_method` (str): `"amplitude" | "angle" | "basis"` (lowercase).
Review Comment:
we also support `"iqp" | "iqp-z"` few days ago.
--
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: dev-unsubscribe@mahout.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add API Reference [mahout]
Posted by "400Ping (via GitHub)" <gi...@apache.org>.
400Ping commented on code in PR #902:
URL: https://github.com/apache/mahout/pull/902#discussion_r2721749406
##########
website/qumat/qdp/api/index.md:
##########
@@ -5,4 +5,130 @@ title: API Reference - QDP
# API Reference
-<!-- TODO: Add API reference documentation for QDP -->
+Mahout QDP (Quantum Data Plane) provides GPU-accelerated quantum state encoding.
+It writes classical data directly into GPU memory and returns a DLPack-compatible
+handle for zero-copy integration with downstream frameworks.
+
+## Quickstart
Review Comment:
should I remove this part?
--
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: dev-unsubscribe@mahout.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [Docs] Add API Reference [mahout]
Posted by "400Ping (via GitHub)" <gi...@apache.org>.
400Ping commented on code in PR #902:
URL: https://github.com/apache/mahout/pull/902#discussion_r2720053029
##########
website/qumat/qdp/api/index.md:
##########
@@ -5,4 +5,131 @@ title: API Reference - QDP
# API Reference
-<!-- TODO: Add API reference documentation for QDP -->
+Mahout QDP (Quantum Data Plane) provides GPU-accelerated quantum state encoding.
+It writes classical data directly into GPU memory and returns a DLPack-compatible
+handle for zero-copy integration with downstream frameworks.
+
+## Quickstart
+
+```python
+import qumat.qdp as qdp
+import torch
+
+engine = qdp.QdpEngine(device_id=0, precision="float32")
+qtensor = engine.encode([0.1, 0.2, 0.3, 0.4], num_qubits=2, encoding_method="amplitude")
+tensor = torch.utils.dlpack.from_dlpack(qtensor) # single-use, zero-copy
Review Comment:
done
--
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: dev-unsubscribe@mahout.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org