Basic usage

Initializing

Before using HQStage you have to initialize the client. To do this make sure to follow the steps outlined in here to create a token with the “license read” permission. You will need the token_id and token secret in the initialization step.

To initialize HQStage run

hqstage init

and follow the instructions in the terminal.

<venv>\Scripts\hqstage

The hqstage init command performs the following steps to set everything up you need to start using HQStage:

• Create a config file with your HQS Cloud token used to authenticate with our software distribution and licensing services
• add your license ID to the config file
• activate your machine for your license
• checkout a license file for offline usage. The license file is valid for 30 days and will automatically be renewed once a day when executing HQStage commands.
• create a default HQStage environment into which HQStage Modules can be installed. This default environment is called HQStageEnv

Installing your first module

Now that everything is set up you can install your first HQStage Modules. If you have received the free trial license the modules HQS Noise App and HQS Qorrelator App are available for you. To check which modules are available for your user run

hqstage modules list

The output of this command is a table with installable packages. The left column shows the human-readable name while the right column lists the package names for installation.

Package Name             Package key (for installation)
_______________________________________________________
HQStage                  hqstage
HQS Noise App Py         hqs-noise-app-py
HQS Qorrelator App Py    hqs-qorrelator-app-py

To install the HQS Noise App and the HQS Qorrelator App into the default environment run

hqstage modules install hqs-noise-app-py hqs-qorrelator-app-py

This will install the HQS Noise App and the HQS Qorrelator App with all open-source dependencies into the default HQStage environment. For more information about the modules’ open source dependencies read the modules documentation. If not changed this environment is called HQStageEnv.

Downloading examples and starting a Jupyter notebook server with examples

After installing the HQS Noise App module we want to run our first examples. HQStage Modules come with a collection of examples that introduce both underlying physics and software usage. The examples are provided as ready-to-use Jupyter notebooks and can be downloaded using the following command:

hqstage modules download-examples

This command will download and unpack all available examples for your modules and store them in your user’s data directory. On unix systems this is $HOME/.local/share/HQStage/examples and on Windows $env:LOCALAPPDATA\HQS Quantum Simulations GmbH\HQStage\examples.

To change the download folder use the --download-dir option, e.g., (works on Windopws Powershell and unix):

hqstage modules download-examples --download-dir $HOME/HQS/Examples

The output of the download-examples command will show additional python packages required for the example notebooks and how to install them using HQStage. Before installing the dependencies make sure the OSS licenses comply with your institution’s standards. To install the dependencies run the printed commands, e.g., on Linux using the default download directory

hqstage pip install -r $HOME/.local/share/HQStage/examples/hqs_noise_app/requirements.txt

Now, to launch a Jupyter server in the default examples directory use:

hqstage run examples

or to choose your previously created download directory run

hqstage run examples --examples-dir $HOME/HQS/Examples

An interesting example to start with is the time_evolution_comparison.ipynb example for the HQS Noise App. Have fun browsing our examples!

Starting a Jupyter Notebook

This section shows the example of running HQStage in a Jupyter Notebook. Other variants can be found in the Run section. After installing the HQS Noise App and HQS Qorrelator App modules and learning how to use them by example we want to start a Jupyter server in a new working directory to work on our first own ideas. First, create a folder to store your first notebooks like this mkdir $HOME/MyNotebooks and change into the directory with cd $HOME/MyNotebooks. Now, launch a Jupyter server with the installed HQStage Modules using

hqstage run jupyter

This will start a Jupyter server in the default HQStage environment and will launch a browser tab connected to the Jupyter server.

In the browser tab click File-->New-->Notebook to create a new notebook.

In the pop-up asking for a Python kernel select Python 3 (ipykernel).

In the first cell of the notebook enter

import hqs_noise_app

and hit shift-enter.

Congratulations! You have succesfully installed/imported the HQS Noise App.