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 when executing HQStage commands.

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

The output of this command is a table with an overview of your available modules with the following columns:

Modules Name: The name of the HQStage module in human readable form.

Module Key : The unique key of the HQStage module. Use this key to install all packages of the module via hqstage install <module_key>.

Packages : The list of packages available for this module. HQStage modules contain one or several python packages. You can install individual packages using hqstage install <package_key>

_________________________ _________________________ _________________________
Module Name               Module Key                Packages
_________________________ _________________________ _________________________
HQStage Base              HQSTAGE_BASE              hqstage
HQS Qorrelator App        HQS_QORRELATOR_APP        hqs-qorrelator-app-py
HQS Noise App             HQS_NOISE_APP             hqs-noise-app-py
_________________________ _________________________ _________________________

To install the HQS Noise App and the HQS Qorrelator App into the currently active environment run

hqstage install hqs-noise-app hqs-qorrelator-app

This will install the HQS Noise App and the HQS Qorrelator App with all open-source dependencies. For more information about the modules’ open source dependencies read the modules documentation.

The hqstage install command accepts HQStage Module names, e.g. hqstage install "HQS Noise App" and variants thereof, e.g., "hqs-noise-app", "HQS_NOISE_APP". Additionally, the command accepts hqs package names, e.g.,hqstage install hqs-noise-app-pyor pypy packages such ashqstage install numpy`.

hqstage install mkl

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 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 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 install -r $HOME/.local/share/HQStage/examples/hqs_noise_app/requirements.txt

Before launching a Jupyter server to run the examples you have to install jupyter using

hqstage install jupyter

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

cd $HOME/.local/share/HQStage/examples
python -m jupyter notebook

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. Before launching a Jupyter server you have to install jupyter using

hqstage install jupyter

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

python -m jupyter notebook

This will start a Jupyter server in the active 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.