iqm-client 29.14.0__tar.gz → 30.1.0__tar.gz

{iqm_client-29.14.0 → iqm_client-30.1.0}/CHANGELOG.rst

@@ -2,6 +2,34 @@
 Changelog
 =========
 
+Version 30.1.0 (2025-08-28)
+===========================
+
+Bug fixes
+---------
+
+- fix initialization of backends on resonance
+
+Version 30.0.0 (2025-08-20)
+===========================
+
+Features
+--------
+
+- Add the experimental :meth:`IQMClient.get_calibration_quality_metrics` method to retrieve calibration set
+  and related quality metrics from the server.
+- Select calibration and quality metric data are now available in :class:`IQMTarget`,
+  :class:`IQMBackend`, and :class:`IQMBackendBase` for transpilation and querying. :issue:`SW-769`.
+  This data includes the gate durations. :issue:`SW-1321`
+- :func:`transpile_to_IQM` no longer has the ``target`` parameter, the transpilation target is always
+  obtained from ``backend``.
+- :class:`IQMTarget` moved into its own module.
+- :class:`IQMFacadeBackend` can be given the name of the :class:`IQMFakeBackend` instance to use.
+
+Breaking Changes
+----------------
+- :func:`generate_initial_layout` takes an :class:`IQMTarget` as an input argument instead of :class:`IQMBackend`.
+
 Version 29.14.0 (2025-08-20)
 ============================
 
@@ -32,7 +60,7 @@ Version 29.11.0 (2025-08-07)
 Features
 --------
 
-- Added :meth:`IQMClient.get_structured_metrics` for obtaining quality metric information.
+- Added :meth:`IQMClient._get_calibration_quality_metrics` for obtaining quality metric and calibration information.
 
 Version 29.10.0 (2025-07-31)
 ============================
@@ -57,7 +85,7 @@ Features
 --------
 
 - An update to IQMFacadeBackend such that all available IQMFakeBackends are usable for simulation, rather than
-just IQMFakeAdonis
+  just IQMFakeAdonis.
 
 Version 29.7.0 (2025-07-15)
 ===========================
@@ -352,7 +380,7 @@ Version 22.16.0 (2025-04-03)
 ============================
 
 Feature
-*******
+-------
 
 - Enable PEP 604 in linting rules, :issue:`SW-1230`.
 
@@ -368,7 +396,7 @@ Version 22.14.0 (2025-04-02)
 ============================
 
 Features
-********
+--------
 
 - Update the documentation footer to display the package version.
 

