Skip to content

Introducing CUDA-Q Pulse: Python-native pulse programming with GPUs in the loop

Gates are the currency of quantum applications. But every quantum gate is a convenient abstraction, representing a shaped microwave or laser pulse executing across a control line with nanosecond precision. Calibration, quantum error correction (QEC), and device bring-up all happen at that deeper layer, and very often crafting and operating with those pulses requires GPU calculations to make fast decisions during quantum runtime.

Today we're releasing CUDA-Q Pulse (cudaq-pulse), an open-source pulse-level programming model and MLIR compiler. This new addition to the NVIDIA quantum platform allows users to write pulse programs in ordinary Python and call classical functions on a GPU, host, or FPGA in the middle of the experiment. It can work within explicit latency budgets, and simulate the whole loop involved in pulse programming with NVIDIA cuDensityMat before running it on quantum hardware.

CUDA-Q Pulse: a Python kernel calls a GPU decoder during quantum runtime and uses the answer to condition the next pulse

Why pulses, and why this release

Gate-level frameworks give algorithm developers a clean interface. But the work that makes a quantum processor (QPU) function, such as tuning a π pulse, tracking a drifting T1, echoing away crosstalk, or choosing an action before the next quantum error correction round, is written in terms of control lines, tones and waveforms. Until now that code has mostly lived in sequencer languages tied to one control system - making it hard to share or simulate.

The classical side of that loop is also becoming increasingly demanding. Adaptive calibration runs a Bayesian estimator between shots. Real-time QEC needs a decoder to answer before the next syndrome round. NVQLink gives QPUs access to GPUs with microsecond latency, and cudaq-realtime provides the runtime for those calls. CUDA-Q Pulse adds the programming model, a single Python source that describes the pulses, the measurements, and the classical calls between them, compiled to an open MLIR representation that any control system can utilize.

  • Python-native kernels


    @pulse.kernel functions are ordinary Python, with loops, comprehensions, *qudits, helpers, and direct calls. They trace to a typed MLIR pulse dialect in milliseconds.

  • Real-time classical calls


    @pulse.classical declares a function the pulse program calls during quantum runtime, with a typed data layout and a latency budget. The scheduler treats it like any other operation.

  • CPU and GPU simulation


    The same kernel runs on a NumPy reference simulator or lowers through an operator dialect to NVIDIA cuDensityMat, so you can run full pulse routines against a physics model of a quantum system, including a 17-qubit surface-code processor from the literature.

  • Open, hardware-agnostic IR


    Pulses, waits, syncs, loops, and measurement-conditioned branches compile to MLIR and, through export_to_controller(), to a versioned program that control-system vendors can lower to their own sequencers, with no dependency on cudaq-realtime.

CUDA-Q Pulse ships as pip-installable wheels covering Python 3.12 through free-threaded Python 3.14t, with CUDA 12 and CUDA 13 GPU simulation on Linux through the [cu12] and [cu13] extras.

Experimental release

CUDA-Q Pulse is currently an experimental, standalone release that's separate from the CUDA-Q product. APIs may change between versions as we work with the community. We want your feedback in GitHub issues.

A pulse kernel is simple Python

A kernel works with a small set of physical resources. Lines carry signals to and from a qubit, and tones hold the frequency and phase that a line operates at. Inside the kernel, a handful of operations do the work: drive, readout, wait, sync, and phase and frequency updates on tones. Waveforms like gaussian, drag, and square are values you can build and pass to other functions - as shown in the below example.

import cudaq_pulse as pulse


@pulse.kernel
def rabi(qudit, amplitude: float):
    d = get_drive_line(qudit)     # the line that drives the qudit
    r = get_readout_line(qudit)   # the line that reads it out
    drive(d, gaussian(duration=32 * pulse.ns, amplitude=amplitude, sigma=8 * pulse.ns))
    sync(d, r)                    # start the readout after the drive pulse ends
    return readout(r, square(300 * pulse.ns, 0.05))


