Kipu Quantum Hub Quickstart

This quickstart gets you from an empty folder to a quantum job on the Kipu Quantum Hub in about fifteen minutes. The job runs on the Hub, not on your laptop, and it stays in your job history after your script ends. You need Python 3.11 or newer, Node.js 20 or newer, and a free Hub account.

:::steps:::

1Step 1: Install the SDK and the CLI

First up: a Python project with the Hub SDK. We use uv here; any Python package manager works.

uv init kipu-hub-quickstart
cd kipu-hub-quickstart
uv venv
uv add qhub-quantum

qhub-quantum brings Qiskit with it, so there is nothing else to install on the Python side.

Then the CLI, qhubctl. It ships on npm:

npm install -g @quantum-hub/qhubctl

1a. Log in with your access token

Copy your personal access token from the Hub home page, then log in:

qhubctl login -t <your access token>

That writes the token to ~/.config/qhubctl/config.json, where the SDK finds it. Your code never has to hold the token. Reference: Manage access tokens.

2Step 2: Run a circuit on the Hub

A quantum coin toss: two qubits in superposition, then a measurement. Save it as coin_toss.py.

# coin_toss.py
from qhub.quantum.sdk import HubQiskitProvider
from qiskit import QuantumCircuit, transpile

BACKEND_ID = 'kipu.sim.qsim'   # free simulator
SHOTS = 100

circuit = QuantumCircuit(2)
circuit.h(0)
circuit.h(1)
circuit.measure_all()

provider = HubQiskitProvider()
backend = provider.get_backend(BACKEND_ID)
job = backend.run(transpile(circuit, backend), shots=SHOTS)
print(f'Job id: {job.id}')

job.wait_for_final_state()
print(job.result().get_counts())
# -> four outcomes, 00, 01, 10 and 11, each near 25 of the 100 shots.
#    Your counts will differ from run to run.

Run it:

uv run python coin_toss.py

It worked if you see a job id and four outcomes in roughly equal shares. Two fair coins, tossed 100 times. The simulator runs jobs in a queue, so the wait can take a few minutes.

Submission is asynchronous. backend.run() hands the job to the Hub and returns at once; only wait_for_final_state() keeps your script waiting. For a long experiment you can drop that line, close the laptop, and collect the result later.

kipu.sim.qsim and azure.ionq.simulator are free. To run on a real quantum computer, change BACKEND_ID; QPUs need an account with active payment information. Quantum Backends lists the IDs your account can reach.

3Step 3: Find your job again

Every job lands in one history on the Hub, whichever machine or script sent it. With the id that coin_toss.py printed, you can fetch the result later, from any machine where you are logged in:

# fetch_job.py
from qhub.quantum.sdk import HubQiskitProvider

JOB_ID = '<the job id coin_toss.py printed>'

provider = HubQiskitProvider()
job = provider.retrieve_job(JOB_ID)
print(job.status())
print(job.result().get_counts())
# -> JobStatus.DONE and the same counts as in Step 2

Or open Quantum Workloads in the Hub, filter by the job id, and use Retrieve Inputs & Results. Reference: Managing quantum jobs.

Where next

• Understand what you just ran. Technical 01 builds an entangled circuit step by step and maps the stack it runs on.
• Ship your code as a service. Technical 04 takes a program from qhubctl init to a deployed Hub service with qhubctl up.
• Solve an optimization problem. The Quantum Optimization Quickstart runs Iskay or Miray in a few lines.