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.

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:

npm install -g @planqk/planqk-cli

TIP

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:

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.

First of all, install the Quantum SDK:

pip install --upgrade planqk-quantum

IMPORTANT

You need Python 3.11 or higher to use the Quantum SDK.

To run a Qiskit program, all you need is an account and three lines of Quantum code:

from planqk.quantum.sdk import PlanqkQuantumProvider
...
qiskit_circuit = ... # create your Qiskit circuit here
...
provider = PlanqkQuantumProvider(access_token="YOUR_PERSONAL_ACCESS_TOKEN_HERE")
result = provider.get_backend("azure.ionq.simulator").run(qiskit_circuit, shots=100).result()

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:

provider = PlanqkQuantumProvider()

Example: Coin Toss

Next, we build a circuit (quantum algorithm) that performs n coin tosses on a Quantum Computer. Instead of heads and tails, we work with 0s and 1s. This means, there will be 2^n possible outcomes, and each time (number of shots) we measure the quantum state, we observe one of these outcomes.

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(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()

A possible outcome of the coin toss quantum algorithm could be:

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:

planqk init

You 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:

{
  "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:

cd my-project

Then, 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:

uv venv
uv sync

source .venv/bin/activate

Open the src/program.py file, modify the following line and enter your personal access token:

provider = PlanqkQuantumProvider(access_token="YOUR_PERSONAL_ACCESS_TOKEN_HERE")

Finally, run your service locally:

python -m src

The output should look like this:

{
  "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:

cd my-project

Next, run the following command:

planqk serve

Once 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:

{
  "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:

{
  "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:

planqk up

This 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:

planqk compress

Both 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:

planqk run

After 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-32cdb497b12b

For more details and options of the planqk run command, see the CLI reference.

What's next?

play_arrow

Discover our Quantum Backends

Learn about our supported quantum backends and how to use them.school

Explore our Tutorials

Check out our tutorials to get started with quantum computing on Kipu Quantum Hub.code

Deep Dive into the Quantum SDK

Learn how to use our SDK to interact with our supported quantum backends.code

Get Started with the Service SDK

Learn how to interact with your deployed services using Python.