{iqm_client-29.14.0 → iqm_client-30.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: iqm-client
-Version: 29.14.0
+Version: 30.1.0
 Summary: Client library for accessing an IQM quantum computer
 Author-email: IQM Finland Oy <developers@meetiqm.com>
 License:                                  Apache License

{iqm_client-29.14.0 → iqm_client-30.1.0}/docs/user_guide_qiskit.rst

@@ -174,6 +174,15 @@ circuit(s) are sampled:
    `Inspecting circuits before submitting them for execution`_ for inspecting the actual run request sent for
    execution.
 
+.. note::
+
+    As of ``iqm-client >= 30.1.0``, structured quality metrics and calibration data are available to
+    ``IQMTarget`` for improved transpilation. To import the latest valid quality metric data corresponding
+    to the default calibration set into ``IQMTarget``, set ``use_metrics`` to ``True`` when initializing the 
+    class. For Resonance users, this data is not yet available via the Resonance API, so use the default setting
+    of ``use_metrics`` of ``False``.
+    
+
 You can optionally provide IQMBackend specific options as additional keyword arguments to
 :meth:`.IQMBackend.run`, documented at :meth:`.IQMBackend.create_run_request`.
 For example, you can enable heralding measurements using ``circuit_compilation_options`` as follows:
@@ -574,6 +583,7 @@ mapping that matches the restriction:
 .. code-block:: python
 
     qubit_mapping = {i: backend.index_to_qubit_name(q) for i, q in enumerate(qubits)}
+    # or qubit_mapping = dict(enumerate(qubits))
     job = backend.run(transpiled_circuit, qubit_mapping=qubit_mapping)
 
 
@@ -731,10 +741,17 @@ Results from such executions are random bits. This may be useful when developing
 Qiskit on IQM contains :class:`.IQMFacadeBackend`, which allows to combine the mock remote execution with a local
 noisy quantum circuit simulation. This way you can both validate your integration as well as get an idea of the expected circuit execution results.
 
-To run a circuit this way, use the ``"facade_x"``, (where `x` is one of the adonis, aprhodite, apollo, deneb or garnet architectures) backend retrieved from the provider.
-Note that the provider must be initialized with the URL of a quantum computer with the equivalent architecture (i.e. names of qubits, their
-connectivity, and the native gateset should match the desired architecture). 
-Additionally, the URL should point to a mock environment rather than a real device as the execution results from the remote will be discarded and replaced by a simulated result generated by Qiskit Aer.
+To run a circuit this way, use :meth:`IQMProvider.get_backend` with one of the backend names
+``facade_adonis, facade_apollo, facade_aphrodite, facade_deneb`` or ``facade_garnet`` to obtain
+a facade backend.
+``facade_adonis, facade_apollo, facade_aphrodite`` represent typical Crystal 5, Crystal 20 and Crystal 54 architecture QPUs,
+whereas ``facade_deneb`` and  ``facade_garnet`` represent the corresponding IQM Resonance quantum computers
+more specifically.
+
+Note that the provider must be initialized with the URL of a quantum computer with the corresponding
+static quantum architecture (i.e. names of qubits, their connectivity, and the native gateset should match the desired architecture).
+Additionally, the URL should point to a mock server rather than a real quantum computer, as the execution results
+from the server will be discarded and replaced by a simulated result generated by Qiskit Aer.
 
 .. code-block:: python
 

{iqm_client-29.14.0 → iqm_client-30.1.0}/src/iqm/iqm_client/cli/auth.py

@@ -42,6 +42,7 @@ class GrantType(str, Enum):
 
 class AuthRequest(BaseModel):
     """Request sent to authentication server for access token and refresh token, or for terminating the session.
+
     * Token request with grant type ``'password'`` starts a new session in the authentication server.
       It uses fields ``client_id``, ``grant_type``, ``username`` and ``password``.
     * Token request with grant type ``'refresh_token'`` is used for maintaining an existing session.

{iqm_client-29.14.0 → iqm_client-30.1.0}/src/iqm/iqm_client/cli/token_manager.py

@@ -51,6 +51,7 @@ def start_token_manager(cycle: int, config: ConfigFile, single_run: bool = False
     """Refresh tokens periodically.
 
     For each refresh cycle new tokens are requested from auth server.
+
     - If refresh is successful next refresh is attempted in the next cycle.
     - If auth server does not respond refresh is attempted repeatedly until it succeeds or
       the existing refresh token expires.
@@ -104,11 +105,10 @@ def refresh_tokens(config: ConfigFile, current_tokens: dict, cycle: int) -> tupl
         cycle: refresh cycle length in seconds
 
     Returns:
-        Tuple[Optional[dict], bool, int] = (tokens, status, sleep_time)
-        tokens: dict containing new tokens or current tokens if auth server could not be connected or
-                None if auth server refused to provide new tokens.
-        status: bool, True if tokens were refreshed successfully, False otherwise
-        sleep_time: time to sleep before next refresh attempt
+        * dict containing new tokens or current tokens if auth server could not be connected or
+          None if auth server refused to provide new tokens
+        * bool, True if tokens were refreshed successfully, False otherwise
+        * time to sleep before next refresh attempt
 
     """
     access_token = current_tokens.get("access_token", "")

{iqm_client-29.14.0 → iqm_client-30.1.0}/src/iqm/iqm_client/iqm_client.py

@@ -20,6 +20,7 @@ from functools import lru_cache
 from http import HTTPStatus
 from importlib.metadata import version
 import json
+import logging
 import os
 import platform
 import time
@@ -77,6 +78,9 @@ DEFAULT_TIMEOUT_SECONDS = 900
 SECONDS_BETWEEN_CALLS = float(os.environ.get("IQM_CLIENT_SECONDS_BETWEEN_CALLS", 1.0))
 
 
+logger = logging.getLogger(__name__)
+
+
 class IQMClient:
     """Provides access to IQM quantum computers.
 
@@ -907,11 +911,18 @@ class IQMClient:
             # model = model_class.model_validate_json(response.text)
         except json.decoder.JSONDecodeError as e:
             raise EndpointRequestError(f"Invalid response: {response.text}, {e!r}") from e
+
         return model
 
-    def get_structured_metrics(self, calibration_set_id: UUID | None = None) -> ObservationFinder:
+    def get_calibration_quality_metrics(self, calibration_set_id: UUID | None = None) -> ObservationFinder:
         """Retrieve the given calibration set and related quality metrics from the server.
 
+        .. warning::
+
+           This method is an experimental interface to the quality metrics and calibration data.
+           The API may change considerably in the next versions *with no backwards compatibility*,
+           including the API of the ObservationFinder class.
+
         Args:
             calibration_set_id: ID of the calibration set to retrieve.
                 If ``None``, the current default calibration set is retrieved.
@@ -925,8 +936,16 @@ class IQMClient:
             HTTPException: HTTP exceptions
 
         """
+        logger.warning(
+            "IQMClient.get_calibration_quality_metrics is an experimental method, and the API will likely change "
+            "in the future with no backwards compatibility."
+        )
+        return self._get_calibration_quality_metrics(calibration_set_id)
+
+    def _get_calibration_quality_metrics(self, calibration_set_id: UUID | None = None) -> ObservationFinder:
+        """See :meth:`get_calibration_quality_metrics`."""
         if isinstance(self._station_control, IqmServerClient):
-            raise ValueError("The get_structured_metrics method is not supported by IqmServerClient.")
+            raise ValueError("The _get_calibration_quality_metrics method is not supported by IqmServerClient.")
 
         if not calibration_set_id:
             # find out the default calset id
@@ -936,5 +955,4 @@ class IQMClient:
         calset_obs = self._station_control.get_observation_set_observations(calibration_set_id)
         quality_metrics = self._station_control.get_calibration_set_quality_metrics(calibration_set_id)
         qm_obs = quality_metrics.observations
-
-        return ObservationFinder(list(calset_obs) + qm_obs)
+        return ObservationFinder(calset_obs + qm_obs)

{iqm_client-29.14.0 → iqm_client-30.1.0}/src/iqm/iqm_client/util.py

@@ -14,12 +14,10 @@
 """Helpful utilities that can be used together with IQMClient."""
 
 from json import JSONEncoder, dumps, loads
-from typing import Any, TypeVar
+from typing import Any
 
 import numpy as np
 
-T = TypeVar("T")
-
 
 class IQMJSONEncoder(JSONEncoder):
     """JSONEncoder that that adds support for some non-JSON datatypes"""

{iqm_client-29.14.0 → iqm_client-30.1.0}/src/iqm/qiskit_iqm/examples/resonance_example.py

@@ -36,7 +36,7 @@ def resonance_example(server_url: str, api_token: str | None) -> dict[str, int]:
     """
     SHOTS = 1000
 
-    # Initialize a backend
+    # Initialize a backend without metrics as IQMClient._get_calibration_quality_metrics is not supported by resonance
     backend = IQMProvider(server_url, token=api_token).get_backend()
 
     # Just to make sure that "get_static_quantum_architecture" method works

{iqm_client-29.14.0 → iqm_client-30.1.0}/src/iqm/qiskit_iqm/fake_backends/fake_adonis.py

@@ -44,5 +44,4 @@ def IQMFakeAdonis() -> IQMFakeBackend:
         },
         name="sample-chip",
     )
-
     return IQMFakeBackend(architecture, error_profile, name="IQMFakeAdonisBackend")

iqm_client-30.1.0/src/iqm/qiskit_iqm/iqm_backend.py

@@ -0,0 +1,158 @@
+# Copyright 2022-2025 Qiskit on IQM developers
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Qiskit backend for IQM quantum computers."""
+
+from __future__ import annotations
+
+from abc import ABC
+import logging
+from typing import Final
+
+from iqm.iqm_client import (
+    DynamicQuantumArchitecture,
+    ObservationFinder,
+)
+from iqm.qiskit_iqm.iqm_target import IQMTarget
+from qiskit.providers import BackendV2
+from qiskit.transpiler import Target
+
+IQM_TO_QISKIT_GATE_NAME: Final[dict[str, str]] = {"prx": "r", "cz": "cz"}
+logger = logging.getLogger(__name__)
+
+
+class IQMBackendBase(BackendV2, ABC):
+    """Abstract base class for various IQM-specific backends.
+
+    Args:
+        architecture: Dynamic quantum architecture associated with the backend instance.
+        metrics: Optional calibration data and related quality metrics for the transpilation target.
+        name: Optional name for the backend instance.
+
+    """
+
+    def __init__(
+        self,
+        architecture: DynamicQuantumArchitecture,
+        *,
+        metrics: ObservationFinder | None = None,
+        name: str = "IQMBackend",
+        **kwargs,
+    ):
+        super().__init__(name=name, **kwargs)
+        self.architecture = architecture
+        self.metrics = metrics
+        # Qiskit uses integer indices to refer to qubits, so we need to map component names to indices.
+        # Because of the way the Target and the transpiler interact, the resonators need to have higher indices than
+        # qubits, or else transpiling with optimization_level=0 will fail because of lacking resonator indices.
+        qb_to_idx = {qb: idx for idx, qb in enumerate(architecture.qubits + architecture.computational_resonators)}
+
+        # NOTE: both targets include fictional CZs
+        self._target = IQMTarget(
+            architecture=architecture,
+            component_to_idx=qb_to_idx,
+            include_resonators=False,
+            include_fictional_czs=True,
+            metrics=metrics,
+        )
+
+        self._target_with_resonators = (
+            IQMTarget(
+                architecture=architecture,
+                component_to_idx=qb_to_idx,
+                include_resonators=True,
+                include_fictional_czs=True,
+                metrics=metrics,
+            )
+            if "move" in architecture.gates
+            else None
+        )
+
+        self._qb_to_idx = qb_to_idx
+        self._idx_to_qb = {v: k for k, v in qb_to_idx.items()}
+        self._coupling_map = self.target.build_coupling_map()
+
+    @property
+    def target(self) -> Target:
+        """Return the target without computational resonators."""
+        return self._target
+
+    @property
+    def target_with_resonators(self) -> Target:
+        """Return the target with MOVE gates and resonators included.
+
+        Raises:
+            ValueError: The backend does not have resonators.
+
+        """
+        target = self._target_with_resonators
+        if target is None:
+            raise ValueError("The backend does not have computational resonators.")
+        return target
+
+    @property
+    def physical_qubits(self) -> list[str]:
+        """Return the list of physical qubits in the backend."""
+        return list(self._qb_to_idx)
+
+    def has_resonators(self) -> bool:
+        """True iff the backend QPU has computational resonators."""
+        return bool(self.architecture.computational_resonators)
+
+    def get_real_target(self) -> Target:
+        """Return the real physical target of the backend without fictional CZ gates."""
+        return IQMTarget(
+            architecture=self.architecture,
+            component_to_idx=self._qb_to_idx,
+            include_resonators=True,
+            include_fictional_czs=False,
+            metrics=self.metrics,
+        )
+
+    def qubit_name_to_index(self, name: str) -> int:
+        """Given an IQM-style qubit name, return the corresponding index in the register.
+
+        Args:
+            name: IQM-style qubit name ('QB1', 'QB2', etc.)
+
+        Returns:
+            Index of the given qubit in the quantum register.
+
+        Raises:
+            ValueError: Qubit name cannot be found on the backend.
+
+        """
+        if name not in self._qb_to_idx:
+            raise ValueError(f"Qubit '{name}' is not found on the backend.")
+        return self._qb_to_idx[name]
+
+    def index_to_qubit_name(self, index: int) -> str:
+        """Given a quantum register index, return the corresponding IQM-style qubit name.
+
+        Args:
+            index: Qubit index in the quantum register.
+
+        Returns:
+            Corresponding IQM-style qubit name ('QB1', 'QB2', etc.).
+
+        Raises:
+            ValueError: Qubit index cannot be found on the backend.
+
+        """
+        if index not in self._idx_to_qb:
+            raise ValueError(f"Qubit index {index} is not found on the backend.")
+        return self._idx_to_qb[index]
+
+    def get_scheduling_stage_plugin(self) -> str:
+        """Return the plugin that should be used for scheduling the circuits on this backend."""
+        return "iqm_default_scheduling"

{iqm_client-29.14.0 → iqm_client-30.1.0}/src/iqm/qiskit_iqm/iqm_move_layout.py

@@ -11,12 +11,10 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-"""Generate an initial layout for a quantum circuit that is
-valid on the quantum architecture specification of the given backend.
-"""
+"""Generate an initial layout for a quantum circuit containing MOVE gates."""
 
 from iqm.iqm_client import DynamicQuantumArchitecture
-from iqm.qiskit_iqm.iqm_backend import IQMBackendBase, IQMTarget
+from iqm.qiskit_iqm.iqm_backend import IQMTarget
 from qiskit import QuantumCircuit
 from qiskit.circuit import Qubit
 from qiskit.dagcircuit import DAGCircuit
@@ -228,26 +226,20 @@ class IQMMoveLayout(TrivialLayout):
 
 
 def generate_initial_layout(
-    backend: IQMBackendBase,
+    target: IQMTarget,
     circuit: QuantumCircuit,
-    restrict_to_qubits: list[int] | list[str] | None = None,
 ) -> Layout:
-    """Generates an initial layout for the given circuit, when run against the given backend.
+    """Generate an initial layout for the given circuit, for running on the given Star architecture target.
 
     Args:
-        backend: IQM backend to run against.
-        circuit: Star architecture circuit for which a layout is to be generated.
-        restrict_to_qubits: Optional list of qubits to restrict the layout to.
+        target: IQM Star architecture target to run the circuit on, without fictional gates.
+        circuit: Quantum circuit for which a layout is to be generated.
 
     Returns:
-        Layout that maps the logical qubits of ``circuit`` to the physical qubits of ``backend`` so that
+        Layout that maps the virtual/logical qubits of ``circuit`` to the physical qubits of ``target`` so that
         all the gates in ``circuit`` are available on those loci.
 
     """
-    target = backend.get_real_target()
-    if restrict_to_qubits is not None:
-        target = target.restrict_to_qubits(restrict_to_qubits)
-
     layout_gen = IQMMoveLayout(target)
     pm = PassManager(layout_gen)
     pm.run(circuit)

{iqm_client-29.14.0 → iqm_client-30.1.0}/src/iqm/qiskit_iqm/iqm_naive_move_pass.py

@@ -200,7 +200,7 @@ def _get_scheduling_method(
 def transpile_to_IQM(  # noqa: PLR0913
     circuit: QuantumCircuit,
     backend: IQMBackendBase,
-    target: IQMTarget | None = None,
+    *,
     initial_layout: Layout | dict | list | None = None,
     perform_move_routing: bool = True,
     optimize_single_qubits: bool = True,
@@ -214,16 +214,14 @@ def transpile_to_IQM(  # noqa: PLR0913
 
     Works with both the Crystal and Star architectures.
 
-    Note: When transpiling a circuit with MOVE gates, you might need to set the `optimization_level` lower.
-    If the `optimization_level` is set too high, the transpiler might add single qubit gates onto the resonator,
+    Note: When transpiling a circuit with MOVE gates, you might need to set ``optimization_level`` lower.
+    If ``optimization_level`` is set too high, the transpiler might add single qubit gates onto the resonator,
     which is not supported by the IQM Star architectures. If this in undesired, it is best to have the transpiler
     add the MOVE gates automatically, rather than manually adding them to the circuit.
 
     Args:
-        circuit: The circuit to be transpiled without MOVE gates.
-        backend: The target backend to compile to. Does not require a resonator.
-        target: An alternative target to compile to than the backend, using this option requires intimate knowledge
-            of the transpiler and thus it is not recommended to use.
+        circuit: The circuit to transpile.
+        backend: The backend to transpile to.
         initial_layout: The initial layout to use for the transpilation, same as :func:`~qiskit.compiler.transpile`.
         perform_move_routing: Whether to perform MOVE gate routing.
         optimize_single_qubits: Whether to optimize single qubit gates away.
@@ -233,30 +231,35 @@ def transpile_to_IQM(  # noqa: PLR0913
         existing_moves_handling: How to handle existing MOVE gates in the circuit, required if the circuit contains
             MOVE gates.
         restrict_to_qubits: Restrict the transpilation to only use these specific physical qubits. Note that you will
-            have to pass this information to the ``backend.run`` method as well as a dictionary.
+            also have to pass this information to :meth:`.IQMBackend.run` using the ``qubit_mapping`` parameter.
         qiskit_transpiler_kwargs: Arguments to be passed to the Qiskit transpiler.
 
     Returns:
         Transpiled circuit ready for running on the backend.
 
     """
-    if restrict_to_qubits is not None:
-        restrict_to_qubits = [backend.qubit_name_to_index(q) if isinstance(q, str) else q for q in restrict_to_qubits]
-
-    if target is None:
-        if circuit.count_ops().get("move", 0) > 0 or circuit.num_qubits > backend.num_qubits:
-            target = backend.target_with_resonators
-            # Create a sensible initial layout if none is provided
-            if initial_layout is None:
-                initial_layout = generate_initial_layout(backend, circuit, restrict_to_qubits)
-            if perform_move_routing and existing_moves_handling is None:
-                raise ValueError("The circuit contains MOVE gates but existing_moves_handling is not set.")
-        else:
-            target = backend.target
+    circuit_has_moves = circuit.count_ops().get("move", 0) > 0
+    # get the target from the backend
+    if circuit_has_moves:
+        target = backend.target_with_resonators
+        if perform_move_routing and existing_moves_handling is None:
+            raise ValueError("The circuit contains MOVE gates but existing_moves_handling is not set.")
+    else:
+        target = backend.target
 
     if restrict_to_qubits is not None:
+        # qubit names to qiskit indices
+        restrict_to_qubits = [backend.qubit_name_to_index(q) if isinstance(q, str) else q for q in restrict_to_qubits]
         target = target.restrict_to_qubits(restrict_to_qubits)
 
+    if circuit_has_moves and initial_layout is None:
+        # Create a sensible initial layout if none is provided, since
+        # the standard Qiskit transpile function does not do this well with resonators.
+        real_target = backend.get_real_target()
+        if restrict_to_qubits is not None:
+            real_target = real_target.restrict_to_qubits(restrict_to_qubits)
+        initial_layout = generate_initial_layout(real_target, circuit)
+
     # Determine which scheduling method to use
     scheduling_method = qiskit_transpiler_kwargs.pop("scheduling_method", None)
     if scheduling_method is None: