IQM Backend Advanced Use Cases¶

On this page advanced uses cases which are supported by the IQM backend integration are described.

Emulation Mode¶

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.

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.

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.

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.

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.

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.

// 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

// 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.

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 IQM examples.

Setting the Number of Shots¶

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.

cudaq.sample(kernel, shots_count=10000)

Using Credentials Saved in a File¶

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.