Write, emulate and run a program on Helios

Before you begin

Python 3.12, 3.13 or 3.14 on macOS, Linux or Windows.
A Quantinuum Nexus account. Apply for access
Signed in to Nexus from Python. Get started with qnexus
Helios access through your organization, for the final run on hardware. Systems access

Install Guppy, which includes Selene, and the Nexus client:

pip install guppylang qnexus

Step 1: Write a Guppy program

Guppy

This program entangles two qubits, measures the first and uses the outcome to correct the second. The measurement-dependent if is ordinary Python syntax in Guppy.

from guppylang import guppy
from guppylang.std.builtins import output
from guppylang.std.quantum import cx, h, measure, qubit, x


@guppy
def simple_circuit() -> qubit:
    q1, q2 = qubit(), qubit()

    h(q1)
    cx(q1, q2)

    outcome = measure(q1).read()
    output("q1", outcome)

    if outcome:
        x(q2)

    return q2


@guppy
def evaluate() -> None:
    q = simple_circuit()
    output("q2", measure(q).read())


evaluate.check()

check() type-checks the program without running it.

Learn more:Guppy getting started Language guide

Step 2: Emulate locally

Selene

Run 100 shots on Selene, the emulator built into guppylang. Nothing leaves your machine.

shots = evaluate.emulator(n_qubits=2).stabilizer_sim().with_seed(0).with_shots(100).run()
print(shots.collated_counts())

Checkpoint:About half of the shots report q1 as 1, and q2 is always 0, because the conditional x undoes the entanglement.

Learn more:Selene user guide Simulators

Step 3: Run with noise emulation

Systems support

Compile the program, upload it to your Nexus project, check its cost and start a job on Helios-1E, the noisy Helios emulator hosted in Nexus. It models Helios hardware noise, but the job does not run on a quantum computer.

import qnexus as qnx

project = qnx.projects.get_or_create("Helios-Samples")
qnx.context.set_active_project(project)

ref_hugr = qnx.hugr.upload(evaluate.compile(), name="first-helios-program")

# Ask the Helios syntax checker for the maximum cost of 100 shots.
max_cost = qnx.hugr.cost(programs=[ref_hugr], n_shots=[100])

config = qnx.models.HeliosConfig(
    system_name="Helios-1E",
    max_cost=max_cost,
    emulator_config=qnx.models.HeliosEmulatorConfig(
        n_qubits=2,
        simulator=qnx.models.StatevectorSimulator(),
    ),
)

result_ref = qnx.start_execute_job(
    programs=[ref_hugr],
    n_shots=[100],
    backend_config=config,
    name="first-helios-program",
)

The emulator lets you finish the workflow without using hardware time. To run on Helios hardware, change system_name to the Helios system available to your organization.

Learn more:Helios job workflow Job costing

Step 4: Verify the results

Helios

Wait for the job to finish and download its results.

qnx.jobs.wait_for(result_ref)
job_result = qnx.jobs.results(result_ref)[0].download_result()

Checkpoint:The job shows as completed in your project in the Nexus portal, and the result distribution matches step 2, with small deviations from the emulated noise.

Troubleshooting

The upload or compile step fails

Check that your guppylang and qnexus versions match those used in the Helios job workflow.

The job is rejected for cost or quota

Increase max_cost within your quota, or ask an organization administrator. Administrator guide

I don't have access to Helios

Complete the workflow on Helios-1E, then contact support about hardware access.

Next steps

Make a program fault tolerant with Guppy FT

Encode an ordinary Guppy program with the Steane code and run it on emulated Helios hardware.

Guppy FTGuppySeleneSystems supportHelios

Guided workflow

Estimate the cost of a Helios job

Predict the cost of a program before you submit it.

Systems supportHelios

Guide

Decode errors in real time on GPUs

Use NVIDIA GPU decoding alongside Helios programs.

GuppyHeliosCUDA-Q

Guide

Bring existing pytket circuits to Guppy

Load pytket circuits into Guppy programs and adopt Guppy features.

TKETGuppy

Guide