Installation (latest release)#

uv is highly recommended for practical Python environment and package management. With uv installed in your system, start a terminal in your machine and create a new Python environment

uv venv --python=3.11

Note: refer to uv’s documentation if there are problems setting up a Python environment.

After the command has run, read the output and make sure to use the prompt to activate the environment. Then, you can install the latest release of the IQM Benchmarks by running:

uv pip install iqm-benchmarks

Supplied within the Python package there is an additional requirements.txt file containing locked, security scanned dependencies. The file can be used to constrain installed dependencies either directly from the repo or by extracting it from the PyPI package.

uv pip install --constraint requirements.txt iqm-benchmarks

Optional dependencies#

Optional dependencies like compressive gate set tomography and jupyter notebooks can be installed as follows:

uv pip install "iqm-benchmarks[mgst,examples]"

Current optional dependencies are:

• examples: Jupyter notebooks

• mgst: Compressive gate set tomography

• test: Code testing and Linting

• docs: Documentation building

• cicd: CICD tools

Development installation (latest changes)#

To install in development mode with all required dependencies, you can instead clone the repository and from the project directory run

uv pip install --constraint requirements.txt iqm-benchmarks --editable ."[test, docs, mgst]"

To run the tests, you can use the following command:

./test

To build the API documentation as HTML:

./docbuild

Update the requirements. This is necessary when you add a new dependency or update an existing one in pyproject.toml. After this, any changes in the lockfile requirements.txt have to be committed. The script upgrades locked dependencies defined in pyproject.toml within the given version ranges. However, transitive dependencies are deliberately not upgraded automatically.

python update-requirements.py

Characterize Physical Hardware#

The IQM Benchmarks suite is designed to be used with real quantum hardware. To use the suite, you will need to have access to a quantum computer. The suite is designed to work with both IQM Resonance (IQM’s quantum cloud service) and on-prem devices, but can be easily adapted to work with other quantum computing platforms.

To use the suite with IQM Resonance, you will need to set up an account and obtain an API token. You can then set the IQM_TOKEN environment variable to your API token. The suite will automatically use this token to authenticate with IQM Resonance.

import os
os.environ["IQM_TOKEN"] = "your_token"

from iqm.benchmarks.randomized_benchmarking.interleaved_rb.interleaved_rb import InterleavedRBConfiguration
from iqm.benchmarks.randomized_benchmarking.mirror_rb.mirror_rb import MirrorRBConfiguration
from iqm.benchmarks.quantum_volume.quantum_volume import QuantumVolumeConfiguration

EXAMPLE_IRB = InterleavedRBConfiguration(
    qubits_array=[[3,4],[8,9]],
    sequence_lengths=[2**(m+1)-1 for m in range(7)],
    num_circuit_samples=30,
    shots=2**10,
    calset_id=None,
    parallel_execution=True,
    interleaved_gate = "iSwapGate",
    interleaved_gate_params = None,
    simultaneous_fit = ["amplitude", "offset"],
)

EXAMPLE_MRB = MirrorRBConfiguration(
    qubits_array=[[0,1],
                  [0,1,3,4],
                  [0,1,3,4,8,9],
                  [0,1,3,4,8,9,13,14],
                  [0,1,3,4,8,9,13,14,17,18]],
    depths_array=[[2**m for m in range(9)],
                  [2**m for m in range(8)],
                  [2**m for m in range(7)],
                  [2**m for m in range(6)],
                  [2**m for m in range(5)]],
    num_circuit_samples=10,
    num_pauli_samples=5,
    shots=2**8,
    two_qubit_gate_ensemble={"CZGate": 0.7, "iSwapGate": 0.3}, # {GATE: PROBABILITY}
    density_2q_gates=0.25,
    calset_id=None,
)

EXAMPLE_QV = QuantumVolumeConfiguration(
    num_circuits=800,
    shots=2**8,
    calset_id=None,
    num_sigmas=2,
    choose_qubits_routine="custom",
    custom_qubits_array=[[0,1,2,3], [0,1,3,4]],
    qiskit_optim_level=3,
    optimize_sqg=True,
    routing_method="sabre",
    physical_layout="fixed",
    max_circuits_per_batch=500,
    max_gates_per_batch=60_000, # Will be used if it renders a smaller max batch size than max_circuits_per_batch
    rem=True,
    mit_shots=1_000,
)

from iqm.benchmarks.randomized_benchmarking.mirror_rb.mirror_rb import *
# import os
# os.environ["IQM_TOKEN"] = "your_token"

backend = IQMProvider("https://example-station.qc.iqm.fi/cocos/").get_backend()

EXAMPLE_EXPERIMENT = MirrorRandomizedBenchmarking(backend, EXAMPLE_MRB)
EXAMPLE_EXPERIMENT.run()