Make a program fault tolerant with Guppy FT

Before you begin

Python 3.12 or above on macOS, Linux or Windows.
Familiarity with writing and emulating Guppy programs. Run your first program
For step 4, a Nexus account and a signed-in Python session. Get started with qnexus

Install Guppy FT, which brings in guppylang and the Selene emulator, plus the Nexus client:

pip install guppyft qnexus

Step 1: Write the program without QEC

Guppy

Start with the algorithm itself. This teleportation program uses only standard guppylang operations and knows nothing about error correction, so you can check its logic first without thinking about noise.

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


@guppy
def teleportation() -> None:
    # Prepare the source qubit in |1>
    src = qubit()
    x(src)

    # Create a Bell pair
    tmp = qubit()
    tgt = qubit()
    h(tmp)
    cx(tmp, tgt)

    # Teleport src onto tgt
    cx(src, tmp)
    h(src)
    if measure(src).read():
        z(tgt)
    if measure(tmp).read():
        x(tgt)

    output("tgt", measure(tgt).read())

Learn more:Guppy language guide

Step 2: Encode it with the Steane code

Guppy FT

Choose a QEC code and how many logical blocks are available. Here the Steane code protects each of the program's three qubits with its own block. check_may_encode reports problems such as unsupported operations before you encode.

from guppyft.code.steane.encode import SteaneBuilder

# One logical block per logical qubit in the program.
steane = SteaneBuilder().build(n_blocks=3)

steane.check_may_encode(teleportation.compile())
encoded = steane.encode(teleportation.compile())

encoded is an ordinary HUGR package of logical primitives, so the same tools that run any Guppy program can run it.

Learn more:Guppy FT getting started Steane code API

Step 3: Emulate the encoded program

Selene

The Steane instance builds an emulator for the encoded program. Use the Stim stabilizer simulator, which handles the many physical qubits an encoded program needs. 98 qubits matches Helios.

from selene_sim import Stim

shots = (
    steane.emulator(teleportation.compile(), n_qubits=98)
    .with_simulator(Stim())
    .with_shots(100)
    .run()
)
print(shots.collated_counts())

Checkpoint:Every shot reports tgt as 1: the |1⟩ state prepared on the source qubit has been teleported through three encoded blocks. Fewer than about 30 qubits is too few for this program, and fails with “No more qubits available to allocate”.

Step 4: Run it on the Helios emulator

Systems support

Upload the encoded package to Nexus and run it on Helios-1E, the Helios emulator, with the realistic Helios error model, so you can see the code protecting the result from noise.

import qnexus as qnx

project = qnx.projects.get_or_create("guppyft-samples")
qnx.context.set_active_project(project)

ref = qnx.hugr.upload(encoded, name="steane-teleportation")

# Helios configs require a maximum cost; estimate it for 100 shots.
max_cost = qnx.hugr.cost(programs=[ref], n_shots=[100])

config = qnx.models.HeliosConfig(
    system_name="Helios-1E",
    max_cost=max_cost,
    emulator_config=qnx.models.HeliosEmulatorConfig(
        n_qubits=98,
        # Encoded programs are Clifford-heavy and use many physical qubits,
        # so use the Stim-based stabilizer simulator.
        simulator=qnx.models.StabilizerSimulator(),
        error_model=qnx.models.QSystemErrorModel(),
    ),
)

result_ref = qnx.start_execute_job(
    programs=[ref],
    n_shots=[100],
    backend_config=config,
    name="steane-teleportation",
)

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

Checkpoint:The job completes in your project in the Nexus portal. Compare its counts with step 3: with the Helios error model switched on, tgt should still be 1 in the large majority of shots.

To run on hardware, change system_name to the Helios system available to your organization.

Learn more:Helios job workflow Quantinuum emulators Job costing

Troubleshooting

check_may_encode raises an error

The program uses something the chosen code can't encode yet. Check the error message, then adjust the program or try another code from guppyft.code.

The emulator runs out of qubits

Increase n_qubits. Each Steane block uses 7 physical qubits, plus ancillas for syndrome extraction and state preparation.

The Nexus job is slow or runs out of memory

Make sure the emulator uses StabilizerSimulator. The default state-vector simulator cannot handle this many qubits.