qs = pulse.quantum_system("transmon_surface17")
q = qs.qudits[0]

# Sweep the drive amplitude. A float argument stays symbolic, so this compiles once.
for amplitude in [0.04, 0.1, 0.16]:
    result = pulse.simulate(rabi, q, amplitude)
    p1 = result.level_population(1)   # excited-state population: 0.15, 0.65, 0.96

Calling rabi(q, 0.16) is an ordinary Python call. The first call traces the function's bytecode into the Pulse MLIR dialect, compiles it, and runs it on the selected quantum system. Each specialization is cached, so repeat calls skip compilation.

We spent much of this release making kernels read like standard Python. Comprehensions, generator expressions, starred unpacking, *qudits parameters, methods, and decorated helpers all trace. Here's a Ramsey sequence across every qubit on a 17-qubit device:

@pulse.kernel
def parallel_ramsey(qudits, tau: float):
    for q in qudits:
        d = get_drive_line(q)
        x90 = d.get_calibration(pulse.gates.X90)   # this line's calibrated π/2 pulse
        drive(d, x90)
        wait(d, tau * pulse.ns)                    # free evolution for tau
        drive(d, x90)

scheduled = parallel_ramsey.lower(qs.qudits[0:17], 200.0)   # compile and schedule all 17

When something can't trace, the error names your file and line and tells you what to write instead. A python -m cudaq_pulse.doctor --setup-editor command and a mypy plugin clear editor warnings on bare kernel operations such as drive and readout, and the command writes that configuration for you when you confirm.

Calling a GPU in the middle of an experiment

Many of the most valuable control loops need a classical answer during the middle of an experiment. A decoder may need to report whether a syndrome indicated an error, or an estimator may need to pick the next wait from what was just measured. CUDA-Q Pulse adds a classical dialect so a pulse program can call a function on the controller or a GPU during quantum runtime and use the answer immediately.

import cudaq_pulse as pulse

# A function that runs on a GPU while the qubits wait. Its answer comes back
# within 3.8 us of the request. In simulation, this Python body gives the answer.
@pulse.classical(link="gpu", max_latency_ns=3_800)
def decode(syndrome: pulse.Bits) -> bool:
    return bool(syndrome[0])

@pulse.kernel
def feedback_and_adapt(q):
    d = get_drive_line(q)
    r = get_readout_line(q)
    pi_pulse = d.get_calibration(pulse.gates.X)
    outcome = readout(r, square(300 * pulse.ns, 0.05))

    # Ask the decoder, waiting at most 4 us. If it's late, use the raw outcome.
    request = decode.submit([outcome])
    in_time, flip = request.result(timeout=4 * pulse.us)
    correct = flip if in_time else outcome
    sync(d, r)
    if correct:
        drive(d, pi_pulse)

# The control system reaches the GPU over a link named "gpu" (NVQLink).
control_system = pulse.ControlSystem(links={"gpu": pulse.Link(feedback_ns=50)})
qs = pulse.quantum_system("transmon_surface17")
compiled = pulse.compile(feedback_and_adapt, control_system=control_system)
scheduled = compiled.lower(qs.qudits[0])
report = scheduled.classical_report()   # when each answer is due: decode, slack 0 ns

The decoder's 3.8 µs latency follows FPGA-GPU-FPGA round trips over NVQLink, which measure 2.9–3.8 µs on an RTX PRO 6000 Blackwell host (details).

Timeline of one shot showing readout, a classical decode call with a timeout, a conditional drive pulse, and a runtime-chosen wait
Figure 1. One shot with real-time calls. The decoder's answer gates a conditional pulse, as in feedback_and_adapt, and an estimator sets a wait whose length is known only at runtime, as described in the calibration section below.

