Verify an Authored Gadget

gadgets/00_verify_gadget.py authors a Repetition-code syndrome round, declares its detector contract, and verifies its ideal logical action. It then changes the declared action to demonstrate a failed verification receipt.

This is the first gadget example. The general standalone introduction, standalone/00_logical_program.py, instead authors and estimates a logical Bell program. Here the question is whether one encoded realization does what its declaration promises.

Run from the repository root with CUDA-Q Logical installed:

python3 preview/logical/examples/gadgets/00_verify_gadget.py

The example needs no simulator dependency. Run the complete script or step through its # %% cells.

Author the realization and its claim

A gadget combines an ideal logical action with a physical realization on an encoded boundary. This realization extracts the Repetition code’s two Z checks and returns the block. Its implements= declaration claims that the logical qubit is unchanged:

import cudaq.logical as cql

RepetitionPatch = cql.patch[cql.codes.Repetition]

An idle logical claim with a syndrome-extraction realization.

@cql.gadget(implements=cql.std.idle)
def syndrome_round(block: RepetitionPatch) -> RepetitionPatch:
    block, _ = cql.extract_syndrome(block, record="round")
    return block

The patch type identifies the code. record="round" gives the extracted check results stable names that the contract can reference.

Declare the detector contract

The contract relates the realization’s measurement records to its encoded input and output boundaries:

Declare the virtual detectors and outgoing virtual syndrome.

def declare_contract(gadget):
    incoming = gadget.inputs.only()
    outgoing = gadget.outputs.only()
    checks = tuple(
        gadget.record(f"round.s{i}") for i in range(incoming.syndrome.width))
    detectors = tuple(
        cql.gadgets.Detector(incoming.syndrome[i] ^ checks[i])
        for i in range(incoming.syndrome.width))
    return cql.gadgets.GadgetContract(gadget,
                                      detectors=detectors,
                                      boundary={outgoing.syndrome: checks})


contract = declare_contract(syndrome_round)

Each detector computes the XOR of an incoming virtual syndrome and the newly measured check. In an ideal round the two agree, so the detector parity is zero. The output binding carries the measured checks forward as the next gadget’s expected stabilizer values. These declarations describe the realization’s measurement relations; they do not add physical operations.

Inspect a successful receipt

Verification checks both the detector contract and the logical action:

receipt = cql.gadgets.verify_gadget(contract)
assert receipt.detector_contract.ok
assert receipt.logical_action.status == "verified"
assert receipt.verified
print("Syndrome round:")
print(f"  detector contract verified: {receipt.detector_contract.ok}")
print(f"  logical action: {receipt.logical_action.status}")
print(f"  gadget verified: {receipt.verified}")

detector_contract.ok establishes that the declared detector and boundary relations are deterministic and complete. logical_action.status reports whether the realization implements the declared idle action. receipt.verified requires both checks to pass. With the default arguments, verify_gadget raises if either check fails.

Inspect an incorrect logical claim

The final cell gives the same physical extraction a logical-X claim:

Return a failed receipt for inspection with raise_on_failure=False.

@cql.gadget(implements=cql.std.x)
def wrong_action(block: RepetitionPatch) -> RepetitionPatch:
    block, _ = cql.extract_syndrome(block, record="round")
    return block


wrong_contract = declare_contract(wrong_action)
wrong_receipt = cql.gadgets.verify_gadget(wrong_contract,
                                          raise_on_failure=False)
assert wrong_receipt.detector_contract.ok
assert wrong_receipt.logical_action.status == "failed"
assert not wrong_receipt.verified
print("Deliberately wrong logical X declaration:")
print(f"  detector contract verified: {wrong_receipt.detector_contract.ok}")
print(f"  logical action: {wrong_receipt.logical_action.status}")
print(f"  gadget verified: {wrong_receipt.verified}")

The detector contract still passes: those checks describe syndrome relations, which cannot distinguish idle from a claimed logical X. The logical-action check fails, and the combined receipt is unverified. Passing raise_on_failure=False lets the example inspect this expected failure.

These checks establish ideal behavior for the supported stabilizer actions; they do not prove fault tolerance or noisy circuit distance. See Detector contracts for receipt details and supported claims.

Continue with Physical surface-code memory to verify preparation, extraction, and readout, then export their noisy circuit and composed detector error model.

Back to examples