Appearance
Quickstart
This page provides a crash course on using PLANQK 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 PLANQK CLI
To install the PLANQK 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 PLANQK 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 PLANQK, run planqk set-context and select the organization you want to work with.
Run your first quantum program
The PLANQK Quantum SDK provides an easy way to develop quantum circuits that can be executed on quantum backends/devices available through PLANQK. 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 PLANQK Quantum SDK:
shell
pip install --upgrade planqk-quantumIMPORTANT
You need Python 3.11 or higher to use the PLANQK Quantum SDK.
To run a Qiskit program, all you need is an account and three lines of PLANQK Quantum code:
python
from planqk.qiskit 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 PLANQK CLI to log in and authenticate with PLANQK. Then, you can use the PlanqkQuantumProvider without specifying the access token:
python
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.
python
from planqk.qiskit 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://platform.planqk.de/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 PLANQK 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 PLANQK. The Python Starter templates implement the coin toss example from above as a PLANQK 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 PLANQK. 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 the PLANQK Platform, run the following command in your project directory:
bash
planqk upThis will compress your project directory and upload it to the PLANQK Platform. 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 PLANQK:
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://platform.planqk.de/jobs/a7a3422b-9522-408b-96c9-32cdb497b12bFor more details and options of the planqk run command, see the CLI reference.
What's next?
play_arrow