In-language variational training
Define a bounded train block beside the quantum model, run deterministic local optimization, and inspect final parameters, cost history, convergence, output, and trace evidence.
Train block contract
A train block belongs inside fn main and declares exactly one objective, optimizer, and step budget. The parser, formatter, language service, CLI, and runtime share the same first-class AST contract.
Runnable train block
1module variational_demo;2 3param theta: Angle = 0.4;4 5fn main() {6 let q: QReg<1> = qreg[1];7 Ry(q[0], theta);8 let cost = expect Z(q[0]);9 train {10 objective: minimize cost;11 optimizer: adam(lr = 0.08);12 steps: 24;13 }14 return cost;15}Validation, early stopping, scheduling, and checkpoints
NM-RFC-0004 freezes deterministic validation, early stopping, step scheduling, and in-memory best-parameter checkpoints behind the experimental.qmlTrainingControls feature flag. The directive order is not semantic; every control is bounded and requires a supervised embedded dataset.
- Maximum train steps
- 100
- Maximum validation cadence
- 100
- Maximum early-stop patience
- 100
- Maximum circuit evaluations
- 20,000
Runtime-experimental training controls
1module qml_training_controls;2param theta: Angle = 0.1;3 4fn main() {5 let q: QReg<2> = qreg[2];6 encode(sample_row(), q, method: "reupload");7 Ry(q[1], theta);8 let cost = expect Z(q[1]);9 10 train {11 objective: minimize cost;12 optimizer: adam(lr = 0.2);13 steps: 40;14 loss: cross_entropy;15 dataset: xor_2d;16 validation: split = validation, every = 5;17 early_stopping: metric = validation_loss, patience = 3, min_delta = 0.001;18 scheduler: step(every = 10, factor = 0.5, min_lr = 0.01);19 checkpoint: best(metric = validation_loss);20 }21 return cost;22}Explicit negotiation and fail-closed errors
Execution is available only with explicit feature negotiation and returns bounded validation, learning-rate, early-stop, and checkpoint evidence. Invalid or non-finite runtime state fails with NM-QML-109; control intent is never silently discarded. Stable N/M 0.1 programs are unchanged when the feature flag is absent.
nm run main.nm --experimental-qml-training-controls --jsoninitializationOptions.nm.experimental.qmlTrainingControls = truenm.experimental.qmlTrainingControls = trueNM-PARSE-060NM-PARSE-061NM-QML-108NM-QML-109Defaults and results
Automatic gradients use an adjoint sweep for eligible noiseless Rx/Ry/Rz/RXX/RYY/RZZ/P/GPhase/CRy/CRz/CP circuits. Angle expressions support +, -, *, / and parentheses with scalar or vector parameters; the chain rule accumulates shared contributions. On flat circuits, arithmetic constants propagate derivatives into gate angles and observable coefficients, including identity terms. Loops, circuit expansion, modifiers and dependent indices remain unsupported with dependent constants; function calls are unsupported. Parameter-shift fallback requires at most one direct supported Pauli rotation per parameter and rejects angle expressions and controlled gates. Results report costs, final parameters, the method and step history before rerunning the optimized model.
Preview limits
Bounded local training supports gd, momentum, Adam, deterministic SPSA, or preview QNG with 1-100 steps. Supervised train blocks iterate every row of the embedded XOR, circles, spiral, three-feature blobs, or parity datasets and report mse/cross_entropy/hinge loss plus accuracy history. QNG uses a bounded fidelity-diagonal approximation rather than a full quantum geometric tensor.
Stable training diagnostics
NM-QML-101NM-QML-102NM-QML-103NM-QML-104NM-QML-105These codes cover placement, required or duplicate directives, objective syntax, numeric ranges, and optimizer support. The diagnostics explorer provides localized messages and fixes.
OpenQASM has no portable training-block equivalent. Export strips the train directive and marks that boundary explicitly; the N/M sidecar preserves the train contract. Export a trained model only after applying the returned final parameters.