[PR] [Qumat] Add a minimal QMLTrainer for parameterized circuits (#1409) [mahout]

["andrewmusselman (via GitHub)" <gi...@apache.org>]

andrewmusselman opened a new pull request, #1546:
URL: https://github.com/apache/mahout/pull/1546

   ### Purpose of PR
   Proposes a concrete shape for #1409: a small trainer modelled on the HuggingFace split of model / `TrainingArguments` / training loop. Data is angle-encoded with `RY(2x)`, which prepares the same state as QDP's "angle" encoding, so a future QDP path stays numerically interchangeable. QDP is not a runtime dependency (it is GPU-only).
   
   ### Related Issues or PRs
   Part of #1409
   Depends on the #749 PR; review only the last 2 commits until that merges.
   
   ### Changes Made
   - New `qumat/trainer.py`:
     - `QMLModel` runtime-checkable Protocol (`num_qubits`, `param_names`, `build_circuit`, `init_params`, `forward`); the circuit is built once and each sample only rebinds values.
     - `AngleEncodedClassifier` reference model: `RY(2*x_k)` encoding (or `encoding="rotation"`), layers of trainable RY plus a CNOT chain, `<Z>` readout on the last qubit.
     - `TrainingArguments` (epochs, learning_rate, batch_size, optimizer `adam`/`gradient_descent`, seed, log_every, shuffle, gradient, backend_config).
     - `QMLTrainer` with `train()`, `evaluate()`, `predict()`, per-epoch history, `qumat.trainer` logger and `TrainerCallback` hooks (`should_stop` for early stopping).
   - Gradients use `parameter_shift_gradient` on the model output and the chain rule for the loss, so non-linear losses such as MSE stay correct; optimizer steps reuse `qumat.optimize`.
   - `testing/qumat/test_trainer.py`, including an end-to-end run: 2 qubits, 16-sample XOR-like data, 5 epochs; train/eval loss decrease and accuracy >= 0.75. Encoding checked against `qumat_qdp.torch_ref.angle_encode` on CPU.
   - Docs: `docs/qumat/trainer.md`; links in `docs/qumat/index.md` and `website/sidebars.ts`; `qumat.trainer` in `docs/api/qumat.yml`.
   
   ### Testing
   - With the #749 commits underneath: `testing/qumat` 669 passed, 0 failed, 0 skipped (main: 589). The end-to-end test takes about 4 s.
   - ruff, ruff format and `ty` clean (no new diagnostics vs main).
   - Not verified: any QDP GPU path, the Docusaurus build, larger datasets or more than a few qubits (the per-sample loop is slow for big data).
   
   ### Merging
   This branch (with #749 underneath) adds entries to `docs/advanced/index.md`, `docs/api/qumat.yml`, `qumat/__init__.py` exports and `website/sidebars.ts`, which conflict textually with the #456/#458 PR. A rebased "after #1409" version of #456/#458 exists.
   
   🤖 Generated with [Claude Code](https://claude.com/claude-code)
   
   https://claude.ai/code/session_01GuXmXRXdNF43h2FoQcNAZb
   


-- 
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: commits-unsubscribe@mahout.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org