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.
Windows ObjectNotFound
Windows ObjectNotFound
If you have not activated your virtual environment Windows will not be aware of hqstage
.
Either activate the virtual environment into which HQStage was installed or run
<venv>\Scripts\hqstage
instead of 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.
Output
Output
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.