There are three points to note about this example:

  • The call is a contract. @pulse.classical records which function to call, the exact data layout going in and out, and a latency budget. That's everything a control system needs to schedule the call and everything a GPU service needs to answer it.
  • Late answers are handled explicitly. .result(timeout=...) returns an in-time flag along with the value, so a kernel can fall back instead of stalling the QPU.
  • Runtime values stay schedulable. A wait whose length comes from an estimator, like the adaptive T1 tracker's below, carries bounds, so the scheduler can still reason about timing across lines.

Underneath, this rests on mid-circuit measurement and control flow that survive from the Python trace, through region-aware scheduling, into our simulators. In simulation the Python body of each classical function runs. On hardware, the same declaration is what a control-system backend implements, whether the function runs on the controller's FPGA or on a GPU over NVQLink. It's also the hook for plugging CUDA-Q QEC decoders into GPU-in-the-loop syndrome decoding.

Where the function body runs How it's declared What fits in the budget
Python, in simulation any @pulse.classical function Develop and test the full loop against a simulated quantum system
Controller FPGA a link to the controller, such as link="controller" Sub-microsecond updates, such as an estimator
NVIDIA GPU over NVQLink a link to the GPU, such as link="gpu" Microsecond-scale work such as QEC decoding and heavier estimators

In this release, classical calls run end to end in simulation. Lowering them onto specific controllers and NVQLink transports will be available in a future release.

Real-time decoding with a deadline

QEC has demanding timing requirements. The 17-qubit processor modeled below ran its distance-3 surface-code cycle in 1.1 µs, then ran decoding, finally applying corrections in post-processing (Krinner et al.). In real-time operation however, a decoder has to produce answer while the qubits wait, and the program needs a plan for the shots when the decoder is late or unable to respond.

Fast implementations of popular decoders are defined in CUDA-Q QEC and a pulse program can call them as a CUDA-Q kernel does: pulse.classical takes CUDA-Q QEC's own real-time functions, cudaq_qec.qec.enqueue_syndromes and get_corrections, with a link and a latency budget. On hardware, their requests are the messages of CUDA-Q QEC's decoding server; in simulation, the decoder you configured answers them. As an example, here's one round of a distance-3 repetition code with CUDA-Q QEC's GPU decoder, nv-qldpc-decoder (belief propagation with ordered-statistics post-processing, BP+OSD). Note that reproducing this example requires a Linux system running Python 3.12 or 3.13 and connected to an NVIDIA GPU.

import cudaq_qec
import numpy as np

import cudaq_pulse as pulse

# Set up decoder 0 in CUDA-Q QEC: BP+OSD on the GPU for a distance-3
# repetition code (2 syndrome bits in, 1 correction bit per data qubit out).
cudaq_qec.configure_decoders_from_str("""
decoders:
  - id: 0
    type: nv-qldpc-decoder
    block_size: 3
    syndrome_size: 2
    H_sparse: [0, 1, -1, 1, 2, -1]
    O_sparse: [0, -1, 1, -1, 2, -1]
    D_sparse: [0, -1, 1, -1]
    decoder_custom_args:
      error_rate_vec: [0.1, 0.1, 0.1]
      use_sparsity: true
      max_iterations: 50
      use_osd: true
      osd_method: 3
      osd_order: 7
""")

# CUDA-Q QEC's real-time calls, sent to the decoder over the GPU link.
# Corrections come back in about 62 us, and 75 us at worst.
enqueue_syndromes = pulse.classical(cudaq_qec.qec.enqueue_syndromes, link="gpu")
get_corrections = pulse.classical(cudaq_qec.qec.get_corrections, link="gpu",
                                  nominal_latency_ns=62_000, max_latency_ns=75_000)

