Run Variational Workload
Train the parameters of a variational circuit, on a device or classically.
Use this tool for VQE-style workloads on a stored parameterized circuit. Set
mode to optimization to minimize an observable by running the circuit
on a backend, or to pretraining to fit the parameters classically before
spending any quantum time.
When to Use:
- Call this with
mode='optimization'when the user wants a ground-state energy, a minimized cost observable, or a VQE run. - Call this with
mode='pretraining'first when the circuit has many parameters, then feed the resulting parameters into an optimization run asinitial_parameters.
Constraints:
mode='optimization'requiresobservableanddevice_id;mode='pretraining'requiresloss_expressionandobservables. Fields belonging to the other mode are rejected with422rather than silently ignored.circuit_idmust reference a stored circuit with free parameters.- Both modes are asynchronous and billable. Poll with
get_job_results_and_status; stop a run withcancel_job. - Optimization runs many circuit evaluations, so wall-clock time and cost scale with the optimizer’s iteration budget, not with a single shot count.
Notes:
- Confirm the iteration budget with the user before submitting an optimization run against real hardware.
- Backend credentials go in
options, in the same formrun_circuits_on_qpu_or_simulatordocuments.
Args: user: Authenticated user resolved from the API key. data: Mode selector plus the fields required by that mode. db: Active database session.
Returns: The created job identifier, the mode, and the next polling step.
Raises:
HTTPException: Raised with 402 when the caller cannot submit billable
jobs, 404 when the experiment or circuit is unavailable, or 422
when the payload does not match the selected mode.
Authorizations
Body
Define payload for variational optimization and pretraining jobs.
One model covers both modes of the variational family. mode selects the
behavior and determines which of the remaining fields are required; the
unused fields for a mode are rejected with 422 rather than ignored.
Attributes:
mode: Which variational workload to run.
experiment_id: Parent experiment identifier.
circuit_id: Parameterized circuit to train.
name: Optional job name.
description: Optional job description.
initial_parameters: Optional starting parameter values.
observable: Cost observable, required for optimization.
device_id: Execution backend, required for optimization.
shots: Shots per circuit evaluation, optimization only.
optimizer_options: Classical optimizer configuration, optimization
only.
options: Backend or run options, forwarded as given.
use_mitigation: Whether to apply error mitigation, optimization only.
use_compression: Whether to apply state compression, optimization
only.
compression_options: Compression parameters, optimization only.
loss_expression: Loss formula, required for pretraining.
observables: Named observables referenced by loss_expression,
required for pretraining.
max_time: Optional pretraining wall-clock budget in seconds.
seed: Optional pretraining random seed.
Use optimization to minimize an observable on a device or simulator (requires observable and device_id), or pretraining to fit circuit parameters classically before any quantum execution (requires loss_expression and observables).
optimization, pretraining Parameterized circuit to train, from a prior MCP response.
Optional starting parameter values. Length must match the circuit's parameter count.
Cost observable for optimization mode as [[pauli_strings], [coefficients]], for example [["ZZ", "XX"], [1.0, 0.5]].
Backend for optimization mode, from list_qpus_and_simulators.
Shots per circuit evaluation in optimization mode.
Classical optimizer for optimization mode. Either {'type': 'nft', 'maxiter': 100, 'maxfev': 200, 'reset_interval': 32} or {'type': 'scipy', 'method': 'cobyla', 'maxfev': 200, 'options': {}}. Defaults to NFT with library defaults when omitted.
Backend options, including device credentials where the backend requires them.
Apply error mitigation in optimization mode.
Apply state compression in optimization mode.
State-compression parameters used when use_compression is true.
Loss formula for pretraining mode, written over the keys of observables, for example "(energy - target) ** 2".
Named observables for pretraining mode, each as [[pauli_strings], [coefficients]], for example {"energy": [["ZZ"], [1.0]]}.
Pretraining wall-clock budget in seconds.
Pretraining random seed.