> ## Documentation Index
> Fetch the complete documentation index at: https://docs.haiqu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# IQM Resonance

> Access IQM superconducting QPUs directly via the IQM Resonance platform.

### Overview

IQM's superconducting quantum computers are available in the Haiqu SDK through IQM's **Resonance** platform. This integration lets you run circuits directly on IQM QPUs such as **Garnet**, **Emerald**, and **Sirius** — using IQM's native gate set (R, CZ, Measure) — without leaving the Haiqu SDK.

<Tip>
  ### Key Features of the Integration

  **Direct Resonance access:** Execute quantum programs on IQM's superconducting QPUs straight from the Haiqu SDK — no AWS Braket account required.

  **Dynamic device discovery:** IQM devices are enumerated live from Resonance, so `haiqu.list_devices()` always reflects what your account can reach.

  **Mock simulators:** Every device has an ideal `:mock` variant that runs a server-side noiseless simulation with the device's real topology — perfect for validating a circuit before spending QPU time.
</Tip>

### How to Access QPUs via IQM Resonance

<Steps>
  <Step title="Obtain an IQM Resonance API token">
    Create an API token in the [IQM Resonance dashboard](https://resonance.meetiqm.com/). This token authorizes access to the quantum computers available to your Resonance account, and hardware usage is billed to that account.
  </Step>

  <Step title="Configure Haiqu SDK">
    Pass your token into the run options as `iqm_token`:

    <CodeGroup>
      ```python credentials in options theme={null}
      options = {
          "transpilation_options": {
              "optimization_level": 3,
          },
          "iqm_token": "<YOUR_RESONANCE_TOKEN>",
      }
      ```
    </CodeGroup>

    Alternatively, save it once and the SDK will inject it automatically on subsequent runs:

    ```python theme={null}
    haiqu.save_iqm_credentials("<YOUR_RESONANCE_TOKEN>")
    ```

    <Note>
      The Resonance server URL defaults to `https://resonance.iqm.tech` and does not need to be set. To target a different endpoint, pass `iqm_server_url` in `options` (or use `haiqu.save_iqm_credentials(token, server_url)`).
    </Note>
  </Step>

  <Step title="Submit Quantum Jobs">
    IQM devices follow the id convention `iqm_<name>` (e.g. `iqm_garnet`, `iqm_emerald`, `iqm_sirius`).

    <Note>
      Check which IQM devices are available in your environment by calling `haiqu.list_devices()` first — the list is discovered dynamically from Resonance.
    </Note>

    <CodeGroup>
      ```python by device_id theme={null}
      results_qpu = haiqu.run(
          haiqu_circuit,
          shots=1000,
          device_id="iqm_garnet",
          options=options,
      )
      ```

      ```python by device theme={null}
      device = haiqu.get_device("iqm_garnet")

      results_qpu = haiqu.run(
          haiqu_circuit,
          shots=1000,
          device=device,
          options=options,
      )
      ```
    </CodeGroup>

    The same credentials and device ids work for hybrid programs submitted with `haiqu.flow(...)`.
  </Step>

  <Step title="Monitor and Retrieve Results">
    Track a job's status and retrieve results within the SDK:

    ```python theme={null}
    results_qpu.retrieve_status()

    results_qpu.to_json()
    ```
  </Step>
</Steps>

### Using the IQM mock simulators

Each Resonance device exposes an ideal, noiseless **mock** variant under the id `<device>:mock` — for example `iqm_garnet:mock`. A mock device runs a server-side simulator that uses the real device's topology and native gate set, so it's the fastest way to validate an end-to-end run before submitting to hardware. Mock devices consume **no QPU time**.

<Note>
  Mock devices are authenticated with your `iqm_token` just like the physical QPUs — the token is required for any `iqm_*` device.
</Note>

<CodeGroup>
  ```python run on a mock device theme={null}
  options = {
      "iqm_token": "<YOUR_RESONANCE_TOKEN>",
  }

  results_sim = haiqu.run(
      haiqu_circuit,
      shots=1000,
      device_id="iqm_garnet:mock",
      options=options,
  )
  ```
</CodeGroup>

### Conclusion

The IQM Resonance integration brings IQM's superconducting quantum hardware into the Haiqu SDK with a single credential and the familiar `haiqu.run` / `haiqu.flow` workflow. Whether you are validating a circuit on a mock device or running on Garnet, Emerald, or Sirius, the SDK handles transpilation to IQM's native gate set, submission, and result retrieval for you — so you can focus on your quantum application.