@pulse.kernel
def qec_round(data, ancillas, deadline_ns: int):
    # ... syndrome-extraction pulses on data and ancillas go here ...
    # Read out the two ancillas to get the syndrome.
    s0 = readout(get_readout_line(ancillas[0]), square(400 * pulse.ns, 0.05))
    s1 = readout(get_readout_line(ancillas[1]), square(400 * pulse.ns, 0.05))

    # Send the syndrome to decoder 0 (round 0), then wait for its
    # 3 correction bits, but no longer than the deadline.
    enqueue_syndromes.submit(0, [s0, s1], 0)
    request = get_corrections.submit(0, 3, False)
    in_time, fix = request.result(timeout=deadline_ns * pulse.ns)

    # If the decoder is late, use a lookup table on the controller instead.
    table = [s0 and not s1, s0 and s1, s1 and not s0]
    for i in range(3):
        flip = fix[i] if in_time else table[i]
        if flip:
            drive(get_drive_line(data[i]), square(20 * pulse.ns, np.pi / 20))   # π pulse

The kernel sends the syndrome, asks for corrections with a deadline, and keeps a lookup table on the controller for shots where the answer is late. The deadline is a kernel parameter, so you can trade waiting against falling back without editing the program. Compiling checks the timing before anything runs:

qs = pulse.quantum_system("transmon_lattice:5")   # five transmons
data = qs.qudits[0:3]
ancillas = qs.qudits[3:5]

control_system = pulse.ControlSystem(links={"gpu": pulse.Link(feedback_ns=50)})
compiled = pulse.compile(qec_round, quantum_system=qs, control_system=control_system)
scheduled = compiled.lower(data, ancillas, 80_000)   # deadline: 80 us
report = scheduled.classical_report()   # get_corrections is due at 80.5 us

In a simulation that starts from the state syndrome extraction leaves, every single-qubit error is corrected on the right qubit, by the decoder when it answers in time and by the table when it doesn't. examples/27_realtime_decoding.py runs it end to end.

One QEC round: syndrome readout, a request to the GPU decoder, a deadline on the controller, and two arms that apply either the decoder's correction or the fallback table's
Figure 2. One round of qec_round. The correction pulse plays from the decoder's answer if it arrives by the deadline, or from the controller's lookup table if it doesn't.

The same messages also went to a real decoder. On a workstation with an NVIDIA RTX A6000 GPU, the CUDA-QX decoding server ran with cudaq-realtime, serving the same nv-qldpc-decoder configuration on the GPU, and CUDA-Q Pulse's syndrome messages connected to it with no changes. Over 5,000 shots, the server's corrections matched the local emulation exactly, and shots whose answer came back after the deadline took the fallback table. From sending the syndrome to receiving the correction, round trips took about 62 µs typically and 75 µs at the 99.9th percentile, the latency budget in the code above. Replaying those round trips in CUDA-Q Pulse's emulator, a deadline at the median sends 45% of shots to the fallback table, one at the 99th percentile 0.75%, and one at the 99.9th percentile 0.06%.

Those numbers aren't a QPU's latency, and they are different from the 2.9–3.8 µs NVQLink round trips above. The test was host-to-GPU loopback: a process on the same machine sent each request over UDP through the operating system's network stack, and the server launched the decoder from the host. On NVQLink, requests travel from the controller's FPGA to the GPU without passing through the host's operating system. Loopback shows that the messages, corrections, and fallback logic are right; the hardware path brings the round trip down to a few syndrome rounds.

Calibration as one program

Calibration is where real-time classical control pays off first. Researchers track fluctuating qubit relaxation in real time with a Bayesian estimator (Berritta et al., Phys. Rev. X 16, 011025 (2026)) and calibrate and benchmark superconducting qubits at millisecond scale (Marciniak et al., arXiv:2602.11912). Both experiments run their estimators on the controller's FPGA, because the feedback loop has to close in microseconds.

We implemented that protocol end to end in CUDA-Q Pulse. Characterization, estimation, parameter update, and pulse regeneration are a single program, with the estimators declared on the controller link.

Here's the core of the adaptive T1 tracker. Each shot's wait comes from the previous shot's estimate, and the estimator has 500 ns to answer.

import cudaq_pulse as pulse
from cudaq_pulse.classical import calibration as cal

