You're reading an old version of this documentation. If you want up-to-date information, please have a look at 11.0.

User guide#

This guide illustrates the main features of Qiskit on IQM. You are encouraged to run the demonstrated code snippets and check the output yourself.


The recommended way is to install the distribution package qiskit-iqm directly from the Python Package Index (PyPI):

$ pip install qiskit-iqm

After installation Qiskit on IQM can be imported in your Python code as follows:

import qiskit_iqm

Running a quantum circuit on an IQM quantum computer#

In this section we construct a simple quantum circuit and demonstrate how to execute it on an IQM quantum computer.


At the moment IQM does not provide a quantum computing service open to the general public. Please contact our sales team to set up your access to an IQM quantum computer.

Let’s consider the following quantum circuit which prepares and measures a Bell state:

from qiskit import QuantumCircuit

qc = QuantumCircuit(2, 2)
qc.h(0), 1)
qc.measure([0, 1], [0, 1])

     ┌───┐     ┌─┐
q_0: ┤ H ├──■──┤M├───
q_1: ─────┤ X ├─╫─┤M├
          └───┘ ║ └╥┘
c: 2/═══════════╩══╩═
                0  1

First, we need to decompose it into IQM’s native gate family:

from qiskit.compiler import transpile

qc_decomposed = transpile(qc, basis_gates=['r', 'cz'])

global phase: 3π/2
     ┌────────────┐┌────────┐                 ┌─┐
q_0: ┤ R(π/2,π/2) ├┤ R(π,0) ├─■───────────────┤M├─────────────
     ├────────────┤├────────┤ │ ┌────────────┐└╥┘┌────────┐┌─┐
q_1: ┤ R(π/2,π/2) ├┤ R(π,0) ├─■─┤ R(π/2,π/2) ├─╫─┤ R(π,0) ├┤M├
     └────────────┘└────────┘   └────────────┘ ║ └────────┘└╥┘
c: 2/══════════════════════════════════════════╩════════════╩═
                                           0            1

Then, to run this circuit on an IQM quantum computer we need to figure out how to map the virtual qubits to physical ones. Let’s assume we are working with one of IQM’s 5-qubit Adonis chips which have the following connectivity

QB2 - QB3 - QB4

We can choose any pair of connected physical qubits and map the two virtual qubits in the circuit to them, e.g.

virtual_qubits = qc_decomposed.qubits
qubit_mapping = {virtual_qubits[0]: 'QB1', virtual_qubits[1]: 'QB3'}


Currently, IQMBackend does not support automatic generation of mapping from virtual qubits to physical ones using Qiskit transpilers, so it has to be done manually. In a simple scenario as above it is pretty straightforward to do the mapping manually. However in more complicated cases were SWAP gates need to be inserted to accomplish the mapping you can still use Qiskit tools to transpile the circuit against a certain coupling map and then extract qubit_mapping from the result.

Now that we have everything ready, we can run the circuit against the available IQM backend:

from qiskit_iqm import IQMProvider

provider = IQMProvider(iqm_server_url, iqm_settings_path)
backend = provider.get_backend()
job =, shots=1000, qubit_mapping=qubit_mapping)


Note that the code snippet above assumes that you have set the variables iqm_server_url and iqm_settings_path. If the IQM server you are connecting to requires authentication, you will also have to set the IQM_AUTH_SERVER, IQM_AUTH_USERNAME and IQM_AUTH_PASSWORD environment variables or pass them as arguments to the constructor of IQMProvider.

How to develop and contribute#

Qiskit on IQM is an open source Python project. You can contribute by creating GitHub issues to report bugs or request new features, or by opening a pull request to submit your own improvements to the codebase.

To start developing the project, clone the GitHub repository and install it in editable mode with all the extras:

$ git clone
$ cd qiskit-on-iqm
$ pip install -e ".[dev,docs,testing]"

To be able to build the docs graphviz has to be installed. Then to build and view the docs run:

$ tox -e docs
$ firefox build/sphinx/html/index.html

Run the tests:

$ tox

Tagging and releasing#

After implementing changes to Qiskit on IQM one usually wants to release a new version. This means that after the changes are merged to the main branch

  1. the repository should have an updated CHANGELOG.rst with information about the new changes,

  2. the latest commit should be tagged with the new version number,

  3. and a release should be created based on that tag.

The last two steps are automated, so one needs to worry only about properly updating the CHANGELOG. It should be done along with the pull request which is introducing the main changes. The new version must be added on top of all existing versions and the title must be “Version MAJOR.MINOR”, where MAJOR.MINOR represents the new version number. Please take a look at already existing versions and format the rest of your new CHANGELOG section similarly. Once the pull request is merged into main, a new tag and a release will be created automatically based on the latest version definition in the CHANGELOG.