Demo Walkthrough¶
This walkthrough covers the entire memQ distributed-compilation workflow —
compile, verify, schedule — and shows just how little code it takes. It mirrors
the runnable notebook at
demo/demo.ipynb;
run that notebook to reproduce the outputs interactively.
The whole workflow is driven by two objects — and they are the only things we import:
1. Inputs¶
The compiler takes two plain-text inputs:
- A circuit — an OpenQASM 3.0 file. Here, a 4-qubit Quantum Fourier
Transform (
qft_n4.qasm). - A network topology — a JSON file. Here,
demo_network: two QPUs (P0,P1), each with 2 computation + 2 communication qubits, linked by a remote (entanglement) connection between their communication qubits.
2. Compile¶
The whole compilation step is two calls. Compiler takes the circuit and
network directly (file paths, in-memory objects, or inline QASM source), then
compile() partitions the circuit's logical qubits across QPUs and
reconstructs a distributed circuit that inserts the network primitives needed
to run two-qubit gates across QPUs.
compiler = Compiler(
"inputs/qft_n4.qasm",
"inputs/demo_network.json",
algo="interaction",
)
compiler.compile()
print(
"network:",
compiler.network.num_qpus,
"QPUs |",
compiler.network.num_comp_qubits,
"computation +",
compiler.network.num_comm_qubits,
"communication qubits",
)
The distributed circuit is a standard OpenQASM 3.0 program — the compiler's
primary output. Read it as a string (distributed_qasm) and write it to disk
(save_distributed_circuit). Note the per-QPU data registers (q0, q1),
the matching communication registers (c0, c1), and the catent →
remote-gate → catdisent sequences that implement each cross-QPU gate.
Communication register indices preserve the network's physical localIndex
values. If those values are offset or sparse, the register includes unused
slots so every referenced index is in bounds. Its declared length is therefore
an address range, not necessarily the physical communication-qubit count;
use compiler.network.num_comm_qubits for the latter.
compiler.save_distributed_circuit("outputs/qft_n4_distributed.qasm")
print(compiler.distributed_qasm)
3. The network primitives¶
The distributed circuit uses a handful of custom gates that stand in for the networking operations a distributed quantum computer must perform:
- Remote gates —
rcx,rcp,rcz,rcrycarry out a two-qubit gate between data qubits that physically live on different QPUs, without ever moving those data qubits.rswapperforms state teleportation, actually moving a qubit's state from one QPU to another. - Cat-entanglement — every remote gate is wrapped in a cat-entanglement
(
catent) / cat-disentanglement (catdisent) pair that consumes an entangled (EPR) pair on the communication qubits.
The gate declarations ship in memq_dqc/builder/distgates.inc; provide that
include to your OpenQASM tool, or inline it in place if the tool does not
resolve custom includes (for example, qiskit.qasm3.loads). Its placeholders
use the intrinsic U(0, 0, 0) identity, so they do not require stdgates.inc
to be present or included first. The
parameterized signatures are gate rcp(theta) q0, q1, c0, c1 and
gate rcry(theta) q0, q1, c0, c1. Their bodies are identity placeholders:
successfully importing the program does not simulate distributed protocols.
Use compiler.verify() for the monolithic-equivalence check below.
4. Verify¶
Is the distributed circuit still correct? compiler.verify() checks it
directly — no need to re-supply the original circuit, since the compiler
already has it. Under the hood it rewrites the distributed circuit into an
equivalent monolithic circuit (each remote gate replaced by its local
equivalent — rcx→cx, rcp→cp, …, rswap→swap — and the entanglement
scaffolding dropped), simulates both, and compares their output distributions
via Hellinger fidelity.
5. Schedule¶
Finally, the Scheduler lays the distributed circuit's operations out on a
timeline — respecting data dependencies, communication-qubit availability, and
how long each operation takes on real hardware — aiming to minimize the
makespan (total execution time). Hand it the compiler directly. The
hardware is chosen with two strings: a modality (here neutral_atom, which
sets local gate times) and an entanglement profile (here an illustrative
demo.demo, which sets the entanglement-generation rate).
scheduler = Scheduler(
compiler,
algo="des_link_fifo",
modality="neutral_atom",
entanglement_profile="demo.demo",
algo_kwargs={"seed": 0},
)
scheduler.run()
print(
"makespan:",
round(scheduler.schedule.makespan, 1),
"µs |",
"scheduled events:",
len(scheduler.schedule.operations),
)
scheduler.plot_gantt(
title="Execution schedule — qft_n4",
display="legacy",
save_path="outputs/schedule_gantt.png",
)
Each row is a physical qubit. The communication qubits (c…) generate
entanglement (epr) and run the catent/catdisent halves of each remote
gate, while the data qubits (q…) carry the local gates and final
measurements.
What you produced¶
From two plain-text inputs and a handful of lines — importing nothing but
Compiler and Scheduler — the workflow produced:
| File | What it is |
|---|---|
outputs/qft_n4_distributed.qasm |
The distributed circuit — standard OpenQASM 3.0. |
outputs/schedule_gantt.png |
The execution-schedule Gantt chart. |
…plus a verification check confirming the distributed circuit still computes the original result.