Introduction

HQStage provides the stage for your quantum simulations. With HQStage you gain access to our powerful quantum simulation Modules each with distinct use cases and unique features. HQStage and its modules strictly follow our philosophy to provide easy-to-use yet powerful quantum simulation software tools.

At HQS we develop software to simulate quantum mechanical systems on laptops, workstations, HPC centers or quantum computers. Our software can be used for a wide range of quantum mechanical systems like spins, molecules or solids and aims at different properties ranging from spectra to conductivity calculations in disordered systems.

As scientists and software developers we understand, that you prefer to use scientific libraries and tools in a flexible way within a powerful programming environment that allows you to run scripts interactively for visualization and developing and as batch jobs within HPC environments for your large scale simulations.

With this in mind all our tools can be used individually for specific tasks within the workflow of simulating a quantum mechanical system or orchestrated together to generate complex workflows.

Applications

HQStage comes with a command line interface (CLI) that allows you to install and run HQS simulation tools in (virtual) Python environments alongside your preferred open-source Python tools. HQStage takes care of dependencies and updates of your modules and other installed Python tools. Use our simulation software as you prefer to: Run python scripts, interactive IPython sessions or Jupyter Notebooks directly with HQStage CLI.

Don’t have enough compute resources for your high-end quantum simulations? You can use HQS Tasks to effortlessly run HQStage Modules on our Cloud infrastructure. You can easily combine local and Cloud calculations within a simple Python script by directly switching configuration for individual calculations!

Tired of installing software or using your own Laptop for demanding calculations? Use HQStage within your browser via HQS Cloud!

With our intuitive website you manage your HQStage Modules, licenses, subscriptions, compute resources. We offer a free trial license for some of our modules. Learn more about acquiring a free license and getting started with our video tutorial below or following our using our Installation instructions.

Getting started

Features

• HQStage can be managed using our intuitive Cloud website.
  • Manage licenses, modules, compute resources, users
  • Buy new modules
  • Update subscriptions
• Command line tool
  • Automatic dependency management inside virtual environments
  • Easily install HQStage Modules alongside other Python packages inside (virtual) environments
  • Update HQStage Modules
  • Automatic license management and download for HQStage Modules - no struggling with license files or other inconveniences
• Future:
  • Hybride Cloud-local solution with HQS Tasks
  • Effortless integration of computations on Cloud with local computations
  • GPU support on Cloud

Available Plans

We offer four plans for HQStage and HQS Cloud. A free (trial) plan, a standard (cloud only) plan and premium plans for academic and commercial users. Buying or subscribing to HQStage Modules unlocks the premium plan. See the following table for an overview of the different plans:

To learn more about available modules and licensing visit the licensing and modules section of this documentation. The free trial license (free plan) can be requested here. To unlock a advanced plan, obtain a license or upgrade an existing license, please contact us.

(*) See here for module points and pricing
(**) The number of qubits in the HQS Noise App, the HQS Qorrelator App and the HQS Quantum Libraries are restricted in the Free plan. To indicate the difference the Modules are named HQS Noise App Free, HQS Qorrelator App Free and HQS Quantum Libraries Free in this case.
(***) A list of available regions can be found here

Video tutorials and Webinars on HQStages

01 - Introduction and getting started

Account and Token

Register on HQS Cloud

To use HQStage, you need a free user account on our Cloud platform. To create an account visit the login page and click “Create Account”. Follow the instructions on the web page.

Create an API token

After you registered successfully and signed in the Cloud platform, please navigate to the tokens page. Here, you will generate a token that will allow the HQStage CLI to communicate with our Cloud, download and locally install your HQStage Modules.

You can generate tokens with different permissions and scopes. For HQStage you have to create a token with the “license read” permission:

• enter a name for the token
• check read for the license scope

After clicking Submit a dialog will open showing the token’s ID and secret. Do not close this dialog until you proceeded with the next step or copied and saved both ID and secret. You will not be able to read the secret again after closing the dialog.

Installation

Python

HQStage comes with minimal requirements. You only need to have a working Python installation on your system. The hqstage CLI tool requires python>=3.9. Depending on your operating system you can install Python following the instructions for Unix (Linux and BSD), Mac or Windows.

First, try if the correct command in your environment is python or python3. Please adapt the following commands accordingly.

python ...

<venv>\Scripts\python.exe

cd

Virtual environment

We recommend to install HQStage into a virtual environment using venv or mamba. For this guide we assume you create a virtual environment using venv but feel free to use your preferred envrionment management tool. Once you have installed Python on your system you can create and activate a virtual environment called “HQStageBase” in your user directory using

