Using Quantinuum Nexus from a Lovable project

What Nexus is, and what it is not

Selene is the free offline emulator that ships inside guppylang. It runs in your own sandbox, costs nothing, and is where almost all of this programme's work happens. Nexus is the separate online lane: hosted emulators carrying the vendor error model, and — with the right access — real H-series hardware.

On a plain account the real QPUs simply do not appear in the device list. That is not an error to debug. Hosted emulators such as H2-1LE are visible and usable; if H1-1, H2-1 or H2-1SC are missing, you do not have hardware access yet, and no amount of config will conjure them.

What this account can actually reach

The backends page is the ground truth, not the datasheet. Eleven backends are visible on this account and none of them is a QPU — every result on this site is therefore an emulator claim. Two details in this table bite if you ignore them: the widths are the emulator ceilings the account exposes (H2-Emulator shows 26 qubits even though H2-1 is a 56-qubit machine), and each family needs its own config class.

A name submitted through the wrong config class is accepted at job creation and then refused at submission with You do not have access to this machine (code: 14) — an access error for what is really a typing mistake. That is how the Helios leg was lost the first time. The preflight in quantum/backend_nexus.py now picks the class from the backend family, and an unreachable name prints the reachable list grouped the same way.

Which backends will actually take shots

Reachable is not the same as usable. A backend can be visible, correctly configured, and still refuse shot-level output, and a backend wide enough on paper can be too narrow for the run in hand. Every dry run now prints this matrix before anything is submitted, built by asking devices.supports_shots(config) with the config class that backend's family requires — so the devices a sweep would silently skip are named up front rather than discovered one submission at a time.

The snapshot above was written by python -m quantum.device_matrix --dump on 2026-08-26T00:52:33+00:00 from the pinned source, sized for 16 qubits. Two rules keep it honest. An unknown verdict is missing information, never a refusal: if the session is down or the config class is absent from the installed client, the device stays available and the submission path re-checks it. And the matrix is advisory only — the real gate is still the per-submissionsupports_shots preflight, because a table generated minutes ago is not a promise about the job you are about to pay for.

Getting logged in from a sandbox

Login is a device-code flow. The call blocks until you open the URL it prints and approve the device; there is no way to script past that step. On success a token lands in ~/.qnx/auth and the Python client picks it up ambiently — you do not pass credentials to your own code, and you should not.

Two sandbox realities to plan for. Installing qnexus alone is not enough; it needs guppylang>=1.0 in the same place. And the sandbox home is ephemeral, so the login recurs — treat re-authentication as normal, and keep every script able to run in a dry lane without a session.

echo ".pydeps/" >> .gitignore          # do this FIRST
pip install --target .pydeps "guppylang>=1.0" qnexus
PYTHONPATH=.pydeps python -c "import qnexus; qnexus.login()"

Failures — the honest list

Each of these cost real time. They are listed roughly in the order they bit.

Best practices that stuck

Resuming a sweep you already paid for

A hardware sweep loses its process more often than you would like — a rollback, a dropped websocket, a sandbox timeout. Nexus has still finished the jobs and still billed for them. Resubmitting to get those shots back is the single most expensive avoidable mistake on this lane, so recovery has to be one command rather than an ad-hoc script.

# ids in hand, from the console or a shipped dump
python -m quantum.resume --backend hardware --job-id exec-1 exec-2

# ids recorded in a dump the sweep wrote before it died
python -m quantum.resume --backend hardware --from-dump src/data/demos/x.json

# no ids at all — find the run by the labels every submission stamps
python -m quantum.resume --backend hardware --gate G16 --dry-run

Four details make the difference between a command that works months later and one that doesn't. The decode width comes from the n_qubits property stamped on the job, not from memory. A job that is not COMPLETED is reported with a plain reason and skipped, so one DEPLETED id does not abandon the other nine. The billed HQC from the original run stays in the meter, because a resumed sweep that reports itself as free has lost the true cost of the work. And the shots are cached on disk by job id, so the second resume is a file read and a driver's row loop consumes it exactly like a row it ran itself.

Recovery only works if you can see what is recoverable, so the saved-Ref store has its own audit view: the Ref ledger lists every persisted job by submission run, with its last known status and whether it still carries the sweep coordinates a re-attach needs.

Knowing a job ran is not the same as knowing what it cost. The estimate booked at submission and the figure Nexus actually billed are reconciled per job on the cost ledger, which flags any bill more than ten percent above its estimate and refuses to count a job with no bill back yet as free.

Successes — what actually worked

• The ambient token file was recognised without any credential handling in project code — the session simply existed and the client used it.
• A 20-shot X probe on H2-1LE pinned the bit order conclusively, and every downstream reader was written against that result rather than against an assumption.
• A dry run of the ethylene QPDE kernel estimated 5.0384 HQC against a ceiling of 25.0, printed all four quota meters, and correctly refused the devices this account cannot reach.

The Lovable-specific constraint

A Lovable app's server code runs in a Cloudflare Worker. child_process is a stub that throws, and there is no arbitrary filesystem to read from. A Nexus call can therefore never live inside a server function, however tempting the "run experiment" button looks.

The working shape is a three-step loop: run Python in the sandbox, commit the result JSON into the repository, render a static view of that JSON. Every experiment page on this site is built that way. Keep each turn down to one committable artefact and a rollback costs you minutes rather than a day.

What I would do differently

1. 01Calibrate bit order before writing a single line of analysis, not after the numbers look strange.
2. 02Gitignore the vendored dependency tree on day one — it is the difference between a working session and six lost turns.
3. 03Trust max_cost, not the quota meters, as the spend guard.
4. 04Size noisy jobs well under the cliff and batch programs into one submission instead of firing many.
5. 05Write job ids into the cache on the first run so a resume is always a download.
6. 06Run the classical baseline first; half the time it tells you the quantum leg is not the interesting part yet.

Where to go next