Run Circuits On Qpu Or Simulator

Run one or more circuits on a quantum device or simulator.

Use the job ID returned by this endpoint to query job status and results with get_job_results_and_status.

This endpoint supports multiple execution scenarios with different combinations of circuits, parameters, and observables. When multiple values are provided for any of them, results are returned as nested lists with up to three layers, ordered by circuits, then observables, then parameters.

The job created by this endpoint is visible in the Haiqu Dashboard and Haiqu Lab UI. Execution results are stored in the database and shown in job details.

Submit parameters:

• Quantum circuit(s) to execute (circuit_ids or circuits_qasm). This can be one circuit or a list of circuits. Circuits can be provided by ID (if they already exist in the database) or by QASM (if they are created on the fly by the AI agent). When QASM is used, circuits are created in the database and associated with the experiment, making them visible in the Haiqu Dashboard and Haiqu Lab UI for future runs or reference.
• Target device or simulator (device_id) to run the circuits on. The device or simulator must be identified by ID, which can be retrieved from list_qpus_and_simulators.
• Optional execution parameters (options) that can include device-specific settings.
• Error mitigation (use_mitigation): set to true to apply error mitigation during execution.
• Estimation-only mode (dry_run): set this to stop just before backend execution for QPU cost estimation.
• observables: Observable(s) to measure. The order of Pauli terms follows the Qiskit reverse-order convention. This can be a single SparsePauliOp or nested lists of SparsePauliOp. For multiple circuits, provide a list where each element corresponds to the observables for that circuit. Defaults to None, in which case circuits must include their own measurements.

IBM Quantum devices: Users must obtain an access token from IBM. To run workloads through IBM Cloud, create an API key in IBM Cloud. This token is used as a secure credential to authorize access to quantum processors. Specify the token in the options field when submitting a job to run circuits on IBM Quantum devices, for example:

options = {
    "ibm_quantum_token": "<YOUR_TOKEN>",
    "ibm_quantum_instance": "<YOUR_INSTANCE>",
}

Amazon Braket devices: Users must obtain an access key and secret key from AWS. To run workloads through Amazon Braket, create an IAM user with the appropriate permissions and generate access keys. Specify these keys in the options field when submitting a job to run circuits on Amazon Braket devices, for example:

options = {
    "aws_access_key_id": "<YOUR_ACCESS_KEY_ID>",
    "aws_secret_access_key": "<YOUR_SECRET_KEY>",
    "aws_default_region": "<YOUR_DEFAULT_REGION>",
}

IonQ Cloud devices: Users must obtain an access token from IonQ. To run workloads through IonQ Cloud, create an API key in the IonQ console. This token is used as a secure credential to authorize access to quantum processors. Specify the token in the options field when submitting a job to run circuits on IonQ Cloud devices, for example:

options = {
    "ionq_api_key": "<YOUR_TOKEN>",
}

Args: user (User): User authenticated with the API key. data (ContextRunSubmitModel): Run parameters. db (Session): Database session.

Returns: ContextRunJobModel: Newly created job information.