# Berritta et al.'s Bayesian update of the T1 estimate (a gamma posterior over
# 1/T1, with parameters shape and rate), which also picks the next wait.
# It runs on the controller, within 500 ns.
@pulse.classical(link="controller", max_latency_ns=500)
def update_t1(bit: pulse.Bits, shape: float, rate: float,
              wait_ns: float) -> tuple[float, float, float]:
    shape, rate = cal.adaptive_t1_update(shape, rate, bit[0], wait_ns,
                                         error_1to0=0.11, error_0to1=0.14)
    next_wait_ns = cal.adaptive_t1_wait(shape, rate)
    next_wait_ns = min(max(next_wait_ns, 100.0), 200_000.0)   # keep it in 100 ns to 200 us
    return shape, rate, next_wait_ns

@pulse.kernel
def track_t1(q, shots_count: int, shape: float, rate: float, wait_ns: float):
    d = get_drive_line(q)
    r = get_readout_line(q)
    pi_pulse = d.get_calibration(pulse.gates.X)
    for shot in range(shots_count):     # every shot adapts, inside one kernel
        drive(d, pi_pulse)              # excite, then let it decay for wait_ns
        wait(d, wait_ns * pulse.ns, bounds=(100 * pulse.ns, 200 * pulse.us))
        sync(d, r)
        outcome = readout(r, square(300 * pulse.ns, 0.05))
        # The controller updates the estimate and picks the next wait.
        shape, rate, wait_ns = update_t1.submit([outcome], shape, rate, wait_ns).result()
        sync(d, r)
        if outcome:
            drive(d, pi_pulse)          # active reset
The adaptive loop of pi pulse, wait, readout, and Bayesian update, with a schematic of wait lengths changing from shot to shot
Figure 3. Fifty adaptive shots in one kernel. The estimator on the controller updates its posterior after each readout and picks the next wait. The shot lengths on the right are schematic, not data.

We checked the tracker against the paper in simulation. On a model qubit with a T1 of 160 µs and the paper's assignment errors, 400 simulated runs of 50 adaptive shots gave a median estimate of 155 µs, with 68% of runs between 123 and 195 µs. Berritta et al. report 159 µs, with a 68% interval of 131 to 202 µs, on their processor.

Simulated T1 estimate over 50 adaptive shots. A shaded band, the uncertainty of a single run's estimate, narrows from about 97 to 328 µs around the starting guess of 150 µs to about 122 to 212 µs around the true T1 of 160 µs in the model. Five individual runs are drawn as thin lines. On the right, a histogram of the final estimates of 400 runs, with brackets comparing the simulated median of 155 µs and 68% range of 123 to 195 µs with Berritta et al.'s 159 µs and 68% interval of 131 to 202 µs
Figure 4. The T1 estimate after each of 50 adaptive shots, in simulation. The uncertainty of a single run's estimate narrows from the starting guess to around the model's true T1. On the right, the final estimates of 400 runs beside Berritta et al.'s result.

The same structure covers the rest of the protocol; with another estimator or other pulses, the compiler schedules the new loop. Because the estimator is ordinary Python in simulation, you can develop and test it against a simulated quantum system before you lower it to a controller.

A 17-qubit quantum system on GPUs

To test programs like these without access to a physical QPU, CUDA-Q Pulse includes a physics model of the 17-qubit superconducting processor used to demonstrate repeated error correction in a distance-3 surface code (Krinner et al., Nature 605, 669 (2022)). The model accounts for exchange coupling, residual ZZ, thermal populations, and Hahn-echo dephasing, and it exposes fitted CZ parameters for all 24 coupled pairs. Flux pulses aren't simulated yet, so a program schedules each CZ as its calibrated time slot.

Layout of the 17-qubit surface-code quantum system with 9 data qubits, 8 ancillas, and 24 couplers, beside the list of modeled effects
Figure 5. The transmon_surface17 quantum system. Pulse programs lower through the QOp operator dialect to cuDensityMat for GPU time evolution.

Selecting the quantum system requires only a single line of code, as used by most examples in this post:

import cudaq_pulse as pulse

