Why we parallelise
Distributed computing is not an advanced optimisation technique you reach for once everything else is exhausted. It is the direct consequence of two physical limits that were hit two decades ago and have not been lifted since. It is worth starting there, because those same two limits reappear — under a different vocabulary — the moment we start connecting several QPUs.
1.1 Dennard scaling and its end
In 1974, Robert Dennard and his co-authors formulated the rule that governed microprocessor design for thirty years.19 Simplified: if you shrink a transistor’s linear dimensions by a factor k and scale the supply voltage proportionally, the power density per unit area stays constant. Translated into practical consequences: every new process generation gave you more transistors and more clock frequency without paying more watts per square millimetre.
That was the free lunch. A programmer could write sequential code and trust that, without touching a line, it would run faster on next year’s hardware. This was not a marketing promise: it was a physical property of scaling.
Dennard scaling breaks down around 2004–2006. The immediate reason is that transistor threshold voltage cannot keep dropping without leakage current exploding, at which point static power starts to dominate the thermal budget. From then on, raising frequency means raising power superlinearly, and power becomes the binding constraint on design.
Precision of vocabulary matters here, because this is the most common error when telling the story: what broke was not Moore’s law, it was Dennard scaling. Transistor count per chip has kept growing. What stopped growing was what you could do with them while keeping a single thread of execution. The industry’s answer was replication: if you cannot make one core faster, add more cores. And the moment there is more than one core, performance stops being the manufacturer’s problem and becomes the programmer’s.
The four curves share a single logarithmic axis and arbitrary per-series units: what matters is not the absolute value but the shape. The transistor curve does not bend. The frequency curve flattens around 2005 and has been essentially horizontal ever since. The core-count curve sits at 1 for thirty-four years and takes off at precisely the point where frequency stops. Schematic order-of-magnitude values; for auditable figures see Rupp’s microprocessor trend dataset.20
1.2 The memory wall
The second limit is independent of the first and, in current practice, more binding. Wulf and McKee named it in 1995 in a four-page paper whose argument still holds thirty years later.18 The observation is simple: compute speed and main-memory latency have improved at radically different rates. Memory bandwidth has grown respectably; latency, barely at all. A DRAM access still costs on the order of tens to hundreds of clock cycles, just as it did decades ago.
The consequence is formalised through arithmetic intensity: the number of floating-point operations you perform per byte moved from memory. If your algorithm has low arithmetic intensity, it does not matter how many FLOPS your machine has — you will be limited by data movement, not by computation. On modern accelerators the break-even point sits on the order of tens of FLOP per byte, which leaves most scientific computational kernels on the memory-bound side. The roofline model is the standard tool for visualising this and appears in any serious treatment of the subject.17
The operational lesson, worth committing to memory because it reappears almost unchanged in the quantum part: moving a datum costs more than operating on it. All parallel algorithm design is, at bottom, about reorganising the computation to move less.
Anatomy of a distributed system
Before distributing work you need to know what you are distributing it over. The physical hierarchy of a supercomputer determines which operations are cheap and which are expensive, and that hierarchy is what the programming model then reflects — sometimes badly.
2.1 The physical hierarchy
From the inside out, a contemporary supercomputer is organised in four levels:
- Core: the execution unit. It has its own registers and first-level caches.
- Socket: a physical package grouping tens of cores with a shared last-level cache and a memory controller.
- Node: a board with one or more sockets, its DRAM and, increasingly, accelerators (GPUs and — this is the field’s bet — QPUs). Everything inside a node shares an address space.
- Cluster: the set of nodes joined by a low-latency interconnect. Between nodes there is no shared memory.
That last sentence is the hinge of the whole course. The node boundary is the address-space boundary, and crossing it requires an explicit communication mechanism. Inside the node you can use threads and shared variables; outside, you must send messages.
Inside a node, cores share memory and communication is implicit: writing a variable suffices. Crossing to another node requires packing, sending and receiving. Note the accelerator drawn in node 1: the HPC-QC integration thesis is exactly this, treating the QPU as one more accelerator within the existing hierarchy.1
2.2 Shared memory versus distributed memory
Two programming models with opposite properties follow from this hierarchy.
Under shared memory all threads see the same addresses. Communicating means writing to a variable; there is no explicit transfer cost. In exchange, race conditions appear, synchronisation is required (locks, barriers, critical sections), and the model does not scale beyond the node. OpenMP is the reference standard.
Under distributed memory each process has its own private address space. There are no data races because there are no shared data; in exchange, all communication is explicit and carries a cost the programmer must account for. The model scales to hundreds of thousands of processes. MPI is the reference standard.15
In practice real codes are hybrid: MPI between nodes, OpenMP or CUDA within. But for our purposes the relevant model is pure distributed memory, because that is what describes a QPU network: each quantum node has its own qubit register and there is no mechanism by which another node reads that register directly. Distributed memory is not a design choice in distributed quantum computing; it is the only possible topology.
How work gets divided
Given a problem and N processors, there are essentially two ways to divide it. The choice between them is not cosmetic: it determines the resulting communication pattern, and the communication pattern determines performance.
3.1 Data decomposition
You partition the problem domain and every process runs the same code on its share. This is the dominant strategy in scientific computing: finite-difference meshes, dense matrices, bodies in a gravitational simulation, pixels of an image. Each process knows its block, operates on it, and only needs to communicate at the block boundaries — what domain-decomposition practitioners call halo or ghost-cell exchange.
Its properties: the code is single and independent of N; communication is concentrated at discrete moments (an initial distribution, a boundary exchange per iteration, a final reduction); and it scales well as long as the local block is large compared with its boundary, that is, as long as the volume-to-surface ratio is favourable.
3.2 Task decomposition
You partition the stages of the computation and data flow through them. Each process does something different. This is the pipeline model: acquire, filter, transform, write. It is also the model of irregular task graphs.
Its properties are almost complementary: the code differs per rank, communication is continuous rather than discrete, and overall performance is set by the slowest stage, not by the sum of stages. Balancing a pipeline is harder than balancing a domain, because stages rarely cost the same.
3.3 The happy case: embarrassingly parallel
The degenerate limit of data decomposition, when inter-process communication is zero. Monte Carlo sampling, parameter sweeps, evaluating the same circuit with different seeds. There are no boundaries to exchange because the shares are independent. Scaling is linear by construction and the only cost is the final aggregation of results.
The axis separating the two strategies is not «data» versus «tasks» but the communication pattern each induces. On the left, communication concentrated at the ends and proportional to block size. On the right, continuous communication dominated by the latency of small messages. These are two distinct regimes of the cost model introduced in chapter 5.
How much there is to gain
There is an upper bound on what parallelisation can give you, and that bound is set by the part of the program that refuses to parallelise. The two classical formulations of that bound do not contradict each other: they answer different questions.
4.1 Amdahl’s law
Gene Amdahl laid out in 1967 the argument that still tempers expectations.16 Let s be the fraction of execution time that is intrinsically sequential and 1−s the parallelisable fraction. With N processors, the speedup is
S(N) = 1 / ( s + (1 − s)/N )
As N tends to infinity the second term vanishes and we are left with S ≤ 1/s. With 5 % sequential, the maximum speedup achievable with infinitely many processors is 20×. With 25 %, it is 4×. No hardware fixes that.
The correct reading of Amdahl is not «parallelising is not worth it». It is «identify and attack the serial fraction before buying more nodes». In practice that fraction is almost never pure computation: it is usually I/O, initialisation, global synchronisation and — very much in particular — communication.
4.2 Gustafson’s law
John Gustafson observed in 1988 that Amdahl assumes something that is almost never true: that problem size is fixed.16 Nobody buys a supercomputer to solve the same problem faster; they buy it to solve a larger problem in the same time. If you grow the problem as you grow N, the parallelisable fraction grows with it while the serial part stays roughly constant. The scaled speedup becomes
S(N) = s + (1 − s) · N
which is linear in N and unbounded. Both laws are true; they describe different scenarios.
The same serial fraction yields opposite diagnoses depending on what is held fixed. With the problem frozen (left), 25 % sequential makes going beyond eight processors pointless. With the problem scaling (right), that same fraction keeps paying off up to sixty-four. Before quoting either law you must declare which of the two experiments you are running.
4.3 Strong and weak scaling
The two laws above have an experimental counterpart, and these are the only two plots a reviewer will look at in a performance paper:
- Strong scaling: problem size held constant while N increases. You measure execution time. This is Amdahl’s experiment. Its curve always bends eventually, because as N grows the local work shrinks and communication comes to dominate.
- Weak scaling: problem size per process held constant, so the total problem grows with N. You measure whether the time stays flat. This is Gustafson’s experiment.
Impeccable weak scaling alongside dismal strong scaling is entirely possible, and it is a common situation. Presenting only one of the two is the most common way to dress up a performance result.
What communication costs
This is the chapter to understand properly, because it is the only one in Part I that carries over to the quantum domain almost unmodified. Everything else adapts; this applies.
5.1 The latency–bandwidth model
The cost of sending an n-byte message between two processes is modelled, to first order, with two parameters:
T(n) = α + β·n
where α is latency — the fixed cost of initiating the transfer, independent of size — and β is the inverse of bandwidth, the marginal cost per byte. On a modern high-performance network, α sits in the range of one to a few microseconds and 1/β in the tens or hundreds of gigabits per second.
From this model comes the most useful quantity in the chapter: the half-power message size, n½ = α/β. It is the message size at which the fixed cost equals the variable cost, and therefore the point where you reach half the asymptotic bandwidth. Below n½ you are paying mostly latency and the network is essentially idle; above it, you start to exploit real bandwidth.
The design consequence is blunt, and counterintuitive to anyone coming from serial programming: sending a thousand one-kilobyte messages is dramatically worse than sending one one-megabyte message, even though the total volume is identical. Message aggregation is almost always the first optimisation to apply to a distributed code that performs badly.
The same model seen two ways. On the left, the intercept α is the toll paid per message sent, whatever its size. On the right, the consequence: below the half-power size the network delivers a negligible fraction of its nominal capacity. Horizontal-axis values are illustrative; the actual n½ is measured empirically with a ping-pong test.
5.2 Granularity and the communication-to-computation ratio
Granularity is the amount of work a process does between two consecutive communications. Fine grain means a lot of communication and little computation between messages; coarse grain, the reverse.
The metric governing scaling is the ratio of communication time to computation time. As N grows with the problem fixed, work per process falls while the number of messages usually rises, so this ratio inevitably worsens. That is the physical mechanism behind Amdahl’s ceiling: it is not that some mystical fragment of sequential code exists, it is that communication grows until it eats the benefit.
5.3 Classic pathologies
Four failures that appear systematically in distributed code and are worth naming before writing the first line of MPI:
| Pathology | What happens and how to avoid it |
|---|---|
| Deadlock | Two processes each wait for a message the other has not yet sent. Avoided by ordering the operations, using combined primitives, or switching to non-blocking communication. |
| Load imbalance | One process takes longer than the rest and everyone waits at the next barrier. Total time is set by the slowest, not the average. |
| Over-synchronisation | Unnecessary global barriers that effectively serialise the program. Every barrier is a serial fraction handed to Amdahl for free. |
| Grain too fine | Many small messages, all below n½. The network runs at 5 % of nominal capacity and the performance profile looks inexplicable. |
MPI: SPMD, rank and communicator
MPI is not a library: it is an interface specification, maintained by the MPI Forum, with multiple independent implementations — Open MPI, MPICH, and vendor variants.<Ref n={15} /> That it is a standard rather than a product is why code written in 1996 still compiles and runs on machines that did not exist then. In Python, access to the standard goes through `mpi4py`.<Ref n={21} />
6.1 The SPMD paradigm
The idea holding up the whole edifice is called Single Program, Multiple Data. You write one source file. The launcher starts N copies of that same program as independent processes and injects a distinct identifier into each. The program reads that identifier and decides which branch of its own logic to execute.
It is worth underlining why this is a design choice and not an obvious one. The alternative — MPMD, writing one program per role — seems more natural at first and produces unreadable code the moment there are more than three participants: going from three to four nodes means writing a new file and modifying the existing ones. SPMD decouples the code from the number of processes. That decoupling is, literally, NetQMPI’s central argument, which is why it is worth insisting on here.
One file; N processes. The value of rank is the only thing that differs between them, and on that single difference the program’s entire asymmetry of roles is built. Going from three to thirty-two processes touches not one line of source: only the launcher argument.
6.2 Rank: logical identity
The rank is an integer in [0, size−1] assigned to each process within a communicator. It is not a node number, nor an operating-system process id, nor a network address. It is a logical label, and that is precisely its virtue: the program reasons about ranks and delegates the correspondence with physical resources to the runtime environment.
By universal convention, rank 0 acts as coordinator when one is needed — reading files, distributing work, collecting results. It is a convention, not a rule of the standard; in MPI, rank 0 holds no privilege.
6.3 Communicator: the communication context
A communicator encapsulates two things: a group of processes and an isolated communication context. Every message is sent within a communicator, and messages from different contexts never get confused with each other — a property that makes it possible to write safe parallel libraries without fear of colliding with the messages of the program using them.
At start-up there is MPI_COMM_WORLD, containing every launched process. Sub-communicators can be derived to group processes by criteria of your own.
The conceptual reading that matters for what follows: the communicator is a virtualisation layer. It presents the programmer with a set of participants numbered 0 to N−1 on top of what is in reality a heterogeneous set of physical resources connected by a specific topology. The program is written against the logical view; the mapping is resolved by the system.
The dotted lines cross deliberately. Two ranks being consecutive does not mean they sit on the same node or that communication between them is cheap: the mapping is decided by the scheduler according to its allocation policy. This separation between logical identity and physical resource is identical to the one NetQMPI’s QMPICommunicator introduces when associating ranks with QPUs.2
from mpi4py import MPI
comm = MPI.COMM_WORLD
rank = comm.Get_rank() # who am I
size = comm.Get_size() # how many are we
name = MPI.Get_processor_name()
print(f"I am rank {rank} of {size}, on {name}")
Run it with mpirun -n 4 python hello.py. In mpi4py there is no need to call Init or Finalize: importing the module initialises the environment and finalisation is registered automatically when the interpreter exits.
Point-to-point communication
MPI's elementary operation is sending a message from one rank to another. Everything else — collectives included — can be built on top of it.
7.1 Send and Recv
A send specifies the destination, and a receive specifies the source. Both carry a tag that distinguishes different messages between the same pair of processes, and both occur within a communicator. A receive matches a send only if source, destination, tag and communicator all agree.
from mpi4py import MPI
comm = MPI.COMM_WORLD
rank = comm.Get_rank()
if rank == 0:
data = {"iteration": 7, "residual": 1e-6}
comm.send(data, dest=1, tag=11)
elif rank == 1:
data = comm.recv(source=0, tag=11)
print("received:", data)
7.2 Blocking versus non-blocking
Blocking operations (send, recv) do not return until it is safe to reuse the buffer. Non-blocking ones (Isend, Irecv) return immediately with a request object, and the program must later wait with Wait or poll with Test. Non-blocking calls allow overlapping communication with computation — start sending, do useful work while the message travels, and wait only when the data is needed — which is the standard technique for hiding the α latency from the previous chapter.
7.3 Deadlock: the canonical error
Consider a boundary exchange between two neighbours, written in the apparently most natural way: each process sends first and receives afterwards. If the MPI implementation lacks sufficient buffering — and with large messages it will — send blocks until the recipient executes its recv. But the recipient is blocked in its own send, waiting for the same thing. Neither will ever reach its recv.
What makes this failure pernicious is that it can pass in testing and hang in production: with small messages the implementation buffers them internally and send returns, hiding the error. The program is incorrect either way; it simply does not manifest until the problem size grows.
Three valid solutions to the same problem, in order of preference: use Sendrecv, which delegates safe ordering to the implementation; use non-blocking communication with Isend/Irecv followed by Waitall; or manually alternate the order by rank parity, as the right-hand panel shows. The third works but is fragile and does not generalise well to complex topologies.
Collective operations
A collective is an operation in which *every* process of a communicator takes part. All must invoke it; if one omits it, the program hangs. In exchange, collectives express common communication patterns in a single call and let the implementation use optimal algorithms — binomial trees, ring algorithms — instead of the naive loop a user would write.
8.1 The fundamental four
Each row is a rank and each cell a buffer slot. Bcast copies; Scatter and Gather move; Reduce combines with an associative operator (sum, max, product…). This distinction between copying, moving and combining is what determines which collectives survive the transition to the quantum domain and which do not.
Variants worth knowing: Allgather leaves the result of a Gather on every process rather than only the root; Allreduce does the same for Reduce and is probably the most used collective in the standard; Barrier synchronises without transferring data; and Scatterv/Gatherv accept unequal chunk sizes, which is necessary when the element count is not divisible by the process count.
Exercises with mpi4py
Four exercises in increasing order of difficulty. The third is optional; the fourth is the one that connects with the second half of the tutorial and is worth doing even if the others do not fit.
from mpi4py import MPI
import numpy as np
comm = MPI.COMM_WORLD
rank, size = comm.Get_rank(), comm.Get_size()
N = 1_000_000
assert N % size == 0, "use Scatterv if N is not divisible"
local_n = N // size
# only the root materialises the full vectors
if rank == 0:
a = np.arange(N, dtype=np.float64)
b = np.ones(N, dtype=np.float64)
c = np.empty(N, dtype=np.float64)
else:
a = b = c = None
a_local = np.empty(local_n, dtype=np.float64)
b_local = np.empty(local_n, dtype=np.float64)
comm.Scatter(a, a_local, root=0) # hand out
comm.Scatter(b, b_local, root=0)
c_local = a_local + b_local # purely local computation
comm.Gather(c_local, c, root=0) # collect
if rank == 0:
print("correct:", np.allclose(c, np.arange(N) + 1.0))
Discussion points when going over it. First: Scatter with a capital S, because the data are NumPy arrays and we do not want pickle serialising them. Second: non-root processes pass None as the send buffer, which is correct — only the root needs to hold it. Third, and this is the important pedagogical point: this program accelerates nothing. Vector addition has negligible arithmetic intensity, so the time is dominated by the Scatter and the Gather. It is an exercise in API mechanics, not in performance, and saying so out loud avoids creating a false expectation.
partial = np.array(np.dot(a_local, b_local))
total = np.empty(1) if rank == 0 else None
comm.Reduce(partial, total, op=MPI.SUM, root=0)
It is worth pointing out here that the floating-point result may differ from the sequential one, because floating-point addition is not associative and the accumulation order depends on the reduction’s internal algorithm. This is not a bug in the program: it is a property of distributed computation that surprises many people the first time.
REPS = 200
for nbytes in [8, 64, 512, 4096, 32768, 262144, 2097152]:
buf = np.zeros(nbytes // 8, dtype=np.float64)
comm.Barrier()
t0 = MPI.Wtime()
for _ in range(REPS):
if rank == 0:
comm.Send(buf, dest=1); comm.Recv(buf, source=1)
elif rank == 1:
comm.Recv(buf, source=0); comm.Send(buf, dest=0)
dt = (MPI.Wtime() - t0) / (2 * REPS)
if rank == 0:
print(f"{nbytes:>9} B {dt*1e6:8.2f} us {nbytes/dt/1e9:7.2f} GB/s")
This is the exercise with the highest pedagogical return per minute invested, because it produces concrete numbers from the machine in use and makes chapter 5 tangible. And it has a second life: in the quantum part of the tutorial you can pose the equivalent — measure the time to establish an EPR pair and compare it with a local gate — so the attendee sees from their own data how many orders of magnitude separate the two costs.
What breaks in the quantum domain
Everything above carries over. But it does not carry over for free: four properties we took for granted in MPI stop being true, and from those four breakages come all of NetQMPI's design decisions. This chapter is the axis of the tutorial.
10.1 No-cloning eliminates broadcast
There is no physical operation that, given an arbitrary and unknown quantum state |ψ⟩, produces two independent copies |ψ⟩⊗|ψ⟩. The proof is three lines and follows from the linearity of quantum mechanics. The consequence for us is brutal in its simplicity: MPI_Bcast has no quantum equivalent. It is not expensive, nor merely unimplemented: it is forbidden.
This is not a minor API detail. It is precisely the objection levelled at the theoretical QMPI proposal of Häner and co-authors, which defined the semantics of a quantum MPI but did not resolve how to express the collectives that imply copying.4 Any library claiming to be a «quantum MPI» must answer this question, and NetQMPI’s answer — the expose and unexpose primitives — is detailed in chapter 13.
The difference is not one of efficiency but of ontology. On the left there would be four independent states; on the right there is one, whose degrees of freedom are spread across four nodes. No node owns the state, and measuring at any of them instantly affects what the others will see. It is a shared resource, not a replicated datum.
10.2 The other three breakages
| MPI assumption | What happens in the quantum case |
|---|---|
| Reading does not destroy | Measuring a qubit collapses its state. There is no «inspect the buffer without consuming it» operation, which is the basis of all classical debugging. Debugging a distributed quantum program is qualitatively harder, and this alone justifies an abstraction layer that reduces the code surface. |
| The channel is reusable | Every transfer consumes an entangled pair, which disappears on use. «Bandwidth» is not a sustained rate but an inventory of resources that must be generated, distributed and accounted for. |
| A delayed message is still valid | Entanglement degrades over time through decoherence. There is a deadline. A correct-but-slow protocol can be an incorrect protocol in practice, because the fidelity of the state on arrival is no longer acceptable. |
10.3 What does not change: the classical control plane
A common misunderstanding is worth defusing early. Transferring a qubit between nodes is done by teleportation, and teleportation is not an alternative to classical communication: it requires it. The protocol consumes a previously distributed EPR pair, the sender performs a Bell measurement on their qubit and their half of the pair, and sends two classical bits over a conventional channel. Without those two bits the receiver does not know which Pauli correction to apply and their qubit is garbage.
So a quantum network is always a double network: a quantum plane distributing entanglement and a classical plane carrying measurement outcomes and synchronisation. Any library abstracting this must manage both, and half the verbosity of the NetQASM SDK comes precisely from having to orchestrate both by hand.6
The software stack
Before looking at code it is worth locating each piece. The software ecosystem for quantum networks is stratified much like the HPC one, and confusing the levels is the main source of misunderstanding.
11.1 The levels
From the bottom up:
- Discrete-event simulators. NetSquid models the physics: photon emission, fibre loss, memory decoherence, timing.7 SeQUeNCe does the same with more emphasis on the network layer and routing.10 These are tools for network architects, not application programmers: the code is dominated by hardware definitions.
- NetQASM, a low-level, platform-independent instruction set architecture for hybrid classical-quantum programs in a quantum internet.6 It plays the role an ISA plays in classical computing: it decouples software from hardware. Its Python SDK offers the EPR socket abstraction.
- Execution backends. SquidASM translates NetQASM into NetSquid events, giving physically realistic simulation. SimulaQron runs each node as a separate process communicating over sockets, imposing a strict memory separation that is very useful for validating distributed logic.8
- NetQMPI, the layer we are concerned with: middleware over the NetQASM SDK adding the SPMD paradigm, the communicator and the semantic primitives.2
Alongside this stack there are high-level tools with different philosophies — QuNetSim, with a very accessible centralised API but no path to real hardware;9 Interlinq, which automates circuit partitioning23 — and, at the intermediate-representation level, NetQIR, an extension of QIR for distributed quantum computing developed by the same group behind NetQMPI and the origin of the expose/unexpose primitives.3
NetQMPI rests on the NetQASM SDK and therefore on its backends. CUNQA is an independent development aimed at emulating distributed QPUs inside a real HPC environment, with its own API and its three communication models.1 That both are combined in the tutorial’s title requires making explicit where they connect.
NetQMPI: the interface
With the frame in place, the API almost explains itself: it is MPI with the constraints of chapter 10 applied. What is interesting is not the syntax but what it chooses to hide and what it chooses to expose.
12.1 The problem it solves
The NetQASM SDK follows a role-based model: one file per participant — app_alice.py, app_bob.py, app_charlie.py. Moreover, it offers no qubit-transfer primitive: to move a state you must implement teleportation by hand, step by step, including creating the EPR socket, the local gates, the measurement, sending the bits over a separate classical socket and applying corrections at the receiver. And you must call flush() manually to synchronise the quantum flow.2
The result, measured on the case study of chapter 14, is that the number of files grows with N and socket instantiation grows as N² in fully connected topologies. That is the cost NetQMPI removes.
12.2 Rank injection and communicator creation
The user writes a main function taking rank and size. The library injects them at run time, exactly as mpirun does with MPI processes. The entry point for all functionality is the QMPICommunicator.
from netqmpi.sdk.communicator import QMPICommunicator
def main(app_config=None, rank=0, size=1):
# rank and size are injected by NetQMPI at start-up
COMM_WORLD = QMPICommunicator(rank, size, app_config)
print(f"hello, I am rank {rank} of {size}")
And it is launched with a command-line interface deliberately modelled on MPI’s:
$ netqmpi -n 3 script.py
hello, I am rank 0 of 3
hello, I am rank 2 of 3
hello, I am rank 1 of 3
The parallel with mpirun -n 3 is visually obvious and worth exploiting in the presentation: an attendee who has just done exercise 0 recognises the structure immediately, unordered output included.
What the communicator automates on construction: it assigns the logical rank, walks the network configuration instantiating the necessary mesh of EPRSocket objects between participants, and stores those sockets in an internal routing table. It also manages quantum control-flow synchronisation, with implicit flushes inside the primitives and an explicit flush() available when needed.2 The programmer stops seeing sockets.
12.3 qsend and qrecv
The two point-to-point primitives encapsulate the full teleportation protocol. From the programmer’s point of view the operation is «send this qubit to that rank» and nothing more: no EPR pairs, no fidelities, no QPU identifiers, no classical signalling.
It is worth unfolding this diagram in the presentation rather than merely saying the library «handles it for you». An abstraction whose interior has not been shown reads as magic, and with a research audience that costs credibility. Note too that the original qubit is destroyed by the measurement in step 2: teleportation moves the state rather than duplicating it, and is therefore compatible with no-cloning.
def main(app_config=None, rank=0, size=2):
comm = QMPICommunicator(rank, size, app_config)
if rank == 0:
q = Qubit(comm.connection)
q.H() # prepare |+>
comm.qsend(q, 1) # no EPR management
print("rank 0: qubit sent")
elif rank == 1:
q = comm.qrecv(0) # returns the already-corrected state
m = q.measure()
print(f"rank 1: received, measurement = {m}")
The structural symmetry with the classical example — same if rank == 0, same send/receive pair — is deliberate and is the library’s central pedagogical argument: if you know MPI, you can already read this.
Quantum collectives
This is where the analogy with MPI stops being comfortable and must be broken explicitly. Copying MPI's list of collectives and prefixing a «q» does not work, because two of the fundamental four are not physically realisable.
13.1 The survivors: qscatter and qgather
qscatter takes a list of qubits at the root process and distributes them, one per rank in the communicator. qgather performs the inverse. Both are legitimate because they move states rather than copying them, and their implementation is a loop of point-to-point operations: a qscatter is equivalent to the root running one qsend per destination rank.2
It is worth being honest about this in the presentation: in their current form they are syntactic sugar over point-to-point, not optimised collectives with tree algorithms like MPI’s. That is a real difference from the classical standard and an obvious line of future work.
def main(app_config=None, rank=0, size=4):
comm = QMPICommunicator(rank, size, app_config)
conn = comm.connection
ROOT = 0
qubits = []
if rank == ROOT:
qubits = [Qubit(conn) for _ in range(size)]
for q in qubits:
q.H()
conn.flush()
local_qs = comm.qscatter(qubits, ROOT) # returns this rank's qubit
m = local_qs[0].measure()
conn.flush()
print(f"rank {rank}: measured {m}")
13.2 The one that does not exist: Bcast
From chapter 10 it follows that there is no qbcast and there cannot be one. The theoretical QMPI proposal left this gap unresolved, and it is its most-cited limitation.4
13.3 NetQMPI’s answer: expose and unexpose
Instead of copying, NetQMPI distributes. The expose primitive, taken from the NetQIR architectural framework,3 transforms a state residing at the root
|ψ⟩ = α|0⟩R₀ + β|1⟩R₀
into a global state spread across all participating ranks
α (|0⟩R₀ ⊗ … ⊗ |0⟩Rₙ) + β (|1⟩R₀ ⊗ … ⊗ |1⟩Rₙ)
The implementation entangles the root’s qubit with a pre-shared GHZ state across all nodes, followed by local measurements and classical corrections.2 The result is not a copy: it is a single state whose degrees of freedom are distributed. Collective controlled operations can be run on it, which is the use it was designed for.
Hence the counterpart: because the operation alters the accessibility scope of the qubits, releasing the resource when finished is mandatory. unexpose returns the system to a consistent state in which the qubits are private to their owner again. This is not politeness: it is resource release, and omitting it leaves the communicator inconsistent. The right analogy is not Bcast but the acquire/release pair of a lock.
The full cycle. Between steps 2 and 3 is where the algorithm does its work, applying controlled operations on the distributed quantum information. Omitting unexpose is the quantum equivalent of a memory leak, with the aggravating factor that the leaked resource also degrades through decoherence.
13.4 Correspondence table
| MPI | NetQMPI | Comment |
|---|---|---|
Send / Recv |
qsend / qrecv |
Direct correspondence. Internally teleportation, and the original state is destroyed. |
Scatter / Gather |
qscatter / qgather |
Direct correspondence. Implemented as point-to-point loops. |
Bcast |
— | Does not exist. Forbidden by the no-cloning theorem. Its functional place is taken by expose, with different semantics: it spreads rather than replicates. |
Reduce / Allreduce |
— | Would require measuring to obtain combinable values, destroying the superposition. Reducing classical post-measurement results is possible, but that is already classical MPI. |
Barrier |
flush() |
Not exact equivalents: flush synchronises the quantum instruction stream, it is not a process barrier. |
Case study: the distributed GHZ state
Generating a Greenberger–Horne–Zeilinger state shared across N nodes is the «hello world» of the quantum internet: it requires multipartite entanglement and coordinated control, which is why it serves as a benchmark for comparing tools.<Ref n={2} />
14.1 The protocol
The goal is the maximally entangled state |GHZ⟩ = (|00…0⟩ + |11…1⟩)/√2 shared among N distinct nodes. The conceptual protocol has three steps: a root node prepares a qubit in superposition by applying a Hadamard gate; it then executes a sequence of CNOTs whose control is its qubit and whose targets live on the remaining N−1 nodes; and, since there is no shared memory, each of those CNOTs is remote and requires underneath a teleportation or entanglement-swapping protocol with its corresponding classical communication and corrections.
The logical circuit is trivial: one Hadamard and N−1 CNOT gates. What is not trivial is that none of those CNOTs can run locally, because control and target sit on different machines. All of the problem’s complexity is hidden inside the dashed boxes, and it is exactly that complexity which the various tools handle more or less gracefully.
14.2 The same task, two tools
In NetQMPI the program is a single file whose logic does not depend on N. The expose primitive takes care of the remote CNOTs and the underlying entanglement distribution.
def main(app_config=None, rank=0, size=3):
comm = QMPICommunicator(rank, size, app_config)
# 1 · the root creates the base qubit in superposition
qubits = []
q = Qubit(comm.connection)
if rank == 0:
q.H()
qubits.append(q)
# 2 · collective operation: spreads the remote CNOT control
comm.expose(qubits, root_rank=0)
# 3 · local operations on the non-root ranks
if rank != 0:
qubits[0].cnot(my_qubit)
# 4 · release the resource: mandatory
comm.unexpose(root_rank=0)
Going from three to fifty nodes means typing netqmpi -n 50. The source is untouched.
The contrast with the raw SDK is the most effective visual argument in the whole block. In the NetQASM SDK the logic is split strictly by role: three nodes need three files, socket creation is explicit and pairwise, and the remote CNOT is not a native primitive but a protocol to implement by hand.
# --- app_alice.py (root) ---
sock_bob = EPRSocket("Bob") # one socket per destination
sock_charlie = EPRSocket("Charlie")
csock_bob = Socket("Alice", "Bob") # and one classical per destination
csock_charlie = Socket("Alice", "Charlie")
with NetQASMConnection("Alice", epr_sockets=[sock_bob, sock_charlie]) as c:
q = Qubit(c); q.H()
epr_b = sock_bob.create_epr()[0] # remote CNOT to Bob, by hand
q.cnot(epr_b)
m_b = epr_b.measure()
c.flush()
csock_bob.send(str(m_b))
epr_c = sock_charlie.create_epr()[0] # and the logic duplicated for Charlie
q.cnot(epr_c)
m_c = epr_c.measure()
c.flush()
csock_charlie.send(str(m_c))
# --- app_bob.py --- and --- app_charlie.py --- : separate, nearly identical files
Adding a fourth node forces you to create a new file and modify the root’s to instantiate the two extra sockets and duplicate the teleportation block once more. It is boilerplate, structurally necessary, and an inexhaustible source of copy-paste errors.
14.3 How the code scales
Qualitative trends following the published comparative analysis.2 In role-based frameworks, each new node requires a file, manual socket instantiation — which grows quadratically in fully connected topologies — and duplication of the control logic. NetQMPI keeps the curve flat because the loop lives inside the collective primitive and iterates dynamically over the communicator size.
Closing, and what is left out
The whole path, in one sentence: physical limits force replicating units; replicating units forces communicating; communicating is expensive; MPI standardised how that is programmed in the classical world through SPMD, rank and communicator; and NetQMPI carries those three abstractions into the quantum domain, adapting the primitives wherever physics forbids a literal translation.
15.1 What this block does not cover
- Fidelity and noise. The whole treatment above has been functional. The real cost of a remote operation depends on EPR pair fidelity and decoherence rates, and NetSquid exists precisely to model that.7
- Circuit partitioning. Given a monolithic circuit and N QPUs, how do you split it while minimising remote gates? It is a combinatorial optimisation problem and an active research line.24
- Real network topology. Full connectivity has been assumed. A realistic quantum network has routers, repeaters and entanglement swapping, and the communicator hides — for now — that structure.13
- Emulator comparison. There is specific work benchmarking distributed quantum computing emulators that is worth consulting before choosing a tool.22
15.2 Link to the second half of the tutorial
CUNQA’s three communication models — no communication, classical communication and quantum communication — map neatly onto the three situations described in Part I: the embarrassingly parallel case, the exchange of scalar results, and the movement of state. Quantum phase estimation, the algorithm used to demonstrate the emulator in the literature,1 exercises all three.
If the attendee takes away one idea from this ninety minutes, let it be this: distributed quantum computing is distributed computing, with a harsher communication cost model and one physical prohibition — no-cloning — that removes one of the four fundamental collectives. Everything else transfers.
What CUNQA emulates
Part III finished with an interface and nothing underneath it. CUNQA is what goes underneath — or rather, the emulated infrastructure that stands in for a machine nobody can yet buy. Knowing exactly what it replicates faithfully and what it merely reproduces behaviourally is the difference between reading its output correctly and over-reading it.
16.1 Emulation is not simulation
The two words are used interchangeably and they are not the same thing. Emulation aims to replicate a system faithfully; simulation aims to reproduce its behaviour. In classical computing, emulating a device means translating the instructions of the emulated machine into native instructions of the host. That route is closed for a quantum computer: there are no classical instructions to translate a quantum one into, because the computing paradigms do not share a vocabulary. What is left is the approach Willsch set out — have the classical counterpart solve the physical equations governing the quantum system, so its behaviour is reproduced rather than its instructions translated.26
CUNQA applies both notions, at different heights of the stack.1
- At the architectural level it emulates. QPUs are first-class components, deployed and queried through the same interfaces a physical installation would expose. Their integration into the HPC system is also designed to mimic faithfully how an actual QPU would be integrated.
- At the device level it simulates. Third-party libraries reproduce the outcome of the quantum tasks; the channels reproduce the effect of the links on what they carry.
In one sentence: CUNQA emulates DQC infrastructures whose QPUs and communication channels are simulated in order to execute the quantum tasks.
The split is what licenses the word «emulator» even when every channel is ideal. What is replicated is the structure: processes that own their resources, are scheduled, queried and addressed exactly as an accelerator of the machine would be. What is reproduced is the physics, and physics is delegated. Noise belongs to the lower half — it is a behavioural property, not a structural one — which is why a perfect-fidelity channel is still a first-class channel.
16.2 The two kinds of noise
Because noise sits at the device level, it splits along the same line as the components:
- Device noise. Gate and qubit errors — decoherence, readout. Supported, but under a restriction that will be made precise in chapter 17: only when AerSimulator runs the shots loop unassisted.
- Communication noise. Latency on the links, entanglement fidelity, heralded loss, memory decoherence while entanglement is distributed. Not modelled in version 3.0.0. The channels are ideal.1
16.3 Where the QPUs sit
There are three ways to place a QPU relative to an HPC installation, following the classification of Elsharkawy et al.27 with the two co-located variants merged:
| Model | What it means | CUNQA |
|---|---|---|
| Standalone | No HPC integration at all; the environment is purely quantum. | Discarded — it falls outside the accelerator paradigm. |
| Co-located | The QPUs live inside the HPC environment but separate from the classical nodes. | Supported, via the --co-located flag. |
| On-node | The QPUs are devices of a classical node, like a GPU. | Supported, and the default. |
The choice is not cosmetic: it decides which nodes can reach a given vQPU, and therefore how the job you launch in chapter 18 must be sized.
16.4 The three communication models
These are the same three situations Part I described in classical terms, and chapter 15 already anticipated the correspondence:
- No communication. Independent QPUs. This is the embarrassingly parallel case of chapter 3: different quantum tasks on different QPUs, in parallel, with no exchange.
- Classical communication. QPUs exchange classical bits at run time. Structurally identical to the previous one, except that a QPU may now receive classical information mid-execution and condition an instruction on it. This introduces the synchronisation problem the previous model did not have — and, with it, the deadlock risk of chapter 7.
- Quantum communication. QPUs are entangled through a quantum channel while keeping the classical link. This is the model that lets several limited QPUs act as one larger machine, and it is the one the vendor roadmaps point at.
To the best of the authors’ knowledge, CUNQA is the only tool that emulates DQC infrastructures with all three models inside an HPC environment.1 The HPCQC integration frameworks — QFw, MQSS, QCCP, XACC — expose no inter-QPU communication model at all; the quantum-network tools — NetSquid, SeQUeNCe, QuISP, SimulaQron, QuNetSim — offer full communication but no HPC integration.22 CUNQA occupies the intersection, and pays for it in noise modelling, which is where those network tools are strongest.
16.5 Why you manage the resources yourself
There are two ways to draw a quantum software stack. In the usual one, resource management lives inside the middleware and is opaque to the user. CUNQA deliberately takes the other: resource management is the user’s responsibility and sits outside the execution workflow.1
The reasoning is HPC practice rather than quantum computing. Compute time on a shared machine is an accounted resource governed per user by the scheduler. A tool that allocated resources on its own would spend an allocation without the restraint its owner would have applied — greedily rather than deliberately. The consequence for the programmer is the two-step workflow of chapter 18: first you raise the infrastructure, then you run against it.
The vQPU
The infrastructure of chapter 16 is made of one repeated unit. A virtual QPU is not a simulator instance that appears when you call it and vanishes when it returns: it is a process that exists, holds resources, and is queried — and that distinction is the whole point.
17.1 What a vQPU is
A vQPU is a process running in an HPC environment, with its own allocated set of classical resources, that stands in for a real QPU in the system and executes the quantum tasks submitted to it.1 The concept is not entirely new — Claudino et al. worked with virtualised quantum accelerators before32 — but the emphasis here is on ownership: because the vQPU owns its resources, its lifetime is independent of the tasks that run on it.
That independence is what makes it behave like hardware. You can ask whether it is up, ask what it is made of, send it work, and send it more work later. From the programmer’s seat it is another accelerator that happens to be in the machine, exactly like a GPU or an FPGA: it receives tasks, executes them, and returns results.
The contrast with the usual quantum-simulation workflow is worth making explicit on a slide. AerSimulator() is an object you construct inside your script; a vQPU is a job that was already running before your script started and will still be running after it ends.
17.2 Three components
Server, backend and simulator. The first two are what makes the vQPU addressable as a device; the third is what makes it compute. Server and simulator are decoupled from any specific third-party implementation, so the underlying libraries can be swapped or extended; the backend is fixed within a CUNQA version but is trivially editable to expose new QPU characteristics.
- Server. Connects the vQPU to the user: receives quantum tasks, queues them, returns results. A conventional client–server structure over a standard socket library — Asio or ZMQ in the current version.
- Backend. Holds what the user needs to know about the simulated QPU: coupling map, number of qubits, basis gates, noise model, and — under the quantum-communication model — the communication qubits. Some fields are generic; others only acquire meaning under a particular DQC model.
- Simulator. Does the actual execution. Version 3.0.0 supports seven: six third-party — AerSimulator, MQT-DDSIM, Maestro, Qulacs, Qsim, QuEST — and CunqaSimulator, a lightweight one written inside the project for testing.1
17.3 How execution changes with the model
This is the part that surprises people. The DQC model being emulated does not only determine what the user may write: it changes how the system executes underneath.
No communication. Nothing changes with respect to an ordinary circuit run. The simulator does all the work and CUNQA treats it as a black box. There is exactly one exception: a classical if on a gate — CIF. Most simulators do not support it, so CUNQA takes over, runs the shots loop itself, and checks the control bit classically before deciding whether to apply the gate.
That exception is the origin of the noise restriction announced in chapter 16. Noise modelling relies on AerSimulator, which injects noise at the simulator level with no documented mechanism for doing it gate by gate. The moment CUNQA takes the shots loop, the simulator’s noise machinery is bypassed. Hence: noisy vQPUs exist only where AerSimulator runs unassisted — no communication, and no CIF.1
Classical communication. The same reasoning applies for the same reason: no supported simulator understands communication directives. SEND and RECV are therefore executed inside a shots loop that CUNQA controls, through an extra element in the simulator component — the classical communication channel, available over ZMQ or MPI.
Quantum communication. Here the scheme above breaks down entirely. Both previous models rest on the same unstated assumption: each vQPU holds its own state, so each can run its own shots loop and the only thing crossing between them is classical. A quantum channel breaks that assumption at the root — once two vQPUs are entangled they no longer have two states, they have one — and no arrangement of independent simulators can represent a state that does not decompose. Something other than the vQPUs has to do the executing, which is what the next section is about.
17.4 The centralised executor
Under no- and classical-communication, each vQPU simulates its own state independently: the distribution is purely classical. Under quantum communication that stops being possible. Quantum protocols between vQPUs can entangle their qubits, and an entangled state is by definition not separable — so the state of all participating vQPUs must be simulated as a single state.
The consequence is structural. A single state needs a single executor aware of every operation, because an operation aimed at one vQPU may affect another. So in this model the vQPUs stop being executors and become proxies: they keep the interface a user would have with a real system, forward instructions to a centralised executor, and hand back that executor’s results.
The same infrastructure, executing in two different ways. Above, the two models of chapter 16 that need no quantum channel: three vQPUs, three states, three executors, and only classical bits crossing between them. Below, what quantum communication forces: one joint state, therefore one executor, and vQPUs reduced to the interface. Nothing changes in what the user writes — the proxies expose exactly what the executors exposed — and everything changes in what runs underneath.
The centralised executor accepts every directive of the two previous models plus one of its own: GEN_ENT, the generation of an entangled state between QPUs. With a centralised executor, generating entanglement is nothing more than preparing a GHZ state across the selected communication qubits — but defining it as an atomic instruction lets CUNQA lift it out of the stream of quantum operations, which is what makes entanglement generation and communication-qubit bookkeeping modellable at all. It was chosen as the semantic minimum of a quantum communication: every known quantum-communication protocol needs it as a building block.11
17.5 Data qubits and communication qubits
The quantum-communication model introduces a backend field the other two do not have. Communication qubits are a subset of a vQPU’s qubits reserved exclusively for communication with other vQPUs, as opposed to data qubits, which do the computing. The distinction goes back to the earliest work on distributed quantum computing31 and has been kept ever since.11
CUNQA adopts it for two reasons. The first is fidelity to the state of the art. The second is management: separating the two resources means that asking for more communication qubits than the machine has stalls execution until some are freed, rather than silently eating the data qubits. Nothing prevents a user who dislikes the split from simply using communication qubits as data qubits.
Raising the infrastructure
Three commands cover the whole life cycle of a vQPU. They are C++ programs exposed as Bash commands and implemented as SLURM wrappers, which is the honest way of saying that CUNQA does not invent a resource manager: it borrows the one the machine already has.
18.1 Reserve first, execute after
The stack model of chapter 16 has a direct operational consequence: by the time your Python program runs, the quantum resources must already exist. There is no lazy allocation, no implicit start-up, no «if no vQPU is available, spawn one». The workflow has two separate steps, and they are separate on purpose.
The full cycle. qraise submits a job that keeps N vQPUs alive for a bounded wall time; qinfo reports what is up; the Python program of chapter 19 attaches to the running vQPUs through get_QPUs, submits work and collects results; qdrop frees everything. Note that the program may be run many times against the same raised infrastructure, and that forgetting qdrop burns allocation until the wall clock expires.
18.2 qraise
Two flags are mandatory: how many vQPUs, and for how long.
$ qraise -n 4 -t 00:10:00
Each invocation deploys a family: a homogeneous group of vQPUs sharing one configuration. Running qraise twice gives you two families, which may differ in every respect — number of qubits, simulator, DQC model — and which can coexist in the same session. Families are how a heterogeneous infrastructure is assembled out of homogeneous pieces.
18.3 The optional flags
They fall into five groups, which map exactly onto the five things a DQC infrastructure has to decide.1
| Group | Flags | What it decides |
|---|---|---|
| Simulated QPU | --backend, --infrastructure |
Qubit counts (data and communication), coupling map, supported instructions, noise properties. --backend takes a JSON file and deploys homogeneous vQPUs; --infrastructure takes a JSON file listing one backend per vQPU, for heterogeneous deployments. |
| Simulator | --sim |
Which of the seven simulators runs the tasks. Defaults to AerSimulator. |
| Classical resources | --cores-per-qpu, --mem-per-qpu, --n-nodes |
Passed through to SLURM. This is where a vQPU stops being an abstraction and starts costing money. |
| DQC model | --classical_comm, --quantum_comm |
Neither: no communication. One of them: that model. |
| Integration and identity | --co-located, --family |
Whether the vQPUs are reachable from any node or only from the one hosting them; and a name to address the group by. |
Noise properties — T₁, T₂ and the rest — are declared in the backend JSON and turned into a noise model with Qiskit. The restriction of chapter 17 applies here in its operational form: a noisy vQPU requires no communication, no CIF, and AerSimulator. Ask for noise outside those conditions and you will not get the noise.
18.4 qdrop and qinfo
qdrop wraps SLURM’s scancel. It frees everything raised, with --all, or one family, with --family followed by the name.
$ qdrop --family qft_demo # one family
$ qdrop --all # everything you raised
qinfo reports the vQPUs currently active in the system: which families exist, what they are made of, and whether they are reachable from where you are. It is the first thing to run when a program cannot find any QPU, and the second thing to run when it finds the wrong ones.
18.5 The same commands from Python
All three are also exposed in the Python API. This is explicitly not the intended main workflow — it exists so that a single script can handle both management and execution when that is convenient, without abandoning the stack model in which the two remain conceptually separate.
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)
The cunqa package
With the infrastructure up, the Python API covers two things and only two: designing distributed quantum tasks, and executing them. The design side is where the DQC directives live; the execution side is deliberately thin.
19.1 CunqaCircuit
The design entry point is a class whose constructor should look familiar to anyone who has written Qiskit:
from cunqa.circuit import CunqaCircuit
circuit = CunqaCircuit(num_qubits=3, num_clbits=3, id="circuit_id")
The id is not decoration. Under any communication model, circuits address each other by identifier, not by rank or by QPU: a send names the receiving circuit, an entanglement generation names the circuits it entangles. This is a genuine difference from MPI, where the addressee is a rank in a communicator, and it is worth flagging early because it is the first thing that trips up someone arriving from Part II.
Beyond the usual catalogue of local gates, the class implements the communication directives.
19.2 Classical communication: send, recv, cif
Two circuits, one identified as the sender and one as the receiver. The sender pushes the contents of one or more classical registers; the receiver declares in advance where they will land.
send_circuit.send(clbits=sending_cregs, recving_circuit="recving_circuit_id")
recv_circuit.recv(clbits=recving_cregs, sending_circuit="sending_circuit_id")
A received bit is only useful if something can be conditioned on it, which is what cif / endcif provide: a classically controlled block that applies the enclosed gates when the control bit is 1.
recv blocks. This is the same semantics as MPI_Recv in chapter 7, with the same consequence: a chain of receives that each wait on the previous one serialises the computation, and a cycle of them deadlocks. Chapter 20 shows a case where this is not a bug but the algorithm’s actual structure.
19.3 Quantum communication: gen_ent
Circuits that will communicate quantum information must distinguish their two kinds of qubit, and they do so by passing an ordered pair as num_qubits:
circuit_0 = CunqaCircuit(num_qubits=(3, 2), num_clbits=3, id="circuit_0_id")
circuit_1 = CunqaCircuit(num_qubits=(1, 1), num_clbits=1, id="circuit_1_id")
Entanglement is then generated by both circuits calling gen_ent consistently — each naming the other:
circuit_0.gen_ent(comm_qubit=1, circuits="circuit_1_id")
circuit_1.gen_ent(comm_qubit=0, circuits="circuit_0_id")
Two circuits give a Bell pair. A consistent list of circuit identifiers in the circuits argument gives a GHZ state shared among all their communication qubits. This is the GEN_ENT directive of chapter 17 seen from the application layer, and it is the building block from which any quantum-communication protocol can be assembled.
19.4 The two protocols you do not have to write
You are not required to build protocols from gen_ent. The two standard ones ship with the library.1
- Teledata — quantum teleportation — moves the state of a data qubit from one circuit to another. Provided by
qsendandqrecv. - Telegate — quantum gate teleportation — shares the state of a control qubit with a communication qubit of a remote circuit so that a local gate placed in between acts as a non-local controlled gate. Provided by
cat_entanglerandcat_disentangler.
In both cases the entanglement generation, the classical corrections and the communication-qubit bookkeeping happen inside. The programmer writes the boundaries of the protocol and the operation that goes between them.
19.5 Composing circuits
Three free functions build large circuits out of small ones, which matters more than it sounds when the circuits are the units you distribute:
addcomposes in depth: the instructions of the first operand followed by those of the second.unioncomposes in width: the registers of the first operand carrying its gates, then those of the second carrying its own.hsplitinvertsunion: it cuts a circuit along the register axis into subcircuits acting on contiguous blocks, given either a partition size or an explicit set of cut points.
hsplit is the closest thing in the API to automatic circuit partitioning, and it is worth being precise about what it is not: it cuts where you tell it to. Deciding where to cut so as to minimise remote gates is the open problem chapter 15 listed as left out.24
19.6 Execution
Connecting to the raised infrastructure returns a list of handles:
from cunqa.qpu import get_QPUs, run
from cunqa.qjob import gather
qpus = get_QPUs(co_located=True, family="qft_demo")
qjobs = run(circuits, qpus, shots=1000)
results = gather(qjobs)
for r in results:
print(r.counts, r.time_taken)
Four things are worth stating explicitly about that block.
get_QPUsfilters, it does not create.co_locateddecides whether vQPUs on other nodes are visible;familyselects by the name given atqraisetime. Both concepts were fixed in chapter 18.runassigns circuits to vQPUs in list order. That is the whole scheduling algorithm. It is a deliberate placeholder: trivial, predictable, and leaving room for a real scheduler on top.runis asynchronous. It dispatches and returns oneQJobper circuit. Results arrive throughQJob.result— aResultwithcountsandtime_taken— or in bulk throughgather.upgrade_parametersupdates the values of a parametric circuit in place. For a variational algorithm running the same ansatz a thousand times with different angles, this is the difference between retransmitting the circuit and retransmitting the numbers.
19.7 What the middleware does, and why it is thin
Between the Python above and the C++ vQPUs there is a middleware whose job is deliberately small: turn a CunqaCircuit into a JSON intermediate representation with a fixed schema, and connect the user to the vQPU through a single point — a client attached to the vQPU’s server.25
Two consequences follow, and both are useful to know.
JSON was chosen for compatibility, not efficiency. Simulators such as AerSimulator already consume that kind of representation. It is also memory-inefficient compared with anything that avoids string literals, which is why chapter 26 lists a binary encoding among the roadmap items.
A single contact point means the Python layer is optional. Anyone who wants a different interface can discard the cunqa package entirely; the only requirement is to send correctly shaped JSON to the vQPU’s server. That is the door Part V walks through.
Compilation, meanwhile, is not a CUNQA concern: Qiskit transpilation is supported and leveraged, and no optimisation machinery is developed in-house. The purpose of the project is the integration of DQC into HPC, not the optimal compilation of circuits, and the middleware’s simplicity is the design decision that keeps effort pointed at the first thing.
One algorithm, three models
The cleanest way to see what each communication model does to a program is to hold the algorithm fixed and vary only the model. Quantum Phase Estimation is the one the CUNQA literature uses for exactly that reason: using a single algorithm isolates the differences the model imposes from the differences the algorithm would have imposed anyway.
20.1 The algorithm, briefly
QPE, introduced by Kitaev in 1995,30 estimates the phase φ of an eigenvalue of a unitary operator U: given U and one of its eigenvectors |ψ⟩ with U|ψ⟩ = e^(2πiφ)|ψ⟩, it returns
φ ≃ ξ / 2ⁿ, with error 1 / 2ⁿ
where n is the number of ancilla qubits and ξ is the decimal reading of the most frequent output string of the ancilla register. The circuit has two registers: the n ancillas that hold the phase, and the register holding |ψ⟩ to which the controlled powers of U are applied, followed by an inverse QFT on the ancillas.
The demonstration takes U = R_z and |ψ⟩ = |1⟩, for two practical reasons: the eigenvectors of R_z are trivial to prepare — eigenstate preparation being one of QPE’s real bottlenecks — and with |1⟩ the answer is known in advance through θ = 2πφ, so correctness is checkable rather than merely plausible.
20.2 No communication: distribute the shots
More precision means more ancillas, more possible outcomes, and therefore more shots. Nothing about the circuit needs distributing; the sampling does. This is the embarrassingly parallel case, and the code shows it: the circuit is built exactly as it would be on one machine, then replicated.
# Defining the QPE circuit
qpe = CunqaCircuit(num_qubits + 1, num_qubits)
qpe.x(num_qubits) # eigenstate |psi> = |1>
for i in range(num_qubits):
qpe.h(i)
for _ in range(2**i):
qpe.crz(phase, i, num_qubits) # controlled U^(2^i)
qpe.IQFT(0, num_qubits - 1)
qpe.measure_all()
# Obtaining available vQPUs and distributing the shots
qpus = get_QPUs()
shots_per_qpu = [shots // len(qpus) for _ in range(len(qpus))]
qjobs = run([qpe]*len(qpus), qpus, shots=shots_per_qpu)
results = gather(qjobs)
The only distributed thing in that program is the last three lines. That is the point: the no-communication model asks nothing of the algorithm.
20.3 Classical communication: the IPEA
The Iterative Phase Estimation Algorithm29 attacks the qubit cost instead of the shot cost: it extracts the binary expansion of the phase one bit at a time, using a single ancilla per circuit.
The derivation is worth doing on a slide because it turns an unfamiliar algorithm into a familiar one. The last thing acting on the ancillas before measurement is the inverse QFT — a ladder of Hadamards and controlled rotations. By the deferred measurement principle, measuring before those controlled rotations is equivalent, and it converts them into classically controlled gates. Classically controlled gates whose controls come from earlier measurements are precisely a partition point: each slice becomes an independent circuit that needs one classical bit from each of its predecessors.
qpus_QPE = get_QPUs()
num_qpus = len(qpus_QPE)
circuits = []
for i in range(num_qpus):
theta = 2 * pi * 2**(num_qpus - i - 1) * phase
circuits.append(CunqaCircuit(num_qubits=2, num_clbits=2, id=f"circuit_{i}"))
circuits[i].h(0)
circuits[i].x(1)
circuits[i].crz(theta, 0, 1) # this slice's power of U
# Receiving bits from previous circuits
for j in range(i):
circuits[i].recv(clbits=0, sending_circuit=f"circuit_{i - j - 1}")
circuits[i].cif(clbits=0)
circuits[i].rz(param=-pi * 2**(-j - 1), qubits=0)
circuits[i].endcif()
circuits[i].h(0)
# Sending bits to upcoming circuits
circuits[i].measure(0, 0)
for k in range(num_qpus - i - 1):
circuits[i].send(clbits=0, recving_circuit=f"circuit_{i + k + 1}")
circuits[i].measure(1, 1)
qjobs = run(circuits, qpus_QPE)
results = gather(qjobs)
The inner loop is the whole algorithm. recv blocks until subcircuit i − j − 1 has measured; cif/endcif apply the correction rotation R_z(−π · 2^−(j+1)) only when the received bit is 1; and the cumulative effect of all those conditional rotations reproduces the inverse QFT one bit at a time, with no extra ancillas. Then the ancilla is measured and broadcast to every later subcircuit that will need it.
The partition is legitimate for a reason worth stating: in the eigenvector register, each controlled gate leaves the register in the eigenstate, so the slices are genuinely independent of one another except through the classical bits.
20.4 Quantum communication: the register split
QPE has two registers, so the obvious quantum-communication partition is one register per vQPU. Doing that turns every controlled-U into a non-local controlled gate, which is exactly what telegate is for. The example below uses cat_entangler / cat_disentangler rather than raw gen_ent, which makes the structure legible.
ancilla_circuit = CunqaCircuit((N_ANCILLA_QUBITS, 1), N_ANCILLA_QUBITS, id="ancilla_circuit")
register_circuit = CunqaCircuit((N_REGISTER_QUBITS, 1), 1, id="register_circuit")
data_qubits_anc, comm_qubits_anc = ancilla_circuit.get_qubits()
data_qubits_reg, comm_qubits_reg = register_circuit.get_qubits()
register_circuit.x(data_qubits_reg[0]) # eigenstate |1>
for i in range(N_ANCILLA_QUBITS):
ancilla_circuit.h(data_qubits_anc[i])
for i in range(N_ANCILLA_QUBITS):
cat_entangler(
target_circuits = [ancilla_circuit, register_circuit],
data_qubit = data_qubits_anc[N_ANCILLA_QUBITS - 1 - i],
comm_qubits = [comm_qubits_anc[0], comm_qubits_reg[0]],
clbits = [0, 0],
tag = "telegate"
)
param = (2**i) * 2 * 2 * pi * PHASE_TO_COMPUTE
register_circuit.crz(param, comm_qubits_reg[0], data_qubits_reg[0])
cat_disentangler(
target_circuits = [ancilla_circuit, register_circuit],
data_qubit = data_qubits_anc[N_ANCILLA_QUBITS - 1 - i],
comm_qubits = [comm_qubits_reg[0]],
recv_clbits = [0],
send_clbits = [0]
)
ancilla_circuit.IQFT(0, N_ANCILLA_QUBITS)
ancilla_circuit.measure_all()
qjobs = run([ancilla_circuit, register_circuit], get_QPUs())
results = gather(qjobs)
The three-step pattern inside the loop is the one to keep:
cat_entanglershares the state of one ancilla qubit withregister_circuitthrough the reserved communication qubits, without destroying it. If the ancilla is α|0⟩ + β|1⟩, the joint state of that ancilla and the remote communication qubit becomes α|00⟩ + β|11⟩ with α and β unchanged — so using the communication qubit as a control is equivalent to using the ancilla as a control.- The local
crzis then an ordinary local gate insideregister_circuit. This is where the non-locality has gone: it has not disappeared, it has been paid for in advance. cat_disentanglerremoves the residual entanglement, leaving the ancilla in α′|0⟩ + β′|1⟩ and the communication qubit back in |0⟩, free for the next iteration.
Together the three realise a non-local controlled gate having exchanged only a temporary entangled pair and some classical bits — never the ancilla’s state itself.
20.5 Reading the numbers honestly
All three variants were run to estimate φ = 1/π on the QMIO cluster at CESGA, each vQPU given the same 2 cores and 30 GB, all co-located, every case repeated 100 times.1
| Model | vQPUs | Shots per vQPU | Estimated phase | Mean time (s) |
|---|---|---|---|---|
| No communication | 1 | 10⁸ | 0.3183135986328125 | 123.602 |
| No communication | 128 | 781 250 | 0.3183135986328125 | 1.267 |
| Classical communication | 16 | 10⁸ | 0.3183135986328125 | 4959.346 |
| Quantum communication | 2 | 10⁴ | 0.3183135986328125 | 5124.625 |
Two readings, and they must not be mixed up.
Correctness. Every model returns the same estimate, 0.3183135986328125 ± 0.000015, against the true 1/π = 0.31830988…. The uncertainty is 2⁻¹⁶, exactly the resolution of QPE with n = 16 ancillas, and the estimate agrees well inside it. The platform emulates all three models and gets the right answer in all three. That is the claim the table supports.
Cost. The times measure the classical wall clock spent emulating and simulating the infrastructure. They are not predictions of a physical DQC system’s runtime — the channels are ideal and carry no timing model at all — and they are not a benchmark, because benchmarking here would mostly benchmark AerSimulator. What they do show is how each model shapes the simulation:
- No communication scales. 128 vQPUs run about 100× faster than one, close to the ideal speedup line, because there is nothing to coordinate. The reason to stop at 128 is not the curve flattening but the bill: 256 cores and 3.84 TB.
- Classical communication serialises. Sixteen subcircuits could overlap, but every subcircuit i must receive a bit from each of its i predecessors, and
recvblocks. The dependency structure of the IPEA is a chain, so the partition buys nothing and the communication traffic costs plenty: 40× slower than the monolithic baseline at the same shot count. - Quantum communication is monolithic and expensive. The centralised executor takes over, the joint state is one state, and the telegate protocol inserts many extra gates. Four orders of magnitude fewer shots for a comparable wall time — a per-shot cost roughly 4 × 10⁵ times higher.
Exercises with CUNQA
Two exercises, and they are the same program twice. The first writes by hand what the NetQMPI notebook obtained from a single call; the second hands it back to NetQMPI and puts the two files side by side. What separates them is not capability — it is how many decisions are yours, and how quietly the wrong ones fail.
21.1 One family for the whole afternoon
Both exercises of this chapter and both of chapter 25 run against a single raised family. That is the point of the two-step workflow of chapter 18: raise once, attach many times, and pay no scheduler cost per run.
from cunqa.qpu import get_QPUs, qraise
FAMILY, SIZE = "netqmpi_notebook", 3
qpus = get_QPUs(co_located=True, family=FAMILY) or []
if len(qpus) < SIZE:
qraise(SIZE, "02:00:00",
simulator="Munich",
co_located=True,
quantum_comm=True, # without this there is no gen_ent
backend="notebook_apps/notebook_vqpu.json",
family=FAMILY)
qpus = get_QPUs(co_located=True, family=FAMILY) or []
The vQPU definition is the one number that decides whether the afternoon finishes. num_qubits is the pair [data, comm], and the executor simulates the whole family in one register spanning every qubit each vQPU declares — used or not.
{
"name": "netqmpi_notebook",
"num_qubits": [2, 2]
}
Two data qubits because exercise 9’s rank 0 holds a counting qubit and the eigenstate, and a family is raised from a single definition, so every other rank carries the second qubit unused. Two comm qubits because the inverse QFT of exercise 8 keeps two expose windows open at once, and an open window costs one comm qubit on every rank inside it. Four qubits times three vQPUs is a twelve-qubit register — 4096 amplitudes, 64 KiB. Read that off the definition, never off your circuit: [4, 4] across three vQPUs is 256 MiB, and [8, 8] across two is 64 GiB.
| NetQMPI derives it | You choose it | |
|---|---|---|
| Circuit id | f"rank_{rank}" |
You name them — and the names are the addresses |
| Comm qubits | Borrowed from a pool, per protocol block | Declared up front in the (data, comm) pair |
| Protocol clbits | Its own netqmpi_protocol register |
Yours to allocate, apart from your own bits |
| Pairing the two halves | A tag built from the ranks and a counter | The same string on both sides, or the run hangs |
CunqaCircuit((num_data, num_comm), num_clbits, id="...")
circuit.add_cl_register("name", n) # returns the name it used
circuit.classical_regs["name"] # the bits of that register
circuit.comm_qubits # the indices reserved for communication
qsend(circuit, data_qubit, comm_qubit, clbits, recving_circuit="<id>", tag="...")
qrecv(circuit, data_qubit, comm_qubit, clbits, control_circuit="<id>", tag="...")
Both calls need one comm qubit and two classical bits, and the tag has to match byte for byte on the two sides.
Two operational details that the API does not announce and that people lose time on.
- On a
(1, 1)circuit,comm_qubitsis[1]. Comm qubits are numbered after the data ones, andadd_cl_registerreturns the name it used, so the register looked up by that name goes straight into the call. - The spare vQPU needs a circuit. The family has three vQPUs and this program uses two. CUNQA runs one executor per family and starts a round only once every vQPU has submitted something, so the idle one does not sit the round out — it stalls it. Give it a throwaway circuit.
spare = CunqaCircuit((1, 0), 1, id="spare")
spare.measure(0, 0)
results = gather(run(circuits + [spare], qpus, shots=1024))
for result in results:
if result.id != "spare":
print(f"{result.id}: {result.counts}")
Read the counts before moving on. rank_1 splits roughly 50/50, which is what |+> looks like — and also exactly what a broken channel returning noise looks like. Swap the sender’s h(0) for an x(0) and run it again: rank 1 must then report 1 on essentially every shot. That is the test that actually distinguishes the two. rank_0 contributes nothing either way, because teleportation moves a state: by the end its data qubit is back in |0> and its only measurements are the protocol’s own.
$ netqmpi -n 2 notebook_apps/ex7_send_recv.py --cunqa --shots 1024
With exactly one family up, that is all the adapter needs: it attaches to what is running and leaves the allocation alone afterwards. Note also that two ranks ran on a three-vQPU family and nothing stalled — the adapter gave the spare vQPU a throwaway circuit, the same thing you had to know to do by hand in exercise 6. An oversized family is wasteful, never wrong.
Roughly thirty lines against six, and the difference is entirely the four rows of the table above. None of those values has a correct setting you could look up; they only have to agree between the two halves, and nothing checks that they do. That is the class of bug NetQMPI removes — not a hard one, a silent one.
Four questions to answer in writing before Part V starts:
- Who is addressed? In NetQMPI you send to a rank; in CUNQA you name a circuit identifier. Which one is the communicator, and where does it live in each model?
- When does the parallelism appear? NetQMPI launches N copies of one file, SPMD-style. CUNQA builds N circuit objects in one file and hands them to N vQPUs. Both end up with N things running — but only one of them is SPMD.
- Who reserves the resources? In NetQMPI the launcher does it as part of starting the application. In CUNQA it happened before the program existed, in a separate command, and outlives it.
- What is the unit of work? A rank executing a program, or a circuit executed on a device. This is the deepest of the four differences and the one Part V has to reconcile.
Two stacks, one contact point
Chapter 11 left a question open and flagged it as something to resolve before delivering: the tutorial's title promises «NetQMPI over CUNQA», and the two projects were published independently, each with its own stack. This chapter answers it. The short version is that the integration is a backend adapter, and that it works because both sides were built with the seam in the right place.
22.1 What each side actually is
It is worth restating the two definitions next to each other, because most of the confusion about the integration comes from assuming the two tools occupy the same level.
| NetQMPI | CUNQA | |
|---|---|---|
| What it is | A programming model: MPI’s SPMD, rank and communicator carried into the quantum domain.2 | An infrastructure emulator: vQPUs deployed on a supercomputer through the scheduler.1 |
| Level in the stack of chapter 11 | Middleware, over the NetQASM SDK. | System layer plus its own application layer. |
| What it hides | Sockets, EPR pairs, corrections, node identities. | Simulators, processes, sockets, the SLURM job. |
| What it insists you see | Ranks and the communicator. | The infrastructure: you raise it, you pay for it, you drop it. |
| Unit of work | A rank executing a program. | A circuit executed on a device. |
They are not competitors, and neither is a subset of the other. NetQMPI needs something underneath that can hold quantum state, produce entanglement between nodes and carry classical bits. CUNQA is such a something, and it happens to be the only one that runs inside a real HPC environment with all three communication models.22
22.2 The seam on the CUNQA side
Chapter 19 ended on the sentence that matters here: the middleware connects to the lower level through a single point — a client attached to the vQPU’s server — and anyone who wants a different interface can discard the cunqa Python package entirely, the only requirement being to send correctly shaped JSON to the vQPUs.1
That is not an accident of implementation; it is the reason the middleware was kept thin on purpose. An emulator whose Python API was welded to its execution layer would have to be wrapped. One whose contact point is a documented JSON schema over a socket can be targeted.
22.3 The seam on the NetQMPI side
NetQMPI has moved in the same direction. The published version of the library is described as middleware over the NetQASM SDK with SquidASM and SimulaQron as execution backends;2 the interface has since been reorganised around an explicit Environment that owns both the communicator and the circuit construction, so that the same user program runs against whichever backend the launcher selects.
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 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}")
Three things in that snippet are the integration, and they are easy to miss on a first read.
env.create_circuit(...)instead ofQubit(connection). The user no longer instantiates qubits against a live connection; they build a circuit object supplied by the environment. Which class that is depends on the backend — and on CUNQA it is aCunqaCircuit.with comm:as an execution scope. The block delimits what gets dispatched. Under a NetQASM backend this maps onto flushes; under CUNQA it maps onto assembling the circuits and callingrun.comm.resultscollects afterwards, which is exactly thegatherof chapter 19 wearing an MPI-shaped hat.
The contact point. NetQMPI keeps the whole programming model — one file, SPMD, ranks, qsend/qrecv, collectives — and delegates two things to the backend adapter: what a circuit object is, and what happens when the execution scope closes. The adapter maps ranks onto raised vQPUs, translates the primitives into CUNQA directives, and returns the counts. Everything above the dashed line is unchanged between the SquidASM backend and the CUNQA one; everything below it is chapters 17 to 19.
22.4 Why this composes rather than collides
The two abstractions being at different heights is what makes the composition clean, and it shows up in three places:
- Neither owns resource management, in the same way. NetQMPI’s launcher starts N ranks; CUNQA’s
qraisereserves N vQPUs. These are the same act performed in two vocabularies, and chapter 24 shows how the two commands line up. - Both are already backend-agnostic in the right direction. NetQMPI abstracts over what executes; CUNQA abstracts over what programs it. They meet in the middle and neither has to give up its model.
- The circuit is the natural interchange object. NetQMPI needs somewhere to accumulate gates before dispatch; CUNQA’s IR is a circuit in JSON. The impedance mismatch that could have existed — a streaming instruction model on one side, a whole-circuit model on the other — does not, because both are currently whole-circuit.
The dictionary
With the contact point identified, the backend adapter is a translation table. Most entries are one-to-one; the interesting ones are those where the translation is not literal, because those are the places where the two models genuinely disagree about the world.
23.1 Structure: rank, size, communicator
| NetQMPI | CUNQA | Notes |
|---|---|---|
rank |
position in the list returned by get_QPUs() |
run assigns circuits to vQPUs in list order (chapter 19), so the ordering is the rank assignment. Trivial, deterministic, and the place a real scheduler would eventually go. |
size |
len(get_QPUs(...)) |
Which is why it must match the -n given to qraise. See chapter 24. |
COMM_WORLD |
a family | The --family name at raise time is the closest thing CUNQA has to a communicator: a named, homogeneous group you can filter for. Sub-communicators would map onto multiple families. |
env.create_circuit(...) |
CunqaCircuit(...) |
With one difference that matters: CUNQA circuits carry an id, and the adapter has to generate one per rank and keep the rank → id map. |
with comm: closing |
run(circuits, qpus, ...) |
The execution scope becomes the dispatch call. |
comm.results |
gather(qjobs) |
Same operation, different name. |
The rank → id mapping is the single most important thing the adapter maintains, and the reason is chapter 19: NetQMPI addresses ranks, CUNQA addresses circuit identifiers. Every primitive below is, at bottom, that translation applied once.
23.2 Point to point
comm.qsend(circuit, [q], dest) → qsend (teledata) from this rank's circuit
to the circuit registered for `dest`
comm.qrecv(circuit, [q], src) → qrecv (teledata) declared on this rank's
circuit, naming the circuit of `src`
This is the cleanest entry in the whole table, because both libraries implement the same protocol and even use the same two verbs. NetQMPI’s qsend/qrecv encapsulate teleportation;2 CUNQA’s qsend/qrecv are teledata built over gen_ent.1 The adapter has to translate names and destinations, not semantics.
The classical pair is equally direct: a classical send and receive become CUNQA’s send/recv, and any conditional applied to a received bit becomes a cif/endcif block.
23.3 Collectives
| NetQMPI | CUNQA | Notes |
|---|---|---|
qscatter / qgather |
a loop of qsend / qrecv |
Both libraries already implement these as point-to-point loops (chapter 13). The translation is literal and inherits the same honest caveat: these are not tree-optimised collectives. |
expose / unexpose |
gen_ent over N circuits, then cat_entangler / cat_disentangler |
The interesting entry. See below. |
flush() |
— | No direct counterpart. See 23.4. |
Bcast |
— | Does not exist on either side, and for the same physical reason. |
expose in CUNQA terms. Chapter 13 defined expose as the transformation of a root state α|0⟩ + β|1⟩ into a single global state spread across all participating ranks, implemented by entangling the root’s qubit with a pre-shared GHZ state followed by measurements and corrections. Every one of those ingredients is a CUNQA directive:
- the pre-shared GHZ state is
gen_entcalled consistently with a list of circuit identifiers — chapter 19 said this explicitly: two circuits give a Bell pair, N circuits give a GHZ state across their communication qubits; - entangling the root’s data qubit with that state, plus the measurements and classical corrections, is
cat_entanglergeneralised from two circuits to N; unexposeiscat_disentangler, and the reason NetQMPI makes it mandatory is the reason chapter 17 gave for separating communication qubits from data qubits: the resource is finite, and a request for more communication qubits than exist stalls execution until some are freed. Skippingunexposedoes not merely leave the communicator inconsistent — on this backend it consumes a communication qubit that the nextexposewill wait for.
That last sentence is the best argument in the tutorial for why the two projects belong together: NetQMPI’s most abstract primitive acquires a concrete operational cost the moment it runs on an emulator that models resources. On a network simulator, forgetting unexpose is a correctness smell. On CUNQA it is a hang.
23.4 What does not translate cleanly
Three entries where the dictionary needs a footnote rather than a word.
flush(). In NetQMPI, flush synchronises the quantum instruction stream — it pushes accumulated NetQASM instructions to the backend. CUNQA has no instruction stream to push: a circuit is submitted whole, as JSON, and the shots loop runs inside the vQPU or inside the centralised executor. On this backend flush is therefore either a no-op or a scope boundary that triggers dispatch, and chapter 13’s warning applies with extra force: it was never a process barrier, and here it is not even a flush. This is the sharpest structural difference between the two models, and chapter 26 explains why it is expected to shrink.
Blocking semantics. NetQMPI’s qrecv blocks the rank; CUNQA’s recv blocks inside a shots loop that CUNQA controls. The observable behaviour is similar enough for programs to be correct, but the failure modes differ: an MPI-style deadlock stops N processes, while a CUNQA deadlock stalls one shots loop until the qraise wall time expires. The diagnosis is different too, and worse — which is precisely why exercise 6b asked people to see it once on purpose.
Noise. NetQMPI’s published backends are network simulators whose central contribution is physical-layer noise.7 CUNQA models no communication noise at all and only partial device noise (chapters 16 and 18). A program that runs identically on both backends will therefore not produce comparable fidelities, and reading a CUNQA run as if it were a SquidASM run is the single most likely misinterpretation of the second half of this tutorial.
23.5 The table to keep
| Concept | MPI | NetQMPI | CUNQA |
|---|---|---|---|
| Unit | process | rank | vQPU |
| Group | communicator | communicator | family |
| Launch | mpirun -n N |
netqmpi -n N |
qraise -n N -t T |
| Point to point | Send / Recv |
qsend / qrecv |
qsend / qrecv · send / recv |
| Distribute | Scatter / Gather |
qscatter / qgather |
loops of the above |
| Replicate | Bcast |
— | — |
| Spread a control | — | expose / unexpose |
gen_ent · cat_entangler / cat_disentangler |
| Entangle | — | implicit in the primitives | gen_ent — explicit and atomic |
| Synchronise | Barrier |
flush() |
scope of the shots loop |
Launching it
The dictionary of chapter 23 covers what the program says. This chapter covers what you type, which is where the two models are most visibly different: NetQMPI expects one command, CUNQA expects two, and the reason is the stack decision of chapter 16.
24.1 Two commands, not one
A NetQMPI application on its published backends is launched the way an MPI application is:
$ netqmpi -n 3 app.py
On CUNQA the infrastructure does not come into existence when the program starts — it was raised beforehand and outlives the program (chapter 18). So the sequence is:
$ qraise -n 3 -t 00:30:00 --quantum_comm --co-located --family qce26
$ qinfo
$ netqmpi -n 3 app.py --cunqa --shots 1024
$ qdrop --family qce26
Four observations that are worth a slide of their own.
-nappears twice and must agree.qraise -n 3reserves three vQPUs;netqmpi -n 3starts three ranks. If they disagree you get either idle paid-for vQPUs or ranks with nowhere to run. Chapter 23 explained why:sizeislen(get_QPUs(...)).- The DQC model is chosen at raise time, not at run time.
--quantum_commis a property of the infrastructure. A program that callsexposeagainst an infrastructure raised without it fails, and it fails at the vQPU rather than in your code. --shotsbelongs to the run, not the raise. It is an execution argument, forwarded torun(chapter 19) — the one number in the command line that is about the algorithm rather than the machine.qdropis not optional. The vQPUs live until the wall time expires whether or not anything is using them. This is the piece of the workflow with a real cost attached, and the one an audience of HPC users will judge you on.
24.2 Sizing the request
The flags of chapter 18 are where a demo lives or dies, and the sizing rule depends entirely on the model, for the reason chapter 17 gave:
| Model raised | What the vQPUs are | How to size |
|---|---|---|
| No communication | N independent simulations | Per-vQPU memory scales with the qubits of one circuit. Adding vQPUs adds throughput at linear cost. |
--classical_comm |
N independent simulations plus a message layer | Same per-vQPU sizing. The cost that grows is time, not memory, and it grows with the dependency chain rather than with N. |
--quantum_comm |
one joint state behind N proxies | Per-vQPU memory is not the right mental model: the centralised executor holds a single state whose dimension is set by the total number of qubits across participating vQPUs. |
That last row is the one to say out loud. In the quantum-communication model, going from two vQPUs of 10 qubits to four vQPUs of 10 qubits does not double the memory: it squares the state vector’s dimension twice over. A room full of people each raising four --quantum_comm vQPUs on a shared allocation is a predictable way to lose the second half of the session.
24.3 When it does not work
The failure modes are few, and they are all identifiable from the outside. This is the troubleshooting slide to have ready rather than improvise.
| Symptom | Most likely cause | Check |
|---|---|---|
| The program finds no QPUs | Nothing raised, wall time expired, or --co-located mismatch |
qinfo. If the family is listed but invisible, you are on a different node than the vQPUs and they were raised on-node. |
| Fewer ranks than expected | -n disagreement between qraise and netqmpi |
Compare the two command lines before reading any code. |
An expose hangs |
Communication qubits exhausted — a missing unexpose |
Chapter 23. The stall is by design: the request waits for a resource to be freed. |
| A program hangs with no error | A blocking recv cycle, or two halves of a transfer that do not name each other identically |
Chapter 7, exercise 6b. Nothing will diagnose this; the wall time ends it. |
| Noise flags appear to do nothing | Noise asked for outside its supported conditions | Chapters 16 and 18: no communication, no CIF, AerSimulator. |
| Runs, but absurdly slow | --quantum_comm with more qubits than intended |
Chapter 20’s fourth row is the expected behaviour, not a bug. |
Case study: a distributed QFT
The Quantum Fourier Transform across three QPUs is the exercise the whole day has been building towards. It is a good final case for a reason that has nothing to do with its fame: unlike the GHZ state of chapter 14, its remote gates are not all alike, and the ones that matter least are exactly the ones you would want to cut. The pay-off is chapter-length — the transform written for exercise 8 is reused, verbatim, as a subroutine of exercise 9.
25.1 Why the QFT partitions badly, and what that teaches
The QFT on n qubits is a ladder: a Hadamard on each qubit, followed by controlled phase rotations between that qubit and every one below it, with the rotation angle halving at each step. Two properties follow immediately, and both matter for distribution.
- It is almost all two-qubit gates, and they are all-to-all. Every qubit interacts with every other. Any partition into blocks cuts a number of gates that grows with the product of the block sizes — so the communication cost of a distributed QFT is quadratic in the cut, not linear.
- The gates that cross the cut are the weakest ones. The rotation angle between qubits j and k falls off as 2^−|j−k|, so the gates between distant qubits — precisely those most likely to cross a partition boundary — contribute the least phase. This is the basis of the approximate QFT, and it means the distributed QFT is one of the rare cases where a principled approximation dramatically reduces the number of remote operations.
That second point is worth spending a slide on, because it is the general lesson the specific exercise carries: circuit partitioning is not only a graph problem, it is an algorithmic one. Chapter 15 listed partitioning as an open research line;24 the QFT is the case where a physicist beats the graph partitioner by knowing what the gates mean.
25.2 Telegates, and why a QFT wants them
Teleporting a control across a cut and back costs two transfers each way and drags along whatever the qubit is already entangled with. So the QFT does not want to move qubits. It wants to lend them: the control stays where it is and is made available to the others through a shared GHZ state. That is a telegate, and it is what expose / unexpose do (chapter 23).
Three properties of that pair carry the whole exercise.
- They are collective, like
MPI_Bcast. Every rank in the window calls them, in the same order, which is why the calls sit outside theif rank ==branches. Ranks outside the window getNoneback and consume nothing. exposereturns the index to use as the control — the root’s own qubit on the root, a freshly reserved comm qubit on every receiver — so the non-local gate is written exactly like a local one.- Windows nest like scopes. Two can be open at once, and the inner one must close first. That is not a style rule: it is the reason the vQPU of chapter 21 was raised with two comm qubits rather than one.
25.3 The shape of the program
Three ranks, one data qubit each, and the inverse transform rather than the forward one:
H(q2) · CP(q2→q1, −π/2) · H(q1) · CP(q2→q0, −π/4) · CP(q1→q0, −π/2) · H(q0)
Reversing the order is what makes it an exercise rather than a transcription, and it forces two things the forward transform does not.
q2’s Hadamard comes first, before it is lent to anybody — the mirror of the forward transform, where it came last.q1is a receiver and then a lender, so its window opens insideq2’s and therefore has to close before it. Rank 0 sits inside both at once, which is where the second comm qubit of chapter 21 goes.
The structure to point at is the pairing: every expose has an unexpose, innermost first, with the non-local gates between them. Chapter 23 explained why that pairing is stricter on this backend than on any other — the communication qubit released by unexpose is the one the next window will ask for.
Note also what a window costs: one GHZ state, however many rotations happen inside it. Rank 2’s control is used twice, by two different ranks, for the price of lending it once. Teleporting q2 back and forth would have meant four teledata blocks.
25.4 The exercises
The value of x travels in the environment, because the launcher passes no arguments through to the program — the SPMD constraint of chapter 6, still binding four parts later.
$ QFT_X=5 netqmpi -n 3 notebook_apps/ex8_iqft.py --cunqa --shots 1024
$ for x in 0 1 2 3 4 5 6 7; do
> QFT_X=$x netqmpi -n 3 notebook_apps/ex8_iqft.py --cunqa --shots 1024 | tail -1
> done
101 is 5, rank 0 first, and every marginal should be a clean 1.000 / 0.000. The determinism flag is worth more than the value itself. It guards the one assumption that comes from the counts format rather than the physics: CUNQA joins one bitstring per classical register, the user’s own register first and the two protocol bits after it, and the protocol bits are coin flips. Had the reader picked one of those by mistake, nothing would be deterministic — so you get an honest deterministic=False rather than a plausible wrong answer. One value could be luck; eight cannot.
This is the first program of the day in which the ranks are not symmetric: rank 0 holds counting bit 0 and the eigenstate on a second data qubit; ranks 1 and 2 hold one counting bit each. Every controlled-U^(2^j) has its control on rank j and its target on rank 0 — local for rank 0, an expose window for the other two. Those windows do not overlap, so they hand the same comm qubit back and forth.
Two things to settle before writing any of it. The collectives go outside the if rank == branches, as always: every rank calls expose and unexpose, and only rank 0 puts a gate between them. And the angles are 2π·2^j·φ, not 2π·φ/2^j. Rank 0 is the most significant bit, so it gets the smallest rotation — which is the ordering the inverse QFT expects, and the reason the two halves fit at all.
$ QPE_PHI=0.625 netqmpi -n 3 notebook_apps/ex9_qpe.py --cunqa --shots 1024
$ QPE_PHI=0.3333333333333333 netqmpi -n 3 notebook_apps/ex9_qpe.py --cunqa --shots 1024
φ = 5/8 is a multiple of 1/8, so three bits hold it exactly and the counting register is deterministic: 101, every shot. φ = 1/3 falls between 2/8 and 3/8, and the second run is the more instructive of the two — read it carefully, because what comes back is three marginals, and nothing in them says which shot of rank 0 went with which of rank 2. For the exact phases that was harmless, since a product of deltas is the joint distribution. Here it is not, and the histogram over x simply is not in the data. 010 and 011 agree on the first two bits and differ in the third, which is exactly what you should see: ranks 0 and 1 nearly certain, rank 2 split near 50/50, and deterministic=False — the honest signature.
25.5 What to take from it
The most valuable five minutes are not the run. They are what the two exercises say together.
The composition is the result. inverse_qft was copied out of exercise 8 unchanged and kept working even though rank 0 now holds two data qubits and arrives entangled rather than in a product state. A distributed collective that composes is not a given; this one does, because it is written against ranks and qubit indices and does not care what happened before it.
Peak concurrency is what you pay for, not total count. Five windows open over the whole of exercise 9, and the family is still [2, 2]. The kickback windows open and close one at a time; only the inverse QFT’s nested pair is ever held at once. Window lifetime is the comm-qubit budget — close rank 2’s window earlier and one comm qubit would do, but the circuit would no longer be the inverse QFT.
And the resources are still yours to give back. The family has been up since chapter 21, which is why every run here attached instantly and paid no scheduler cost. It is still a reservation.
qdrop(FAMILY)
Two extensions worth trying afterwards, both of which answer themselves on paper before they cost an allocation:
- Redo exercise 8 with teledata instead of telegates — move
q1andq2to rank 0, transform, move them back — and count thegen_entrequests each version issues. - Take exercise 9 to four nodes. Work out what to raise before raising it: n counting qubits over n nodes means n(n−1)/2 cross-node rotations and n−1 comm qubits held at once on rank 0.
Closing the second block
The second half in one sentence: a programming model needs a machine to run on; there is no such machine yet; CUNQA emulates the infrastructure of one inside a real supercomputer, simulating its devices and channels; and because both projects kept a thin, documented seam at the right height of the stack, NetQMPI’s abstractions can be carried down onto it without either side surrendering its model.
26.1 What CUNQA does not do yet
The honest list, in the order it appears on the roadmap.1
- Communication noise: absent. Every channel in this tutorial is ideal. Latency, entanglement fidelity, heralded loss and memory decoherence during entanglement distribution are the characteristic physics of a distributed system, and none of it is modelled. Two routes are being weighed and both have costs: implementing it over the existing simulators, which were not designed for time-dependent physical-layer effects, or integrating a discrete-event network simulator, which brings mature noise models along with a networking paradigm that does not adapt readily to a computing one — and, being mostly written in Python, would break the C++ ecosystem the current simulators live in.
- Device noise: partial. Available only when AerSimulator runs the shots loop unassisted — no communication, no
CIF(chapters 16 to 18). Lifting this and extending noise to the other simulators that support it, such as Qulacs, is the nearer of the two goals. - The joint state lives in one process. Under quantum communication, the centralised executor simulates a single state without exploiting the distributed state vectors that QuEST and AerSimulator-under-MPI already offer. This is the ceiling on how large a quantum-communication experiment can be, and it is the clearest illustration in the whole tutorial of chapter 17’s point: the distribution of a quantum system and the distribution of its classical simulation are orthogonal problems.
- Execution is circuit-at-a-time. The roadmap points at streaming instructions to the vQPU in small binary blocks, with the vQPU updating its state as each block arrives — driven by the prospect of circuits whose encoding reaches hundreds of gigabytes. That would replace JSON as the interchange format and, incidentally, would make
flush()translate properly for the first time (chapter 23). - Scheduling is list order.
runassigns circuits to vQPUs in the order they appear. Everything a scheduler would do — locality, load, heterogeneous backends — is left as room above the API.
26.2 What the integration still has to settle
- Sub-communicators. Chapter 23 mapped
COMM_WORLDonto a family. Splitting a communicator maps onto multiple families, which is workable but not yet the same abstraction — and MPI programmers reach forComm_splitsooner than one might expect. - Noise parity across backends. The same program runs on SquidASM and on CUNQA and returns incomparable fidelities, for the reasons in 26.1. Until communication noise exists, the backend choice is a choice about what question you are asking: physical realism, or infrastructure behaviour at HPC scale.
- Where the ranks come from. Today the two
-nflags must agree by hand (chapter 24). A launcher that raised the infrastructure and started the ranks in one act would be more convenient — and would quietly undo the stack decision of chapter 16, which is why it has not been done.
26.3 The through-line
Five parts, one argument. Physical limits forced the replication of units, replication forced communication, and communication turned out to be the expensive part. MPI standardised how that is programmed, through three abstractions — SPMD, rank, communicator — that have outlived every machine they were written for. NetQMPI carried those three into the quantum domain, adapting the primitives where physics forbids the literal translation and leaving one cell of the table permanently empty. And CUNQA supplies what the model was missing: not a simulator of quantum mechanics, of which there are many, but an emulator of the infrastructure — vQPUs that are asked for, paid for, queried and released exactly as an accelerator of a real machine would be.
If an attendee leaves with one sentence from the second half, let it be the counterpart of the one that closed the first: distributed quantum computing will be run on HPC systems, so it has to be programmed like HPC and managed like HPC. The quantum part is what is new. Almost everything around it is not — and that is the good news, because it means the discipline already exists.
References
- J. Vázquez-Pérez, D. Expósito-Patiño, M. Losada, Á. Carballido, A. Gómez, T. F. Pena. CUNQA: a Distributed Quantum Computing emulator for HPC. arXiv:2511.05209 [quant-ph], 2025. arxiv.org/abs/2511.05209 · documentation and code at github.com/CESGA-Quantum-Spain/cunqa
- F. J. Cardama, T. F. Pena. NetQMPI: An MPI-Inspired library for programming Distributed Quantum Applications over Quantum Networks using NetQASM SDK. arXiv:2512.11483 [quant-ph], 2025. arxiv.org/abs/2512.11483 · código en github.com/netqir/netqmpi
- F. J. Cardama, J. Vázquez-Pérez, C. Piñeiro, T. F. Pena, J. C. Pichel, A. Gómez. NetQIR: An extension of QIR for distributed quantum computing. Future Generation Computer Systems, 174:107989, 2026.
- T. Häner, D. S. Steiger, T. Hoefler, M. Troyer. Distributed quantum computing with QMPI. Proc. SC'21, 2021.
- Y. Shi et al. A Reference Implementation for a Quantum Message Passing Interface. Proc. SC-W '23, pp. 1420–1425, 2023.
- A. Dahlberg, B. van der Vecht, C. Delle Donne, M. Skrzypczyk, I. te Raa, W. Kozlowski, S. Wehner. NetQASM — a low-level instruction set architecture for hybrid quantum-classical programs in a quantum internet. Quantum Science and Technology, 7(3):035023, 2022.
- T. Coopmans et al. NetSquid, a NETwork Simulator for QUantum Information using Discrete events. Communications Physics, 4:164, 2021.
- A. Dahlberg, S. Wehner. SimulaQron — a simulator for developing quantum internet software. Quantum Science and Technology, 4(1):015001, 2018.
- S. DiAdamo, J. Nötzel, B. Zanger, M. M. Beşe. QuNetSim: A Software Framework for Quantum Networks. IEEE Transactions on Quantum Engineering, 2, 2021.
- X. Wu et al. SeQUeNCe: a customizable discrete-event simulator of quantum networks. Quantum Science and Technology, 6(4):045027, 2021.
- D. Barral, F. J. Cardama, G. Díaz-Camacho, D. Faílde, I. F. Llovo, M. Mussa-Juane, J. Vázquez-Pérez, J. Villasuso, C. Piñeiro, N. Costas, J. C. Pichel, T. F. Pena, A. Gómez. Review of Distributed Quantum Computing: From single QPU to High Performance Quantum Computing. Computer Science Review, 57:100747, 2025.
- M. Caleffi, M. Amoretti, D. Ferrari, J. Illiano, A. Manzalini, A. S. Cacciapuoti. Distributed quantum computing: A survey. Computer Networks, 254:110672, 2024.
- S. Wehner, D. Elkouss, R. Hanson. Quantum internet: A vision for the road ahead. Science, 362(6412), 2018.
- J. Preskill. Quantum Computing in the NISQ era and beyond. Quantum, 2:79, 2018.
- MPI Forum. MPI: A Message-Passing Interface Standard. Version 4.1, 2023. mpi-forum.org/docs
- G. M. Amdahl. Validity of the single processor approach to achieving large scale computing capabilities. AFIPS Spring Joint Computer Conference, pp. 483–485, 1967. — J. L. Gustafson. Reevaluating Amdahl's Law. Communications of the ACM, 31(5):532–533, 1988.
- J. L. Hennessy, D. A. Patterson. Computer Architecture: A Quantitative Approach. 6th ed., Morgan Kaufmann, 2019. — For the roofline model: S. Williams, A. Waterman, D. Patterson, Communications of the ACM, 52(4):65–76, 2009.
- W. A. Wulf, S. A. McKee. Hitting the Memory Wall: Implications of the Obvious. ACM SIGARCH Computer Architecture News, 23(1):20–24, 1995.
- R. H. Dennard, F. H. Gaensslen, H.-N. Yu, V. L. Rideout, E. Bassous, A. R. LeBlanc. Design of ion-implanted MOSFET's with very small physical dimensions. IEEE Journal of Solid-State Circuits, 9(5):256–268, 1974.
- K. Rupp. Microprocessor Trend Data. Open dataset, CC-BY licence. github.com/karlrupp/microprocessor-trend-data — recommended source if concrete figures are projected in figure 1.
- L. Dalcín, R. Paz, M. Storti, J. D'Elía. MPI for Python: Performance improvements and MPI-2 extensions. Journal of Parallel and Distributed Computing, 68(5):655–662, 2008. · documentation at mpi4py.readthedocs.io
- G. Díaz-Camacho, I. F. Llovo, F. J. Cardama, I. Bautista, D. Faílde, M. M. Juane, J. Vázquez-Pérez, N. Costas, T. F. Pena, A. Gómez. Benchmarking Distributed Quantum Computing Emulators. arXiv:2512.01807, 2025.
- R. Parekh, A. Ricciardi, A. Darwish, S. DiAdamo. Quantum Algorithms and Simulation for Parallel and Distributed Quantum Computing. Proc. QCS 2021 (SC21), pp. 9–19, 2021.
- A. Ovide, S. Rodrigo, M. Bandic, H. van Someren, S. Feld, S. Abadal, E. Alarcón, C. G. Almudever. Mapping quantum algorithms to multi-core quantum computing architectures. Proc. IEEE ISCAS, 2023.
- M. Losada, J. Vázquez-Pérez, Á. Carballido, D. Expósito. CUNQA Documentation, 2025. cesga-quantum-spain.github.io/cunqa
- D. Willsch. Supercomputer simulations of transmon quantum computers. PhD dissertation, RWTH Aachen University, 2020.
- A. Elsharkawy et al. Challenges in HPCQC Integration. 2023 IEEE International Conference on Quantum Computing and Engineering (QCE), vol. 2, pp. 405–406, 2023.
- S. Gharibian. Strong NP-hardness of the quantum separability problem. Quantum Information and Computation, 10(3):343–360, 2010.
- M. Dobšíček, G. Johansson, V. Shumeiko, G. Wendin. Arbitrary accuracy iterative quantum phase estimation algorithm using a single ancillary qubit: A two-qubit benchmark. Physical Review A, 76:030306, 2007.
- A. Y. Kitaev. Quantum measurements and the Abelian Stabilizer Problem. PhD dissertation, Moscow Institute of Physics and Technology, 1995. arxiv.org/abs/quant-ph/9511026
- A. Yimsiriwattana, S. J. Lomonaco Jr. Generalized GHZ States and Distributed Quantum Computing. arXiv:quant-ph/0402148, 2004. arxiv.org/abs/quant-ph/0402148
- D. Claudino, D. I. Lyakh, A. J. McCaskey. Parallel quantum computing simulations via quantum accelerator platform virtualization. Future Generation Computer Systems, 160:264–273, 2024.