Posix:

python -m venv ~/HQStageBase
. ~/HQStageBase/bin/activate

Windows:

python -m venv $env:USERPROFILE\HQStageBase
~\HQStageBase\Scripts\Activate.ps1

We will call the path to your environment, e.g., ~/HQStageBase, $env:USERPROFILE\HQStageBase, or <venv> from now on. If you are using a special shell you might need a different command to activate the environment:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Once activated all python commands will run in the virtual environment and pip will install packages into the virtual environment instead of the system wide python installation.

Installing HQStage

Once Python has been setup the hqstage CLI tool can be installed. HQStage uses open source libraries. A list of used libraries can be found in the cli documentation. Please follow the download link for HQStage on cloud.quantumsimulations.de/software and copy the corresponding pip command. To see the download link you have to have an active license for HQStage connected to your account. You can request access to a free trial license for the HQStage including access to the modules HQS Noise App and HQS Qorrelator App here. The pip command has the following form:

python3 -m pip install --upgrade --index https://token:user-[a long ID]@license.dev.cloud.quantumsimulations.de/v1/engines/pypi/simple hqstage

In some environments it might be necessary to use python -m pip install ... instead. If you run into problems with both versions please try just pip install ....

Now, hqstage is available in your Python environment. After restarting your terminal you can execute hqstage by running

hqstage

<venv>\Scripts\hqstage

Basic usage

Initializing

Before using HQStage the client needs to be initialized. To do this, please follow the steps outlined 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 up everything you need to start using HQStage:

• Creation of a configuration file using your HQS Cloud token to authenticate with our software distribution and licensing services.
• Addition of your license ID to the configuration file.
• Activation of your machine for the specified license.
• Checkout of a license file for offline usage, valid for 30 days and automatically 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 HQS Noise App and HQS Qorrelator App modules 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:

• Module 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>

_________________________ _________________________ _________________________
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 please refer to 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, jupyter needs to be installed using

hqstage install jupyter

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

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 how to run HQStage in a Jupyter Notebook. After installing the HQS Noise App and HQS Qorrelator App modules and learning how to use them by running examples, we want to start a Jupyter server in a new working directory to work on our first own ideas.

First, please 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.

HQS Cloud

Write and run your Python code in any browser with HQS Cloud. Our platform uses JupyterLab to provide a seamless cloud-based experience for data science and scientific computing. See our plans to learn more about unlocking HQS Cloud. You may use our free plan to get started.

Starting your JupyterLab Server

To launch HQS Cloud visit https://cloud.quantumsimulations.de/notebook and press the “Get started” button. This will launch Jupyter in a new tab of your browser. Use your HQS credentials (email and password) to login to your Jupyter instance and start your personal JupyterLab server (“Start My Server”).

Using your server

Once started you can create and run jupyter notebooks. We have pre-installed all eligible HQS Modules and common packages like numpy into your Python environment. For a more detailed documentation on Jupyter we refer to the official Jupyter documentation. You can install additional python packages into your environment using the command

!pip install <package name>

in a notebook cell. You can ignore the warning that the installation directory is not on PATH. After restarting the kernel you can import the package as usual.

Accessing examples

Coming soon: You will be able to access all examples for our modules from your Jupyter notebboks on HQS Cloud.

Shutdown the server

