Visualizing Compilation and Execution¶
DQC can render every stage of the pipeline: the circuit DAG, the distributed circuit, and the final execution schedule — including an experimental animation played over the network graph.
This notebook uses the small two-QPU demo so every figure stays readable.
Running this notebook. From the repository root:
uv sync uv run jupyter lab demo/visualization.ipynb
Setup¶
Two conventions to know:
- The matplotlib renderers return an
Axesand draw inline. - The SVG renderers return an
SvgDocument, whose.svgattribute is markup you can display or write to disk with.write_svg(path).
ebit_assignment=True on compile() records which entangled pair each remote
operation used, which the animation needs.
from pathlib import Path
from IPython.display import SVG, display
from memq_dqc import Compiler, Scheduler
Path("outputs").mkdir(exist_ok=True)
compiler = Compiler(
"inputs/qft_n4.qasm", "inputs/demo_network.json", algo="interaction"
)
compiler.compile(ebit_assignment=True)
scheduler = Scheduler(
compiler,
algo="des_link_fifo",
modality="neutral_atom",
entanglement_profile="demo.demo",
algo_kwargs={"seed": 0},
)
scheduler.run()
partitioner = compiler.partitioner
circuit = compiler.circuit
schedule = partitioner.schedule
windows = partitioner.windows
print("QPUs: ", compiler.network.num_qpus)
print("windows: ", len(windows))
print("makespan:", round(scheduler.schedule.makespan, 1), "us")
QPUs: 2 windows: 3 makespan: 93.8 us
1. The circuit DAG¶
plot_circuit_dag shows the monolithic circuit as a dependency graph — the
input to partitioning. Nodes are operations; edges are data dependencies.
import matplotlib.pyplot as plt
from memq_dqc.visualization import plot_circuit_dag
fig, ax = plt.subplots(figsize=(11, 5))
plot_circuit_dag(circuit, ax=ax, title="qft_n4 — circuit DAG")
fig.tight_layout()
fig.savefig("outputs/circuit_dag.png", dpi=150)
plt.show()
2. The distributed circuit¶
plot_distributed_circuit draws the compiled result. Wires are QPU-local
physical slots rather than global logical qubits, so you can see which QPU
each operation lands on, and the cat-entanglement scaffolding around every
remote gate.
from memq_dqc.visualization import plot_distributed_circuit
document = plot_distributed_circuit(
circuit,
schedule=schedule,
windows=windows,
title="qft_n4 distributed across 2 QPUs",
)
document.write_svg("outputs/distributed_circuit.svg")
display(SVG(document.svg))
3. The execution schedule¶
This is the post-scheduling view: real durations on real hardware. plot_gantt
has two renderings — "pretty" for publication and "legacy" for on-screen
diagnostics.
scheduler.plot_gantt(
display="pretty",
save_path="outputs/schedule_gantt_pretty.png",
);
scheduler.plot_gantt(
title="Execution schedule — qft_n4",
display="legacy",
save_path="outputs/schedule_gantt_legacy.png",
);
Each row is a physical qubit. Communication qubits (c…) generate entanglement
(epr) and run the catent/catdisent halves of each remote gate; data qubits
(q…) carry local gates and measurements.
4. Animating execution over the network — Experimental¶
This feature is experimental and may change in a future release.
animate_circuit_execution plays the schedule back over the network graph:
nodes light up as operations run, and remote links light up while an entangled
pair is being generated or consumed.
mode="events" gives one frame per event boundary. The returned object renders
inline in Jupyter via _repr_html_, but that embeds a frame-by-frame player in
the saved file — megabytes of base64. Export a GIF and reference it instead, so
the notebook stays small.
from memq_dqc.visualization import animate_circuit_execution
animation = animate_circuit_execution(
compiler.network,
scheduler.schedule,
mode="events",
title="qft_n4 execution",
figsize=(7, 4),
)
gif_path = Path("outputs/execution.gif")
animation.save(gif_path, fps=3, dpi=70)
plt.close("all")
print("wrote", gif_path, f"({gif_path.stat().st_size // 1024} KB)")
MovieWriter ffmpeg unavailable; using Pillow instead.
wrote outputs/execution.gif (325 KB)

save() picks its writer from the extension: .gif uses Pillow, .mp4 needs
ffmpeg on the path, and .html writes a self-contained player. In a live
session animation.show() opens an interactive window, and
animation.to_jshtml() returns an embeddable player.
What you produced¶
| File | What it is |
|---|---|
outputs/circuit_dag.png |
Monolithic circuit dependency graph |
outputs/distributed_circuit.svg |
Compiled circuit across QPUs |
outputs/schedule_gantt_pretty.png |
Execution schedule (publication) |
outputs/schedule_gantt_legacy.png |
Execution schedule (diagnostic) |
outputs/execution.gif |
Animated playback over the network (experimental) |
Next¶
comparing_partitioners.ipynb— quantify what these pictures show.scheduling_and_hardware.ipynb— change the hardware and watch the schedule stretch.