Support dynamic quantum architecture for IQM QPUs

.github/workflows/config/spelling_allowlist.txt

@@ -297,6 +297,7 @@ prepend
 preprocessor
 probability
 programmatically
+prx
 pybind
 qaoa
 qed
@@ -352,6 +353,7 @@ toolchain
 toolchains
 toolset
 transmon
+transpile
 trotterization
 uccsd
 unary

.github/workflows/integration_tests.yml

@@ -500,7 +500,7 @@ jobs:
             # Only the following tests are currently supported on IQM
             case $filename in
               targettests/iqm/*)
-                nvq++ -DSYNTAX_CHECK --target iqm --iqm-machine Crystal_5 $filename
+                nvq++ -DSYNTAX_CHECK --target iqm $filename
                 test_status=$?
                 if [ $test_status -eq 0 ]; then
                   ./a.out

.github/workflows/test_in_devenv.yml

@@ -91,7 +91,7 @@ jobs:
           shell: bash
           run: |
             cd $CUDAQ_REPO_ROOT
-            python3 -m pip install iqm-client==16.1
+            python3 -m pip install iqm-client==28.0.0
             python3 -m pytest -v build/python/tests/interop/
             pytest_status=$?
             if [ ! $pytest_status -eq 0 ]; then

docs/sphinx/targets/cpp/iqm.cpp

@@ -1,6 +1,6 @@
 // Compile and run with:
 // ```
-// nvq++ --target iqm iqm.cpp --iqm-machine Crystal_5 -o out.x && ./out.x
+// nvq++ --target iqm iqm.cpp -o out.x && ./out.x
 // ```
 // Assumes a valid set of credentials have been stored.
 

docs/sphinx/targets/python/iqm.py

@@ -4,9 +4,7 @@
 # for every execution call on your kernel.
 # To use different targets in the same file, you must update
 # it via another call to `cudaq.set_target()`
-cudaq.set_target("iqm",
-                 url="http://localhost/cocos",
-                 **{"qpu-architecture": "Crystal_5"})
+cudaq.set_target("iqm", url="http://localhost/")
 
 # Crystal_5 QPU architecture:
 #       QB1

docs/sphinx/using/backends/hardware/superconducting.rst

@@ -113,34 +113,49 @@ IQM
 
 .. _iqm-backend:
 
-Support for submissions to IQM is currently under development. 
-In particular, two-qubit gates can only be performed on adjacent qubits. For more information, we refer to the respective hardware documentation.
+The `IQM Resonance <https://meetiqm.com/products/iqm-resonance/>`__ portal offers access to various different IQM quantum computers.
+The machines available will be constantly extended as development progresses.
+Programmers of CUDA-Q may access the IQM Server from either C++ or Python.
+
+With this version it is no longer necessary to define the target QPU architecture in the code or at compile-time.
+The IQM backend integration now contacts at runtime the configured IQM server and fetches the active dynamic quantum architecture of the QPU.
+This is then used as input to transpile the quantum kernel code just-in-time for the target QPU topology.
+By setting the environment variable ``IQM_SERVER_URL`` the target server can be selected just when executing the program.
+As result the python script or the compiled C++ program can be executed on different QPUs without any changes to the code.
+
+For IQM architectures two-qubit gates can only be performed on adjacent qubits. For more information, we refer to the respective hardware documentation.
 Support for automatically injecting the necessary operations during compilation to execute arbitrary multi-qubit gates will be added in future versions.
 
 Setting Credentials
 `````````````````````````
 
-Programmers of CUDA-Q may access the IQM Server from either C++ or Python. Following the `quick start guide <https://iqm-finland.github.io/cortex-cli/readme.html#using-cortex-cli>`__, install `iqm-cortex-cli` and login to initialize the tokens file.
-The path to the tokens file can either be passed explicitly via an environment variable or it will be loaded automatically if located in
-the default location :code:`~/.cache/iqm-cortex-cli/tokens.json`.
+Create a free account on the `IQM Resonance <https://meetiqm.com/products/iqm-resonance/>`__ portal and log-in.
+Navigate to the account profile (top right). There generate an "API Token" and copy the generated token-string.
+Set the environment variable ``IQM_TOKEN`` to contain the value of the token-string.
+The IQM backend integration will use this as authorization token at the IQM server.
+
+Note: The previously used ``IQM_TOKENS_FILE`` environment variable can still be used to point to a tokens file but will be ignored if the ``IQM_TOKEN`` variable is set.
+The tokens file cannot be generated by the ``iqmclient`` tool anymore but needs to be created manually using the token obtained from the Resonance profile page.
+A token file can be created and the environment variable set like this:
 
 .. code:: bash
 
-    export IQM_TOKENS_FILE="path/to/tokens.json"
+    echo '{ "access_token": "<put-your-token-here>" }' > resonance-token.json
+    export IQM_TOKENS_FILE="path/to/resonance-tokens.json"
 
+Please find more documentation after logging in to the IQM Resonance portal.
 
-
 Submitting
 `````````````````````````
-    
-.. tab:: Python 
-    
+
+.. tab:: Python
+
         The target to which quantum kernels are submitted
         can be controlled with the ``cudaq.set_target()`` function.
 
         .. code:: python
 
-            cudaq.set_target("iqm", url="https://<IQM Server>/cocos",**{"qpu-architecture": "Crystal_5"})
+            cudaq.set_target("iqm", url="https://<IQM Server>/")
 
         To emulate the IQM Server locally, without submitting to the IQM Server,
         you can also set the ``emulate`` flag to ``True``. This will emit any target
@@ -157,39 +172,33 @@ Submitting
         .. code:: python
 
             cudaq.sample(kernel, shots_count=10000)
-
+
+        To see a complete example for using IQM server backends, take a look at our :doc:`Python examples<../../examples/examples>`.
+
+
 .. tab:: C++
-
-        To target quantum kernel code for execution on an IQM Server,
-        pass the ``--target iqm`` flag to the ``nvq++`` compiler, along with a specified ``--iqm-machine``.
 
-        .. note::
-            The ``--iqm-machine`` is  a mandatory argument. This provided architecture must match
-            the device architecture that the program has been compiled against. The hardware architecture for a
-            specific IQM Server may be checked  via `https://<IQM server>/cocos/quantum-architecture`.
+        To target quantum kernel code for execution on an IQM Server,
+        pass the ``--target iqm`` flag to the ``nvq++`` compiler.
 
         .. code:: bash
 
-            nvq++ --target iqm --iqm-machine Crystal_5 src.cpp
+            nvq++ --target iqm src.cpp
 
-        Once the binary for a specific IQM QPU architecture is compiled, it can be executed against any IQM Server with the same QPU architecture:
+        Once the binary for an IQM QPU is compiled, it can be executed against any IQM Server:
 
         .. code:: bash
 
-            nvq++ --target iqm --iqm-machine Crystal_5 src.cpp -o program
-            IQM_SERVER_URL="https://demo.qc.iqm.fi/cocos" ./program
-
-            # Executing the same program against an IQM Server with a different underlying QPU
-            # architecture will result in an error.
-            IQM_SERVER_URL="https://<Crystal_20 IQM Server>/cocos" ./program
+            nvq++ --target iqm src.cpp -o program
+            IQM_SERVER_URL="https://demo.qc.iqm.fi/" ./program
 
         To emulate the IQM machine locally, without submitting to the IQM Server,
         you can also pass the ``--emulate`` flag to ``nvq++``. This will emit any target
         specific compiler diagnostics, before running a noise free emulation.
 
         .. code:: bash
 
-            nvq++ --emulate --target iqm --iqm-machine Crystal_5 src.cpp
+            nvq++ --emulate --target iqm src.cpp
 
 To see a complete example, take a look at :ref:`IQM examples <iqm-examples>`.
 

lib/Optimizer/CodeGen/TranslateToIQMJson.cpp

@@ -1,6 +1,7 @@
 /*******************************************************************************
  * Copyright (c) 2022 - 2025 NVIDIA Corporation & Affiliates.                  *
  * All rights reserved.                                                        *
+ * Copyright 2025 IQM Quantum Computers                                        *
  *                                                                             *
  * This source code and the accompanying materials are made available under    *
  * the terms of the Apache License 2.0 which accompanies this distribution.    *
@@ -121,10 +122,10 @@ static LogicalResult emitOperation(nlohmann::json &json,
     emitter.getOrAssignName(optor->getResult(1),
                             emitter.getOrAssignName(optor.getTarget(0)).str());
   } else {
-    json["name"] = name;
+    json["name"] = "prx";
 
     if (optor.getParameters().size() != 2)
-      optor.emitError("IQM phased_rx gate expects exactly two parameters.");
+      optor.emitError("IQM prx gate expects exactly two parameters.");
 
     auto parameter0 =
         cudaq::getParameterValueAsDouble(optor.getParameters()[0]);
@@ -154,7 +155,7 @@ static LogicalResult emitOperation(nlohmann::json &json,
 
 static LogicalResult emitOperation(nlohmann::json &json,
                                    cudaq::Emitter &emitter, quake::MzOp op) {
-  json["name"] = "measurement";
+  json["name"] = "measure";
   std::vector<std::string> qubits;
   for (auto target : op.getTargets())
     qubits.push_back(emitter.getOrAssignName(target).str());

python/tests/backends/test_IQM.py

@@ -1,6 +1,7 @@
 # ============================================================================ #
 # Copyright (c) 2022 - 2025 NVIDIA Corporation & Affiliates.                   #
 # All rights reserved.                                                         #
+# Copyright 2025 IQM Quantum Computers                                         #
 #                                                                              #
 # This source code and the accompanying materials are made available under     #
 # the terms of the Apache License 2.0 which accompanies this distribution.     #
@@ -30,21 +31,6 @@
 # Define the port for the mock server
 port = 62443
 
-# If we're in a git repo, test that we can provide a filename with spaces.
-# If we are not in a git repo, then simply test without overriding
-# mapping_file. (Testing a mapping_file with spaces is done elsewhere, and
-# that isn't the main point of these tests.)
-with os.popen("git rev-parse --show-toplevel") as f:
-    git_top = f.read().strip()
-    if os.path.isdir(git_top):
-        target_config_origin = os.path.join(
-            f"{git_top}", "runtime/cudaq/platform/default/rest/helpers/iqm")
-        target_config_dest = os.path.join(f"{git_top}", "targettests")
-        shutil.copy(os.path.join(target_config_origin, "Crystal_5.txt"),
-                    os.path.join(target_config_dest, "Crystal_5_Variant.txt"))
-        shutil.copy(os.path.join(target_config_origin, "Crystal_20.txt"),
-                    os.path.join(target_config_dest, "Crystal_20_Variant.txt"))
-
 
 def assert_close(want, got, tolerance=1.0e-5) -> bool:
     return abs(want - got) < tolerance
@@ -68,11 +54,7 @@ def startUpMockServer():
     cudaq.set_random_seed(13)
     # Set the targeted QPU
     os.environ["IQM_TOKENS_FILE"] = tmp_tokens_file.name
-    kwargs = {"qpu-architecture": "Crystal_20"}
-    if os.path.isdir(git_top):
-        mapping_file = f"{git_top}/targettests/Crystal_20_Variant.txt"
-        kwargs["mapping_file"] = mapping_file
-    cudaq.set_target("iqm", url="http://localhost:{}".format(port), **kwargs)
+    cudaq.set_target("iqm", url="http://localhost:{}".format(port))
 
     yield "Running the tests."
 

runtime/cudaq/platform/default/rest/helpers/iqm/CMakeLists.txt

@@ -7,16 +7,14 @@
 # ============================================================================ #
 target_sources(cudaq-rest-qpu PRIVATE IQMServerHelper.cpp)
 add_target_config(iqm)
-add_target_mapping_arch(iqm "Crystal_5.txt")
-add_target_mapping_arch(iqm "Crystal_20.txt")
-add_target_mapping_arch(iqm "Crystal_54.txt")
+add_target_mapping_arch(iqm Crystal_20.txt)
 
 
 add_library(cudaq-serverhelper-iqm SHARED IQMServerHelper.cpp )
 target_link_libraries(cudaq-serverhelper-iqm
-  PUBLIC 
-    cudaq-common 
-    fmt::fmt-header-only 
+  PUBLIC
+    cudaq-common
+    fmt::fmt-header-only
 )
 install(TARGETS cudaq-serverhelper-iqm DESTINATION lib)