Skip to main content
POST
Run Variational Workload

Authorizations

HAIQU_API_KEY
string
query
required

Body

application/json

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.

mode
enum<string>
required

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).

Available options:
optimization,
pretraining
experiment_id
string
required
circuit_id
string
required

Parameterized circuit to train, from a prior MCP response.

name
string | null
default:""
description
string | null
default:""
initial_parameters
number[] | null

Optional starting parameter values. Length must match the circuit's parameter count.

observable
Observable · object | null

Cost observable for optimization mode as [[pauli_strings], [coefficients]], for example [["ZZ", "XX"], [1.0, 0.5]].

device_id
string | null

Backend for optimization mode, from list_qpus_and_simulators.

shots
integer
default:1000

Shots per circuit evaluation in optimization mode.

optimizer_options
Optimizer Options · object | null

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.

options
Options · object | null

Backend options, including device credentials where the backend requires them.

use_mitigation
boolean
default:false

Apply error mitigation in optimization mode.

use_compression
boolean
default:false

Apply state compression in optimization mode.

compression_options
Compression Options · object | null

State-compression parameters used when use_compression is true.

loss_expression
string | null

Loss formula for pretraining mode, written over the keys of observables, for example "(energy - target) ** 2".

observables
Observables · object | null

Named observables for pretraining mode, each as [[pauli_strings], [coefficients]], for example {"energy": [["ZZ"], [1.0]]}.

max_time
number | null

Pretraining wall-clock budget in seconds.

seed
integer | null

Pretraining random seed.

Response

Successful Response

Represent context returned after a variational submission.

Attributes: job_id: Created job identifier. mode: Variational mode that was submitted. context: Submission summary and next polling step.

job_id
string
required
mode
string
required
context
string
required