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. device_id: Execution backend, required for optimization. shots: Shots per circuit evaluation, optimization only. optimizer_options: Classical optimizer configuration, optimization only and required there; NFT is valid only for a loss that is affine in the observables. 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 and optimization. observables: Named observables referenced by loss_expression, required for both modes and never empty. max_time: Optional pretraining wall-clock budget in seconds. seed: Optional pretraining random seed.

mode
enum<string>
required

Use optimization to minimize a loss expression on a device or simulator (requires loss_expression, observables, device_id and optimizer_options), 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.

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, required there and not accepted in pretraining mode; there is no default, and type must be stated. Either {'type': 'nft', 'maxiter': 100, 'maxfev': 200, 'reset_interval': 32} or {'type': 'scipy', 'method': 'cobyla', 'maxfev': 200, 'options': {}}. Choose nft only when loss_expression is affine in the observables ("energy", "2*a - b"): NFT models the loss as a sinusoid in each parameter, which a nonlinear loss ("a*b", "a/b", "(a - b)**2") violates, so an NFT run on one converges to a confident-looking wrong result instead of failing. Choose scipy for a nonlinear loss, and whenever unsure: COBYLA assumes no structure in the loss, so it is valid for every objective, at the cost of more circuit evaluations than NFT needs on an affine one.

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
CompressionOptions · object | null

State-compression parameters used when use_compression is true.

loss_expression
string | null

Loss formula minimized in both modes, written over the keys of observables, for example "(energy - target) ** 2", or just "energy" for a plain expectation-value objective. An expression that is not affine in the observables rules out the NFT optimizer in optimization mode; see optimizer_options.

Required string length: 1 - 1024
observables
Observables · object | null

Named observables referenced by loss_expression, each as [[pauli_strings], [coefficients]], for example {"energy": [["ZZ"], [1.0]]}. At least one entry is required in both modes.

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