qs = pulse.quantum_system("transmon_surface17")

When a kernel is simulated with backend="gpu", the compiler lowers the Pulse dialect into Hamiltonian and Lindblad terms in the QOp dialect and maps those to NVIDIA cuDensityMat. The pulse program you simulate is the same one you'd hand to a control system.

Compiles fast enough for QEC-scale programs

A pulse compiler for fault-tolerant systems has to keep up with large codes. The MLIR compiler in CUDA-Q Pulse handles them comfortably:

Program (one synthetic syndrome-extraction cycle) Size Compile time Peak memory
Distance-11 rotated surface code 241 qubits, 2,401 pulse operations 31 ms 39 MB
Distance-21 rotated surface code 881 qubits, 9,201 pulse operations 120 ms 45 MB
Distance-31 rotated surface code 1,921 qubits, 20,401 pulse operations 266 ms 53 MB
Distance-51 rotated surface code 5,201 qubits, 56,001 pulse operations 790 ms 88 MB
[[144,12,12]] bivariate bicycle (gross) code † 288 qubits, 4,320 pulse operations 54 ms 41 MB

† The gross-code benchmark ships in v0.1.1; the other rows reproduce with v0.1.0's benchmarks/simulation/qec_scaling.py.

Each surface-code row comes from benchmarks/simulation/qec_scaling.py --distances D --repeats 5, run in its own process for each distance, without optimization passes, on an x86-64 Linux workstation (Python 3.12 and the v0.1.0 wheels, in the manylinux container the wheels are built in). The compile time is the median of five compiles, and the peak memory is that of the whole Python process; the repository's performance notes give the host, the version, and the run-to-run spread for distance 31.

Under the hood

CUDA-Q Pulse architecture: Python kernels go through Capture, Pulse MLIR, and Compile to three destinations: Simulate, Run on hardware, and Real-time classical
Figure 6. One compiled program, three destinations.

The @pulse.kernel decorator captures the function's CPython bytecode. Tracing writes each operation into a compact packed buffer, which crosses into C++ in a single zero-copy call and becomes an in-memory MLIR module in the Pulse dialect. From there, MLIR passes verify the program, apply virtual-Z, fuse adjacent pulses, and schedule every operation as late as possible while respecting syncs and control-flow regions.

The scheduled program can be directed to one of three endpoints:

  • Simulation: the NumPy reference on any CPU, or Pulse → QOp → cuDensityMat on GPUs, for quantum systems like the 17-qubit one above.
  • Control systems: a vendor backend takes the program from export_to_controller() (pulses, waits, syncs, loops, and measurement-conditioned branches) and emits code for its own sequencers. CUDA-Q Pulse doesn't depend on cudaq-realtime, so backends can start with the pulse layer alone.
  • Real-time classical functions: @pulse.classical calls become first-class operations in the IR, with their data layout and deadline attached.

Each dialect performs a round-trip through parse and print, so MLIR from CUDA-Q Pulse is an artifact you can inspect and hand to another toolchain. Control-system teams that only need the compiler can run the dialects and passes on MLIR files with the cudaq-pulse-opt driver, which comes with the package.

Get started

To work with CUDA-Q Pulse, install from PyPI and run the examples:

pip install cudaq-pulse            # compiler and CPU simulation (Linux, macOS)
pip install "cudaq-pulse[cu13]"    # plus GPU simulation with CUDA 13 (or [cu12])
python -m cudaq_pulse.doctor       # what's installed, and whether GPU simulation works
  • Explore the code. The CUDA-Q Pulse repository has numbered examples that run from a single-qubit Rabi experiment to GHZ state preparation.
  • Build a backend. If you build control systems, the controller export is the integration point. Open an issue on GitHub and tell us about your sequencer.
  • Learn how to use CUDA-Q Pulse in real-time workflows by leveraging cudaq-realtime and NVQLink to deliver microsecond GPU calls to the controller.

Share on Share on Share on LinkedIn