On this page advanced uses cases which are supported by the IQM backend integration are described.
.. tab:: Python
To emulate the IQM Server locally, without submitting to the IQM Server, you can set the ``emulate`` flag to ``True``.
This will emit any target specific compiler diagnostics, before running a noise free emulation.
.. code:: python
cudaq.set_target('iqm', emulate=True, url="https://<IQM Server>/")
Emulation mode will still contact the configured IQM Server to retrieve the dynamic quantum architecture resulting from the active calibration unless a QPU architecture file is explicitly specified.
This can be done by setting `mapping_file` to point to a file describing the QPU architecture which should be emulated.
If an architecture is specified no server URL is needed anymore.
.. code:: python
cudaq.set_target('iqm', emulate=True, mapping_file="<path+filename>")
The folder ``targettests/Target/IQM/`` contains sample QPU architecture files.
Find there files for the IQM Crystal architecture as well as files from real life QPUs which can be found on the IQM Resonance portal.
The QPU quantum architecture of a test with a real life IQM QPU can be saved for later use in emulation runs.
To do so the environment variable ``IQM_SAVE_QPU_QA`` must be set to point to a filename in addition to setting the URL of a Resonance server.
The test can even run as emulation as long as a server URL is given to retrieve the current dynamic quantum architecture from.
.. code:: bash
IQM_SERVER_URL="https://demo.qc.iqm.fi/" IQM_SAVE_QPU_QA="<path+filename for QPU architecture file>" python3 program.py
The file will be created with the given name. If the file already exists the test is aborted with an error.
.. tab:: C++
To emulate the IQM machine locally, without submitting to the IQM Server, you can pass the ``--emulate`` option to ``nvq++``.
This will emit any target specific compiler diagnostics, before running a noise free emulation.
.. code:: bash
nvq++ --target iqm --emulate src.cpp -o program
IQM_SERVER_URL="https://demo.qc.iqm.fi/" ./program
Emulation mode will still contact the configured IQM Server to retrieve the dynamic quantum architecture resulting from the active calibration unless a QPU architecture file is explicitly specified.
This can be done by specifying a file with the architecture either at compile time or in an variable in the environment executing the binary.
If an architecture is specified no server URL is needed anymore.
.. code:: bash
// With this binary multiple QPU architectures can be tested without recompilation.
nvq++ --target iqm --emulate src.cpp -o program
IQM_QPU_QA="<path+filename of QPU architecture file>" ./program
.. code:: bash
// This binary will use the given QPU architecture file until overwritten by environment variable "IQM_QPU_QA".
nvq++ --target iqm --emulate --mapping-file <path+filename of QPU architecture file> src.cpp -o program
./program
The folder ``targettests/Target/IQM/`` contains sample QPU architecture files.
Find there files for the IQM Crystal architecture as well as files from real life QPUs which can be found on the IQM Resonance portal.
The QPU architecture of a test with an IQM server can be saved for later use in emulation runs.
To do so the environment variable ``IQM_SAVE_QPU_QA`` must be set to point to a filename in addition to setting the URL of a Resonance server.
The test can even run as emulation as long as a server URL is given to retrieve the current dynamic quantum architecture from.
.. code:: bash
nvq++ --target iqm --emulate src.cpp -o program
IQM_SERVER_URL="https://demo.qc.iqm.fi/" IQM_SAVE_QPU_QA="<path+filename for QPU architecture file>" ./program
To see a complete example, take a look at :ref:`IQM examples <iqm-examples>`.
.. tab:: Python
The number of shots for a kernel execution can be set through
the ``shots_count`` argument to ``cudaq.sample`` or ``cudaq.observe``. By default,
the ``shots_count`` is set to 1000.
.. code:: python
cudaq.sample(kernel, shots_count=10000)
The preferred way to pass the "API Token" to the IQM backend is through the environment variable IQM_TOKEN. For compatibility the earlier used storage of the "API Token" in a file can still be used as follows:
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 can be created manually using the "API Token" obtained from the Resonance profile page.
A tokens file can be created and the environment variable set like this:
echo '{ "access_token": "<put-your-token-here>" }' > resonance-token.json
export IQM_TOKENS_FILE="path/to/resonance-token.json"When storing the "API Token" in a file please make sure to restrict access to this file to only the account running tests. No other user or group on the computer must have any access to this file.