Backends

The same, unmodified application runs on every backend; you choose one with a command-line flag. What changes is what is being modelled — a quantum network, an HPC emulation, a plain circuit — and how faithfully.

Choosing one

Backend	Flag	What it targets	Key dependencies
CUNQA reference	--cunqa	HPC emulation of DQC through virtual QPUs (vQPUs)	cunqa (HPC / SLURM environment)
NetQASM / SquidASM	--netqasm	Low-level quantum-network simulation (EPR sockets, NetQASM routines)	squidasm, netsquid, netqasm 2.x, Python ≥ 3.9
NetQASM / SquidASM (legacy)	--netqasm1.0	The same backend against the older NetQASM release	squidasm, netsquid, netqasm 1.x
Qiskit Aer	--aer	Shot-based circuit simulation	qiskit, qiskit-aer
Qoala	--qoala	Quantum-internet node execution environment, with task scheduling and multitasking — simulation only	qoala, netsquid, netqasm 2.x, Python 3.10–3.12

Start here

CUNQA is the reference backend. It is the only one implementing the whole primitive set — transfers, rooted collectives and the telegate window — and the one the shipped examples are written against.

No cluster at hand?

Aer is the lightest option and the only one with no special installation requirements, but it supports point-to-point transfers only, via an unphysical SWAP.

Feature support at a glance

	CUNQA	NetQASM	Aer	Qoala
qsend / qrecv	✅	✅	⚠️ SWAP-based	✅
qscatter / qgather	✅	⚠️ scatter only	✅	❌
expose / unexpose	✅	❌	✅	❌
Controlled gates	✅	cx, cz	✅ incl. phase family	cx, cz
reset	✅	❌	✅	❌
barrier	❌	❌	✅	❌
Several circuits per rank	✅	✅	✅	❌
Hardware noise model	via vQPU definition	T1/T2, gate and link fidelity	❌	✅ full qdevice
Noise by default	—	none (ideal)	none	none (ideal)
Runs without special hardware	❌ needs SLURM	✅	✅	✅

The per-gate breakdown, including which operations are silently ignored rather than rejected, is in the gate support matrix.

Important

The NetQASM and Qoala defaults are noiseless. SquidASM’s default network has perfect qubits (t1 = t2 = 0), perfect gates and perfect links; Qoala’s default qdevice and links are perfect too. Every run of the multi-backend benchmark came out at fidelity 1 for that reason. Ask for noise explicitly — see the netqasm and qoala blocks.

Validated scale

What the benchmark apps (scripts/benchmark/apps) are known to run, per backend. n is the number of ranks, q the qubits per rank.

App	Aer	Qoala	NetQASM
cascade	✅ up to n=256, q≤6	✅ up to n=128, q≤6	✅ q=1 up to n≈10
ghz	✅ up to n=256	⚠️ fixed after 0.3.1, validate on the cluster	⚠️ q=1 up to n=7, q=2 up to n=3
qft (teledata)	✅ statevector-limited	❌ needs controlled-P	❌ needs controlled-P
qft_telegate	✅ statevector-limited	❌ needs expose	❌ needs expose

Two NetQASM limits of 0.3.1 are addressed after 0.3.1 but not yet re-measured on the cluster, so treat the table above as the proven ground:

• Two or more qubits per rank hung in any program with two transfers in a row between the same ranks (cascade with q ≥ 2, even at n=2). Fixed — see classical sockets.

• From about 10 ranks SquidASM’s EPR-socket set-up times out in wall-clock time (TimeoutError: Remote node did not initialize the correct rules) — intermittently at 10–12 ranks, always from 16. Mitigated: each rank now only sets up EPR sockets with the ranks it talks to, and the timeout is raised to 60 s. See scale limits.

The portability matrix in test/test_portability_matrix.py (pytest -m slow) runs cascade and ghz at q ∈ {1, 2} and n ∈ {2, 4, 8, 12} on every installed backend, and is the way to re-establish this table.

The shape of comm.results

The one place the abstraction is not watertight: each backend reports results differently.

Backend	Shape	Populated on
CUNQA	{rank: {bitstring: count}} — every rank’s counts	every rank
Aer	{bitstring: count} for the whole global circuit, all ranks’ classical bits concatenated	every rank, identically
Qoala	{bitstring: count} for this rank alone	every rank
NetQASM	{outcome: count} for this rank’s own measurements	the rank itself

Environment constraints

SquidASM and Qoala cannot share an environment

The --netqasm and --qoala backends must live in separate environments (two conda envs, for instance) — but not, as long thought, because of the NetQASM version. Both run on NetQASM 2.x; what actually conflicts is the NetSquid plugin stack, since SquidASM needs netsquid-magic 16.x and qoala-sim needs 14.x. Installing one over the other leaves the displaced backend unable to build a link layer.

A third environment holds the legacy --netqasm1.0 path on NetQASM 1.x, which pins Python to 3.8 — NetQASM 2.x requires 3.9 or newer. CUNQA and Aer have no such constraints.

On clusters with an older glibc (RHEL 8 has 2.28), NetSquid itself does not install: see NetSquid on RHEL 8.

This is also why the CLI imports backends lazily: only the one you select is ever imported.

NetSquid needs a free account

Both NetQASM and Qoala depend on NetSquid, installed from a private index:

pip install netsquid --extra-index-url https://<user>:<pwd>@pypi.netsquid.org

How a backend is put together

Every backend provides the same three Runtime components, and adding one never requires touching the SDK:

        graph LR
    subgraph SDK["SDK — backend-agnostic"]
        E[Environment]
        C[Circuit]
        Q[QMPICommunicator]
    end
    subgraph RT["Runtime — backend-specific"]
        X[Executor]
        A[CircuitAdapter]
        M[Communicator]
    end
    E -->|create_circuit| X
    C -->|recorded ops| A
    Q -->|on exit| M
    A --> B[(Backend)]
    M --> B
    X --> B
    

See Architecture and Writing a backend.