To shutdown the server open your JupyterLab instance (see here) and click `File–>Hub Control Panel–>Stop My Server“. This will shutdown your server and your HQ$ balance will no longer be debited.

Contact us

For problems and questions regarding HQStage or its modules please contact us via cloud@quantumsimulations.de .

If you want to request access to modules or have questions regarding contracts or billing please contact us via info@quantumsimulations.de .

Overview of Licensing & Modules

HQStage is an execution environment that can be enriched with a variety of modules. These can be obtained either by loan (test license), purchase (“Academic user/ node locked” licenses) or rental (“Industry user/ node locked” licenses) via download.

A list of the available modules can be found on the modules page where descriptions of the modules are also available. The corresponding licenses can be managed on the HQS Cloud.

As a rule, HQStage modules run on 64-bit systems with current Linux and Windows operating systems and also on current MacOS operating systems on ARM architectures. Please refer to the description or documentation of the modules for any restrictions on the execution environment.

HQS uses open source components (OSS components). These OSS components are listed in the respective module overview page in this documentation, along with the applicable license for the OSS components.

Within HQStage, the corresponding modules can be installed and updated based on the licenses available to the user. To learn more look at our getting started section or the cli documentation

The following pages provide an overview of available HQStage modules and different license types.

• Available modules
• Licensing

Licensing

In order to obtain and manage HQStage licenses you have to create an account on the HQS Cloud.

All licenses are bound to our General Terms and Conditions. This General Terms and Conditions always take precedence over this documentation. The following list of available licenses provides only a summary of the licenses defined in the General Terms and Conditions.

When running HQStage and its modules the validity and scope of your licenses will be verified, this requires internet access of the respective machine.

Available Licenses

Academic users and institutions

For academic users, HQS offers user-locked and node-locked licenses for purchase (see price list for prices). These licenses are linked to a specific user or one machine at a time respectively.

Commercial users and institutions

HQS offers user-locked and node-locked subscription models for business and industrial users. For pricing, please request a quote.

How to purchase a license

The free trial license can be requested here. To obtain another license or upgrade an existing license, please contact us.

Pricing

Academic users and institutions

HQStage uses a point system to indicate the size and complexity of the various Modules. The price depends on the total number of points for the modules selected and the number of users or machines required.

For larger numbers of users or machines, please contact us for a quote.

HQStage Modules have the following module points value:

Commercial users and institutions

Prices available on request

Territorial restrictions

Some plans (Standard, Premium) are only available in the following countries / regions:

Modules

At HQS we believe that all steps of the simulation of quantum mechanical systems belong to one of four categories. All our available modules are organized along these categories:

Available Modules

The following modules are available on HQStage. Following the links you can find the User Documentation of the Modules.

To learn more about acquiring a license visit licensing.

HQS Modeling Assistant

You can find the detailed User Documentation here.

HQS Spin Mapper

You can find the detailed User Documentation here.

HQS Molecules

You can find the detailed User Documentation here.

HQS Noise App

You can find the detailed User Documentation here.

HQS Qorrelator App

You can find the detailed User Documentation here.

HQS Quantum Libraries

The HQS Quantum Libraries encompass a comprehensive suite of modules tailored for advanced quantum computing tasks. These modules include algorithms, qonvert, noise-mapper, and the bath-mapper, serving to facilitate quantum algorithm development, compilation, noise emulation, and system-bath interaction modeling.

The HQS Quantum Libraries is a collection of software packages. These are as follows:

• Alqorithms: a collection of tools for building quantum circuits. It includes a collection of quantum algorithms for simulating the trotterized time evolution of a quantum system, tools to build circuits for various kinds of measurements, and algorithms to compute two-point correlators. The detailed Documentation of Alqorithms.
• Qonvert: a range of classes designed to “convert” circuits and quantum programs, each serving as a Converter with specific functionalities: gate decomposition, noise insertion, optimization and routing. The detailed Documentation of Qonvert.
• Noise Mapper: implements noise mapping, the construction of a static noisy algorithm model based on a quantum circuit and physical noise on a quantum computer. The detailed Documentation of the Noise Mapper.
• Bath Mapper: creates objects based on the Bloch-Redfield master equation and to manipulate them. The detailed Documentation of the Bath Mapper.
• Bath Fitter: fits a given open quantum system with an effective open quantum system with finite degrees of freedom. The detailed Documentation of the Bath Fitter.

The HQS Quantum Libraries need to be used in conjunction with the open-source HQS libraries qoqo and struqture, designed for creating quantum programs, as well as representing Hamiltonians and physical models.

HQS Quantum Solver

You can find the detailed User Documentation here.

HQS Spectrum Tools

You can find the detailed User Documentation here.

HQS Qolossal

You can find the detailed User Documentation here.

HQS Raqet

You can find the detailed User Documentation here.

Restrictions and OSS

On this page we list

• Open source dependencies
• Installation hints
• System architecture / operating system restrictions

for all HQStage Modules.

HQS Modeling Assistant

HQS Spin Mapper

HQS Molecules

HQS Noise App

HQS Qorrelator App

HQS Quantum Libraries

 1. Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.

 2. Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.

 3. The names of its contributors may not be used to endorse or promote 
    products derived from this software without specific prior written 
    permission.

HQS Quantum Solver

HQS Spectrum Tools

HQS Qolossal

HQS Raqet

Overview of HQStage CLI

The HQStage Python package provides a command line interface (CLI) for managing HQS Software Modules.

The motivation of this package is to have an easy-to-use entry point to get started with software developed by HQS on most systems without the need to perform a lot of manual installation steps.

Please start using HQStage by reading the installation instructions and the basic usage guide. If required, the HQStage CLI commands API can be used by an experienced user as described in the API reference section.

Features

The HQStage CLI tool comes with the following features:

• Automatic dependency management inside virtual environments
• Easily install HQStage Modules alongside other Python packages inside virtual environments
• Update HQStage Modules
• Automatic license management and download for HQStage Modules - no struggling with license files or other inconveniences

Basic commands

The HQStage CLI comes with a set of (sub-)commands described in the following subsections.

After installing HQStage you can run HQStage with the

hqstage

command in your terminal.

Within HQStage our software tools are called Modules. You can install modules into your current environment using the

hqstage install <module>

command. The same command can be used to install other Python packages from pypi.org. To get an overview of your licensed HQStage Modules run

hqstage modules

Intel’s Math Kernel Library Some HQStage Modules use Intel’s MKL library to accelerate mathematical calculations. You can install MKL using

hqstage install mkl

The command ensures that runtime libraries of mkl are present in the correct format in your environments lib folder.

Typical workflow using HQStage

A typical workflow to setup and run Python interpreters with access to HQStage Modules is to

1. Create a virtual environment using venv or mamba and install hqstage.
2. Install required HQStage Modules and Python packages, e.g., hqstage install hqs-noise-app-py matplotlib mkl
3. Download HQStage examples using hqstage donwload-examples.
4. Start a Jupyter server using python -m jupyter notebook and start creating a notebook that realizes your next simulation using HQStage Modules or write a python script using our modules and execute with python script.py.

Getting help in the terminal

To see all available commands of HQStage use

hqstage --help

To see the available sub-commands and options of any HQStage command use

hqstage <command> --help

To get an overview of your current license and hqstage setup run

hqstage --info

Open-source software components

API reference

HQStage cli provides a set of commands to download and install HQStage modules and other python packages. If required, the HQSTage CLI commands API can be used by an experienced user.

Checkout

Checkout the license file from HQS licensing server.

This checksout the license file from HQS licensing server and saves it into the config directory. The license file will be used by HQStage modules to validate entitlements. The file is valid for 30 days and should be checked-out again before expiration.

hqstage checkout [OPTIONS]

Args

No positional arguments.

Options

• --fingerprint TEXT: Checkout license file for a specific fingerprint. Can be used multiple times and combined with --fingerprints-file.
• --fingerprints-file FILENAME: Read fingerprints from a file. Each line will be interpreted as a fingerprint. Can be used multiple times and combined with --fingerprint.
• --license-id TEXT: Specify the license ID.
• --out-dir PATH: Output directory for the license file. Default is the config directory: $HOME/.config/HQStage.
• –help: Show the help message and exit.

Example

hqstage checkout

Download examples

Download HQStage examples for your modules.

Provide module names with the command line argument -m or –modules. The command tries to find matching examples for incomplete names. If no module name is provided, all available examples will be downloaded.

hqstage download-exampels [OPTIONS]

Args

No positional arguments.

Options

• –download-dir (path) The path to the directory to download the examples to.
• -m, –modules (str) Download examples for a specific module. Can be used multiple times.
• –list-available List available examples instead of downloading.
• –help Show this message and exit.

Example

hqstage download-examples
hqstage download-examples -m noise-app -m hqs-qorrelator-app
mkdir exampels && hqstage download-examples --download-dir ./exampels

Init

Initialize HQStage user and license.

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.

All information can be provided via options (see below) or can be entered interactively during initialization process. It is not necessary to provide all parameters as options or set all parameters interactivly. Any combination works, too.

hqstage init [OPTIONS]

Args

No positional arguments.

Options

• –token-id (str): Provide token id.
• –token (str): Provide token secret.
• –cloud-environment (str): For developers only.
• –license-id (str): Provide your license id.
• –advanced-mode: Activate advanced mode (devs only).
• –help: Show this message and exit.

Example

hqstage init
hqstage init --token-id TokenIDFromCloud --token SecretToken

Install

Install python packages and HQStage Modules into (the currently active) Python environment. Under the hood, HQStage uses uv as a drop-in replacement for standard pip. Look at uv documentation for detailed usage information. Compared to standard pip uv provides better dependency resolution while beeing faster.

hqstage install [OPTIONS] [NAMES]

Args

• names (list[str]): Names of the modules and packages to install.

Options

• -y, –yes: Confirm installation without prompting.
• -a, –all: Install all available modules.
• –help: Show the help message and exit.

Example

hqstage install hqs_noise_app_py --yes
hqstage install "HQS Qorrelator App" hqs-noise-app
hqstage install "hqs_noise_app_py matplotlib qutip
hqstage install "HQS Quantum Solver" mkl -y

Modules

Show your available and installed HQStage Modules and packages.

hqstage modules [OPTIONS]

The output will be of the form

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

Args

No positional arguments.

Options

• –help: Show the help message and exit.

Example

hqstage modules