Configuring the environment
Before you can start running experiments on QPUs, you need to configure your environment. The exact procedure depends on where you are running QruiseOS: in JupyterHub or on your local machine.
Running QruiseOS in JupyterLab¶
If you're interacting with QruiseOS from within the JupyterHub environment that comes with your installation, everything is already preconfigured — you're ready to go! In this case, you can safely skip to the next section, Running a measurement.
Running QruiseOS on your local machine¶
To interact with QruiseOS from your local machine, you need to create a so-called identity file which tells the Qruise tools how to access your QruiseOS instance.
Creating an API token¶
The first step is to create an API token. Start by navigating to the QruiseOS dashboard in your web browser. If you are not signed in, you will be automatically redirected to the login page.
First time user?
If you don't know the address of the QruiseOS dashboard, ask your system administrator. They should also have prepared a user account for you.
After logging in, click on the "User" menu item in the bottom-left corner:
In the page that opens, locate the API keys section. When you log in for the first time, there will be no keys and it will display a "No API keys created" message:
To create a new key, click on "Create new key". This will open an API key creation page:
At the top of the page, you can see the roles permissions for the API key. The leftmost column contains the names of the PUs you have access to. In our example, those are "onboarding-chip" and "my-new-qpu". To the right of the QPU name, checkboxes specify which roles will be assigned to the key, as specified by the topmost row. As you can see, there are three different roles: Reader, Writer, and Admin. You can select only the roles that were assigned to you by your administrator — the rest will be greyed out. In our example, the user has the Writer role for the "onboarding-chip" QPU, but only a Reader role for "my-new-qpu".
Missing roles or QPUs?
In order to follow along with the remainder of the Getting started and the User guides sections (including the example notebooks), the two QPUs — onboarding-chip and my-new-qpu — must first be created following the instructions in Creating a new QPU. Create your API token only after you can see these two QPUs in your dashboard. If either or both of the QPUs are missing or you cannot select a role that you need, contact your system administrator to first create these QPUs and assign you the necessary roles.
You can now select all the roles you wish your API key to have, as well as its name and a description, and click the "Create key" button:
When you click the "Create key" button, the newly created API key will be shown at the bottom of the page:
Copy the API key and save it to your disk - we will need it in the next step.
API keys and security
For security reasons, the API key will only be shown to you when you create it. When you reload the page or close the web browser, it will not be possible to recover it. If this happens to you, simply remove the key and create a new one.
Creating an identity file¶
With the API token created, the final step is to create a default identity file: a text file called default.id located in the ~/.config/qruise/credentials directory. You can create it either in a file explorer or by running the following commands in your terminal window:
Now open the ~/.config/qruise/credentials/default.id file and make sure it has the following structure (replace API_TOKEN with the token you generated in the previous step and QRUISEOS_API_URL with the QruiseOS API URL):
QruiseOS API URL
If you don't know your QruiseOS API URL, ask your team leader or administrator.
For instance, if the QruiseOS server address is https://api.example.com/, then for the token created in the previous section the identity file would look the following:
key: qruise_os_cf10895db9524dea81e98e48b0e95405_51323532e545f024d1c2a3fd11bfbb16a2fa833e3f063c2f5c3af0a936ea8db8
url: https://api.example.com/
In order to check that your API token has been correctly set in the identity file, you can try out the example notebooks in ~/qruise/examples/ on your QruiseOS-hosted JupyterHub instance and follow the User guides section in this documentation.