Appearance
Quickstart
This page provides a crash course on using Kipu Quantum Hub to run an entire quantum workflow, from development to deployment 🚀.
First of all, create an account if you don't have one yet.
TL;DR
To get started quickly, install the CLI and the Quantum SDK in a Python virtual environment:
bash
npm install -g @planqk/planqk-cli
uv add planqk-quantum
planqk login -t YOUR_PERSONAL_ACCESS_TOKEN_HERETo run a Qiskit program, all you need is an account and three lines of Quantum code:
python
from planqk.quantum.sdk import PlanqkQuantumProvider
qiskit_circuit = ... # create your Qiskit circuit here
# Either use the CLI to log in or set the environment variable PLANQK_PERSONAL_ACCESS_TOKEN.
provider = PlanqkQuantumProvider()
# Alternatively, you can pass the access token as an argument to the constructor
provider = PlanqkQuantumProvider(access_token="YOUR_PERSONAL_ACCESS_TOKEN_HERE")
result = provider.get_backend("azure.ionq.simulator").run(qiskit_circuit, shots=100).result()You can find more examples and documentation on how to use different backends etc. in the Quantum SDK documentation.
Install the CLI
To install the CLI, you must install Node.js 18 or higher and the npm command line interface using either a Node version manager or a Node installer.
Then install the CLI using npm:
bash
npm install -g @planqk/planqk-cliTIP
Take a look at the CLI reference for more information on the available commands.
Login to your account
Copy your personal access token to your clipboard.
Login to your account using your access token:
bash
planqk login -t <your access token>TIP
If you like to work in the context of an organization you joined on Kipu Quantum Hub, run planqk set-context and select the organization you want to work with.
Run your first quantum program
The Quantum SDK provides an easy way to develop quantum circuits that can be executed on quantum backends/devices available through Kipu Quantum Hub. The SDK allows you to use your favorite quantum libraries, such as Qiskit and AWS Braket, to construct circuits and run them on quantum hardware in the cloud.
IMPORTANT
You need Python 3.11 or higher to use the Quantum SDK.
TIP
Instead of using your global Python installation, we recommend creating a dedicated Python virtual environment for your quantum projects.
We recommend using uv to create and manage Python virtual environments easily. You can use venv, virtualenv, or conda as well.
Setup a new project [optional]
This step is optional but recommended to keep your project dependencies isolated. Create a new directory for your quantum project and navigate into it:
bash
mkdir ~/my-quantum-project
cd ~/my-quantum-projectWe recommend using uv to create a new virtual environment in the project directory. This helps to keep your project dependencies isolated from your global Python installation.
If you don't have uv installed, you can install it as described in the uv installation guide.
Then create a new Python virtual environment using uv:
bash
uv venv # Create a new virtual environment in the .venv directory
uv init # Initializes a new uv projectActivate the virtual environment:
bash
source .venv/bin/activateInstall the Quantum SDK:
You can install the Quantum SDK using uv:
shell
uv add planqk-quantumExample: Coin Toss
To construct a Qiskit circuit, i.e., a quantum algorithm, that simulates n coin tosses on a quantum computer, representing outcomes as zeros 0 and ones 1 instead of heads and tails. This results in 2^n possible outcomes, and each measurement (shot) of the quantum state yields one of these possibilities. To run the circuit on a quantum backend via Kipu Quantum Hub, we use the PlanqkQuantumProvider from our Quantum SDK. This Qiskit provider connects to Kipu Quantum Hub, enabling execution of quantum circuits on supported devices. Learn more about Qiskit here.
TIP
We recommend using the CLI to log in and authenticate with Kipu Quantum Hub. Then, you can use the PlanqkQuantumProvider without specifying the access token:
python
provider = PlanqkQuantumProvider()Add the following code to a new Python file, e.g., coin_toss.py:
python
from planqk.quantum.sdk import PlanqkQuantumProvider
from qiskit import QuantumCircuit, transpile
n_coin_tosses = 2
circuit = QuantumCircuit(n_coin_tosses)
for i in range(n_coin_tosses):
circuit.h(i)
circuit.measure_all()
# Use the PLANQK CLI and log in with "planqk login" or set the environment variable PLANQK_PERSONAL_ACCESS_TOKEN.
# Alternatively, you can pass the access token as an argument to the constructor
provider = PlanqkQuantumProvider()
### If you do not want to login using the CLI, you can also provide your personal access token directly here:
# provider = PlanqkQuantumProvider(access_token="YOUR_PERSONAL_ACCESS_TOKEN_HERE")
# Select a quantum backend suitable for the task. All PLANQK supported quantum backends are
# listed at https://hub.kipu-quantum.com/quantum-backends.
backend = provider.get_backend("azure.ionq.simulator")
# Transpile the circuit ...
circuit = transpile(circuit, backend)
# ... and run it on the backend
job = backend.run(circuit, shots=100)
counts = job.result().get_counts()
print(counts)You can run the program like this:
bash
python coin_toss.pyA possible outcome of the coin toss quantum algorithm could be:
json
{
"00": 23,
"01": 22,
"10": 29,
"11": 26
}TIP
We have prepared a Jupyter notebook that you can use to immediately run the Quantum Coin Toss example: coin_toss.ipynb
IMPORTANT
Access to IonQ's quantum simulator (azure.ionq.simulator) is free of charge. Other backends/devices requires an account with active payment information.
Create your first Service project
Create a new project by running the following command:
bash
planqk initYou will be prompted to provide some information about your project. For this quickstart, select the following configuration:
- Service name:
my-project - Starter template:
Python Starter - vCPU configuration:
1 vCPU - Memory configuration:
1GB
This will create a new directory called my-project containing all required files to run your quantum code on Kipu Quantum Hub. The Python Starter templates implement the coin toss example from above as a Service.
Note the planqk.json file in the project directory, which contains the project configuration, for example:
json
{
"name": "my-project",
"descriptionFile": "README.md",
"resources": {
"cpu": 1,
"memory": 1
},
"runtime": "PYTHON_TEMPLATE"
}TIP
For more information on the bootstrapped project structure, see the README.md file in the project directory.
Test your service locally
Let's test your service locally before deploying it to Kipu Quantum Hub. First, switch to your project directory:
bash
cd my-projectThen, install the required dependencies. We recommend creating a dedicated Python environment to install and track all required packages from the start. You may use the requirements.txt file to create a virtual environment with the tooling of your choice.
For example, you can use uv to create a virtual environment and install the required packages:
bash
uv venv
uv sync
source .venv/bin/activateOpen the src/program.py file, modify the following line and enter your personal access token:
python
provider = PlanqkQuantumProvider(access_token="YOUR_PERSONAL_ACCESS_TOKEN_HERE")Finally, run your service locally:
bash
python -m srcThe output should look like this:
json
{
"counts": {
"000": 6,
"001": 13,
"010": 19,
"011": 18,
"100": 8,
"101": 14,
"110": 8,
"111": 14
},
"elapsed_time": 17.837932109832764
}Test your service locally using PLANQK CLI
To begin, navigate to your project directory:
bash
cd my-projectNext, run the following command:
bash
planqk serveOnce the server is operational, you can access http://localhost:8081/docs. This interface provides you the ability to run your current code and see the results. Further information can be found in the PLANQK CLI reference.
Open the POST / operation and click on the "Try it out" button. Paste the following JSON into the request body field:
json
{
"data": {
"n_coin_tosses": 2
}
}Click on the "Execute" button to run the service. The response body will contain the ID of the service execution. Copy the ID to your clipboard.
Open the GET /{id} operation and click on the "Try it out" button. Paste the ID into the id field and click on the "Execute" button. You can use this endpoint to check the status of the service execution. If the status is SUCCEEDED, you can retrieve the result.
Open the GET /{id}/result operation and click on the "Try it out" button. Paste the ID into the id field and click on the "Execute" button. The response body will contain the result of the service execution, similar to this:
json
{
"counts": {
"10": 30,
"11": 25,
"00": 24,
"01": 21
},
"elapsed_time": 11.129297733306885,
"_links": {
"status": {
"href": "/5b25134c-dd05-47a0-9c12-ff9816074936"
}
},
"_embedded": {
"status": {
"id": "5b25134c-dd05-47a0-9c12-ff9816074936",
"status": "SUCCEEDED",
"created_at": "2025-03-24 11:16:20",
"started_at": "2025-03-24 11:16:20",
"ended_at": "2025-03-24 11:16:32"
}
}
}Press Ctrl+C to stop the local server.
Deploy your service
To deploy your service to Kipu Quantum Hub, run the following command in your project directory:
bash
planqk upThis will compress your project directory and upload it. After a successful deployment, you will find the service in the Services section.
Alternatively, you can create a ZIP file of your project and upload it manually to the platform:
bash
planqk compressBoth commands, planqk up and planqk compress consider the definitions from the .planqkignore file to exclude files and directories from being uploaded or compressed.
Execute your service
Execute your service with the example input data stored in input/data.json and input/params.json by running the following command:
bash
planqk runAfter a successful execution, the output should look like this:
Running Job (a7a3422b-9522-408b-96c9-32cdb497b12b)... Job succeeded.
See result at https://dashboard.hub.kipu-quantum.com/jobs/a7a3422b-9522-408b-96c9-32cdb497b12bFor more details and options of the planqk run command, see the CLI reference.
What's next?
play_arrow