Quantum Network End-to-End Simulation Toolkit

Getting started

QNEST uses two scientific Python environments. The desktop application, Qoala/NetSquid scheduler, AFA-QSP, HAMFA-QSP and plotting run in qoala. MQT Bench, Qiskit, pytket, DQCPass and pytket-DQC run in pytket_dqc.

Install both environments from the project directory:

./install.sh

To check an existing installation without rebuilding it:

./install.sh --verify

Start the application with:

./launch_qnest.sh

Workspace

QNEST keeps one experiment state across five stages.

The left rail selects the active stage. The top toolbar opens the AI Assistant, Settings, Documentation, Report a Bug and About. The Assistant is a docked tool window; opening or closing it changes the available workspace width without changing the experiment state.

Circuit

The Circuit page can import source files, generate MQT Bench circuits, or edit QASM directly. Choose Single circuit for a one-circuit experiment or Batch / sweep when several circuits should move through the same downstream workflow.

MQT Bench

Scalable benchmarks use an inclusive qubit range. QNEST checks the requested benchmark/size combinations against the installed MQT Bench version before generation. The benchmark list stays in two columns and long labels wrap inside their column.

The assistant's default starter experiment is a GHZ sweep from 5 to 20 qubits in steps of 2.

Batch circuit set

Each generated or imported circuit is kept as a separate record. Compile, Schedule and Run operate on the selected circuit or an eligible all-circuits scope, depending on the current stage.

Network

The Network page defines the physical architecture and the computation capacity available to the distributor. The Table view is authoritative for predefined topologies; the Designer is used for custom graphs and for visual inspection.

Capacity and topology

Set the number of servers/QPUs, qubits per QPU and topology. For All-to-all, choose either Direct QPU links or Shared switch. A shared switch can be All-photonic or Memory-assisted.

Calculated link performance

Distance is editable. QNEST calculates success probability, fidelity, attempt rate, Ebit rate and propagation latency from the active physical model. These calculated values should not be treated as independent manual inputs.

In Memory-assisted mode, the page shows the memory parameters together with the photonic parameters that generate entanglement before storage. Stored-pair fidelity is then aged by the HAMFA memory model during Run.

Compile / Distribute

Compile prepares the circuit for distributed execution and writes the bridge used by the scheduler. The pipeline cleans the source, applies DQCPass preparation, distributes the circuit with pytket-DQC, creates the explicit EJPP representation, and exports the Qoala bridge.

The Compile preview retains the main stages: Original, Cleaned, After DQCPass, Distributed circuit and EJPP representation. Use Open interactive when an interactive HTML representation is available.

Schedule

Schedule runs the Qoala/NetSquid timing workflow using the bridge from Compile. The desktop controls use microseconds. Backend files may retain nanoseconds when the scientific code expects them.

The Schedule visualization tab provides Timed Gantt and Layer Gantt views. The in-app view is a local preview; Open interactive opens the saved HTML without rerunning scheduling.

Request tables and schedule artifacts are stored under 04_schedule/ in the circuit's run directory.

Run / Analyse

AFA-QSP/HAMFA-QSP Monte Carlo is available only when the network uses All-to-all → Shared switch. If the network is switch-free, the executable workflow ends after Schedule. The Run page then exposes the earlier-stage artifacts as one exportable package rather than starting protocol Monte Carlo.

When Monte Carlo is enabled, Compile and Schedule are reused. Only the stochastic AFA/HAMFA protocol stage is repeated.

Reference settings

These are starting values taken from the bundled reference workflow. Researcher-entered values take precedence.

Per-request tables

The Run page intentionally hides simulator-only diagnostics from the normal result surface. The visible tables contain the fields needed to read each request outcome.

Headers and values are centred in the result viewer. Alternating row backgrounds and compact number formatting are used to keep wide Monte Carlo tables readable.

Units

The result selector can show time columns in ns or µs. This is a display conversion only. The saved per-replicate result tables stay in raw ns so the underlying data is not rewritten when the display unit changes.

Batch plots

Batch/sweep mode keeps the publication-style scaling figures for EPR pairs, AFA/HAMFA punishment time, HAMFA resource use and blocked requests versus circuit size.

QNEST Assistant

The Assistant is a planning, configuration and explanation layer. The default local model is Qwen3 8B through Ollama. It receives a fresh control catalogue and scientific workspace summary for every request, so changes made in the GUI are reflected in the next assistant turn.

For an all-to-all network where no interconnect is named, the assistant uses Shared switch → Memory-assisted. Explicit researcher choices always take priority.

The default suggestion builds GHZ 5→20, step 2, on 7 QPUs with 4 qubits/QPU, All-to-all, Shared switch, Memory-assisted.

The Assistant understands Run gating. It must stop after Schedule for switch-free networks and must not propose AFA/HAMFA Monte Carlo in that configuration.

When asked to interpret Run results, it receives the same compact per-request tables shown in the UI and the currently selected display unit. Internal HAMFA implementation diagnostics are not presented as the main result table.

Prepare the local model with:

./setup_qwen.sh

Connection settings are under Settings → AI Assistant.

Files and exports

Each compiled circuit has a stage-structured run directory:

runs/<experiment>/
  01_circuit/
  02_network/
  03_compile/
  04_schedule/
  05_run/
  logs/

Per-replicate AFA/HAMFA result tables are stored under 05_run/result_tables/run_XXX/. Batch exports preserve the individual per-circuit run folders rather than flattening them into one directory.

Settings

Settings controls appearance, UI scale, startup behaviour and AI configuration. Interface preferences are stored in ~/.qnest/ui_settings.json.

Changing appearance settings does not change scientific parameters.

Bug reports

Choose Report a Bug from the toolbar. The report is prepared for:

elyasi@chalmers.se

The dialog can save a diagnostic ZIP containing the report text, UI settings and current-run logs. QNEST then opens the default mail application with the recipient, subject and report text filled in. Attach the diagnostic ZIP before sending when one was created.

Troubleshooting

Compile cannot find pytket-DQC

Run ./install.sh --verify and confirm that the pytket_dqc Jupyter kernel is registered.

Schedule is unavailable

Compile the selected circuit first. In batch mode, confirm that the Schedule scope contains the intended compiled circuits.

Run is disabled

Check the Network architecture. AFA/HAMFA Monte Carlo requires All-to-all → Shared switch. Direct links are intentionally schedule-only.

Result values look unexpectedly large

Check the result-unit selector first. Raw saved timing values use ns; the GUI can show the same values in µs without changing the simulation.

The AI Assistant proposes the wrong downstream stage

Confirm the live Network architecture and circuit mode. The Assistant receives current state on every turn; starting a new assistant message after a GUI change should use the updated prerequisites.