Programming distributed applications with NetQMPI over the CUNQA emulator — from monolithic circuits to multi-QPU networks.
As quantum hardware matures, the physical limits of a single Quantum Processing Unit (QPU) — qubit count, coherence time, cross-talk, cooling, wiring — make monolithic scaling increasingly difficult. Distributed Quantum Computing (DQC) connects multiple QPUs through quantum networks to form one larger computational cluster.
An MPI-inspired, backend-agnostic Python library for Distributed Quantum Computing. Following a Single-Program, Multiple-Data (SPMD) model, one script runs across N quantum nodes, coordinated through quantum-aware primitives — qsend, qrecv and quantum collectives — so entanglement, teleportation and classical messaging never need manual orchestration.
A Distributed Quantum Computing emulator built for HPC infrastructure. CUNQA provisions virtual QPUs (vQPUs) directly through the job scheduler (Slurm), letting you raise a multi-QPU network on a real supercomputer and model its noise and latency — the engine NetQMPI programs run on in this tutorial.
CESGA-Quantum-Spain/cunqaQuantum software engineers, HPC researchers transitioning to quantum architectures, computer science graduate students, and computational scientists looking to future-proof their skills for the multi-QPU era.
Bring the background below — everything else arrives pre-installed. NetQMPI, CUNQA, Slurm and Jupyter all live inside a single Docker image that turns your laptop into a small HPC cluster.
One Docker image, four commands. It ships NetQMPI, the CUNQA emulator, Slurm and Jupyter already wired together, so the cluster you work on during the tutorial runs on your own laptop — no remote accounts, no VPN, nothing to compile.
✓ Ready — pull it before you travel Open the setup guideEvery exercise runs inside a single Docker image that ships NetQMPI, the CUNQA emulator and a working Slurm installation, wired together as a miniature HPC cluster on your own machine. No supercomputer account, no VPN, no dependency hunting — install Docker, pull the image, run it. And if Docker refuses to cooperate with your laptop, Plan B puts the same image in the cloud.
qsend, qrecv and friends.
qraise provisions vQPUs just like on Qmio.
This is the only thing you install on your own system. Pick your operating system below — the whole process takes about ten minutes, most of it downloading.
docker group lets you drop sudo. Log out and back in — or run newgrp docker — for it to take effect.hello-world container is the standard smoke test: if it prints its greeting, the daemon is running and you are done.# 1 — install the Docker Engine curl -fsSL https://get.docker.com | sudo sh # 2 — use Docker without sudo (log out and back in afterwards) sudo usermod -aG docker "$USER" # 3 — check the installation docker run --rm hello-world
docker.io package, prefer the script above — the tutorial image needs Docker 20.10 or newer.
wsl --install and reboot. Windows 10 21H2+ or Windows 11 required, with virtualization enabled in the BIOS.docker command needs it.# 1 — enable WSL 2 (Administrator PowerShell), then reboot wsl --install # 2 — after installing Docker Desktop, check the installation docker run --rm hello-world
cmd.exe, which quotes arguments differently.
uname -m tells you which you have: arm64 or x86_64..dmg, drag Docker into Applications, launch it and accept the privileged-helper prompt. Homebrew users can do the same with one command (below).amd64 build, and Rosetta is what makes it run at a sensible speed.# optional — install Docker Desktop with Homebrew instead of the .dmg brew install --cask docker # which build do you need? arm64 = Apple silicon, x86_64 = Intel uname -m # check the installation docker run --rm hello-world
--platform linux/amd64 to the pull and run commands in the next steps. CUNQA is compiled for x86-64, so it runs under emulation here — and if it will not start at all, take Plan B instead.
The image is published on Docker Hub, already built for you — nothing is compiled on your machine.
docker pull jvazquezperez/cunqa_netqmpi:latest
One command boots munge, slurmctld, slurmd and a Jupyter server inside the container, and drops you into a shell on the head node of your very own cluster.
docker run --rm -it -p 8888:8888 --name qce26 jvazquezperez/cunqa_netqmpi:latest
-p 8888:8888. The Jupyter server runs inside the container and listens on port 8888 there. Publishing that port is what connects it to port 8888 on your own machine; without it the container starts fine, but http://localhost:8888 stays dead and there is no way into the notebooks from your browser.
Two variants worth knowing:
# keep your notebooks on the host after the container exits docker run --rm -it -p 8888:8888 -v "$PWD/work:/home/tutorial/work" jvazquezperez/cunqa_netqmpi:latest # Apple silicon (M1–M4): run the amd64 image under Rosetta docker run --rm -it --platform linux/amd64 -p 8888:8888 jvazquezperez/cunqa_netqmpi:latest
On startup the container prints the address of its Jupyter server. Open it in your browser — the token is cunqa — and the tutorial notebooks are waiting for you.
A last sanity check, from the container shell — or from a Jupyter terminal, or from docker exec -it qce26 bash:
$ sinfo PARTITION AVAIL TIMELIMIT NODES STATE NODELIST debug* up infinite 1 idle 7c41ab93f2e5 $ srun -N1 hostname 7c41ab93f2e5
debug in state idle means Slurm is alive and CUNQA can raise vQPUs on it with qraise. That is Exercise 0 done — you are ready for the tutorial.
CUNQA is compiled for x86-64. On an ARM laptop, on a machine where Docker Desktop never gets past the installer, or behind a corporate policy that blocks virtualization, the image may simply refuse to run — and there is nothing you can do about it from your side on the day of the tutorial.
So run it on someone else's x86-64 machine instead. Railway deploys the very same published image, hands you an HTTPS address, and the tutorial opens in your browser. About five minutes, no terminal, nothing installed on your laptop.
Go to railway.com and sign up — GitHub is the quickest route. New accounts get a one-time $5 trial credit, valid for 30 days and with no card required, which is far more than a two-session tutorial consumes.
railway.app address redirects to railway.com — the dashboard is the same, only the domain changed. Deployed services still get a *.up.railway.app URL.
From the dashboard, hit New Project — or New inside an existing project, or Ctrl/⌘ + K for the command palette — and choose Docker Image. Paste the image name, tag included, and deploy. Nothing is built: Railway pulls the very same image from Docker Hub that the Docker path uses, on its own fast network.
jvazquezperez/cunqa_netqmpi:latest. Watch the Deploy Logs tab: when the lines [entrypoint] munge OK and [entrypoint] Jupyter: http://localhost:8888/… scroll past, your cluster is up.
The container is running, but nothing reaches it yet. Open the service, go to Settings → Networking → Public Networking and click Generate Domain. When it asks for the port, answer 8888 — the port the Jupyter server listens on inside the container, exactly the same number that -p 8888:8888 publishes on the Docker path.
PORT = 8888 settles it for good.
cunqa, which is fine on your laptop and careless on the open internet. In Variables, add JUPYTER_TOKEN with a secret of your own and use that one in the URL below.
Take the domain Railway just generated and add the token to it. That is the whole setup — the notebooks, Slurm and CUNQA are already there, running on an x86-64 machine that is not yours.
There is no docker exec here, so run the Exercise 0 check from a Jupyter terminal — New → Terminal in the file browser:
$ sinfo PARTITION AVAIL TIMELIMIT NODES STATE NODELIST debug* up infinite 1 idle 3f9a1c02b7de $ srun -N1 hostname 3f9a1c02b7de
qraise dies on memory, raise fewer vQPUs or drop a couple of qubits./home/tutorial/work.Two 90-minute sessions on Friday, September 18, 2026, split by a 90-minute lunch break — six exercises take you from a first distributed Bell pair to a distributed Quantum Fourier Transform.
Real, runnable snippets from the two open-source libraries — the same shape of code you'll write during the hands-on exercises.
from netqmpi.sdk.environment import Environment def main(env: Environment = None): comm = env.comm rank = comm.rank next_rank = comm.get_next_rank(rank) previous_rank = comm.get_prev_rank(rank) with comm: # everything inside runs on the selected backend if rank == 0: circuit = env.create_circuit(num_qubits=1, num_clbits=1) circuit.h(0) # prepare |+> comm.qsend(circuit, [0], next_rank) # teleport the qubit else: circuit = env.create_circuit(num_qubits=1, num_clbits=1) comm.qrecv(circuit, [0], previous_rank) circuit.measure(0, 0) results = comm.results if rank != 0: print(f"measure: {results}")
comm.qsend() / comm.qrecv() — entanglement generation, teleportation and classical corrections are handled by whichever backend adapter you select. This exact file runs unchanged on the CUNQA backend used in this tutorial.
$ netqmpi -n 2 send_recv.py --cunqa --shots 1024
View on GitHub →
# Raising 4 virtual QPUs (vQPUs) for this job from cunqa.qpu import qraise, get_QPUs, run from cunqa.circuit import CunqaCircuit from cunqa.qjob import gather family = qraise(4, "01:00:00", simulator="Aer", co_located=True) qpus = get_QPUs(co_located=True) # A 2-qubit Bell circuit, sent to every vQPU qc = CunqaCircuit(num_qubits=2) qc.h(0) qc.cx(0, 1) qc.measure_all() qjobs = run([qc] * 4, qpus, shots=1000) results = gather(qjobs) for r in results: print(f"Counts: {r.counts}") # e.g. {'00': 512, '11': 488}
qraise provisions vQPUs straight from the Slurm job scheduler; get_QPUs hands you live handles to run circuits on. This is the emulation layer NetQMPI targets with its --cunqa backend flag.
$ python3 quickstart.py && qdrop --all
View on GitHub →
This tutorial is delivered jointly by researchers from CiTIUS (Universidade de Santiago de Compostela) and CESGA, the Galicia Supercomputing Center.
CiTIUS — the Centro Singular de Investigación en Tecnoloxías Intelixentes — is the Universidade de Santiago de Compostela's (USC) research center for intelligent technologies, spanning computer vision, trustworthy AI, high-performance computing, robotics and quantum computing. Founded in 1495, USC is one of the oldest universities in the Spanish-speaking world and CiTIUS's host institution.
Visit CiTIUS
CESGA — the Galicia Supercomputing Center — has been at the service of scientific advancement since 1993, as a node of the Spanish Supercomputing Network (RES). Through the Quantum Spain initiative, CESGA operates the 32-qubit Qmio quantum computer and develops CUNQA within its HPC infrastructure.
Visit CESGA
CESGA
Predoctoral researcher at the intersection of HPC and quantum computing, and lead developer of the CUNQA emulator. Experienced in leading technical workshops on advanced computing architectures.

CiTIUS · USC
Postdoctoral researcher specializing in distributed quantum computing and heterogeneous architectures. Creator and lead author of NetQMPI, translating the classical MPI paradigm into the quantum realm.

CiTIUS · USC
Full Professor at USC and senior CiTIUS researcher with decades of experience in HPC, parallel programming and computer architecture, and director of numerous national and European research projects.
NetQMPI and CUNQA are the outcome of publicly funded research. This tutorial acknowledges the programmes and grants that made them possible.
CUNQA has been developed with the financial support of Quantum Spain — Spain's Quantum Computing Ecosystem for AI — financed by the Ministerio para la Transformación Digital y de la Función Pública through the Quantum ENIA project, within the Recovery, Transformation and Resilience Plan – NextGenerationEU, under the Digital Spain 2026 Agenda.
About Quantum Spain
Further supported by the DeepQuantum project, contributing new knowledge, algorithms and tools to High Performance Quantum Computing.
MICIU / AEI / 10.13039/501100011033 / FEDER, UE
About DeepQuantum
The peer-reviewed and preprint work behind NetQMPI and CUNQA, for attendees who want to go deeper than the hands-on exercises.