Skip to content

About

No description, website, or topics provided.

Resources

Code of conduct

Contributing

Security policy

Stars

17 stars

Watchers

1 watching

Forks

Latest commit

 

History

343 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

CUDA-Q Pulse: a Python pulse kernel beside a timeline of drive, readout and GPU lanes. A readout result goes to a GPU decoder over NVQLink within a latency budget, and the answer conditions the next drive pulse.

CI Docs License: Apache-2.0

CUDA-Q Pulse

About

cudaq-pulse is a Python library and compiler for programming quantum processors at the pulse level: the drive and readout pulses, their timing, and the real-time classical decisions between them. It is for people who build and run QPUs and their control systems: hardware and control engineers, calibration and quantum error correction researchers, and controller vendors who want one open format to compile to. It belongs to the CUDA-Q family and shares its goal of one programming model across QPUs, but works at the level below CUDA-Q's gates and kernels and installs on its own, without CUDA-Q. The documentation covers the tutorials, user guide and API reference.

Highlights and Key Features

cudaq-pulse lets developers write pulses, measurements and the real-time classical logic between them as one Python program. That program compiles to an open MLIR pulse dialect that any controller can target.

  • Real-time control: measure-and-react, feedback and calls to classical services (such as decoders) are part of the program. The compiler checks each answer arrives before the pulse that depends on it, given the controller's latency.
  • QEC at scale: syndrome-extraction cycles compile in milliseconds; a distance-31 surface code cycle compiles in 263 ms.
  • Composable QPUs: a QPU is described as data: its qudits, lines, controllers and the links between them. One program can span several controllers, and it is checked against that description when it compiles.
  • Hardware portability: the same compiled program exports to controller backends, so Python front ends are decoupled from each underlying control interface.

Underneath are a Python kernel DSL, the Pulse and Classical MLIR dialects, and their compiler passes. cudaq-pulse does not depend on CUDA-Q. The wheel contains its own statically linked MLIR, so pip is the only installer you need.

cudaq-pulse is an experimental, community-driven research project under active development. We're releasing it now because our partners want a stable, universal pulse dialect that separates Python DSLs from quantum control interfaces.

Documentation: https://nvidia.github.io/cudaq-pulse/

Project Status

Note

The pulse layer is where much of the open work in quantum control happens, and we want to build it in the open with the people who use it. Expect bugs, incomplete features, and incompatible changes to the Python APIs, MLIR dialects and file formats between releases. It is not a supported CUDA-Q product feature. We invite you to try it with your own quantum systems and help shape its direction.

Install

Install from PyPI; pip picks the wheel for your platform:

python -m venv .venv && source .venv/bin/activate

# Compiler and CPU simulation: compile kernels, inspect the MLIR, simulate
# with the NumPy reference, run cudaq-pulse-opt.
pip install cudaq-pulse

For GPU simulation on Linux, also install one CUDA extra, never both:

# CUDA 12 libraries: NVIDIA driver 525.60.13 or newer.
pip install "cudaq-pulse[cu12]"

# CUDA 13 libraries instead: NVIDIA driver 580 or newer.
# pip install "cudaq-pulse[cu13]"

Then check what was installed and whether it works:

python -m cudaq_pulse.doctor

cudaq-pulse-opt, the MLIR driver, comes along automatically: it is in cudaq-pulse-tools, a wheel of its own, one per platform for every Python, which cudaq-pulse requires at the same version. Each release on the GitHub releases page also carries the wheels and the source distribution.

[gpu] is an alias for [cu12]. The cu12 and cu13 extras install into the same directories, so install only one of them per environment.

Platform Python What you get
Linux x86_64 and aarch64, glibc 2.28+ 3.12+ Compiler and CPU simulation; GPU simulation with [cu12] or [cu13]
macOS 11+ arm64 3.12+ Compiler and CPU simulation

GPU execution needs an NVIDIA GPU (compute capability 7.0 or newer) and a driver for the CUDA major you installed:

Extra Minimum Linux driver
[cu12] (or [gpu]) 525.60.13
[cu13] 580

The driver is the only system requirement. The extras install cuDensityMat and the CUDA runtime libraries from PyPI, so no CUDA toolkit, cuQuantum SDK, or container is required.

Troubleshooting

Run python -m cudaq_pulse.doctor first. It prints the version, the wheel platform, whether CPU simulation works, which CUDA extra is installed, each GPU library with its path or load error, and the driver version and device count. Without a CUDA extra it passes on CPU simulation alone and says how to enable GPU simulation. With one installed, it exits non-zero if GPU simulation does not work: a driver too old for the extra, both extras installed, or a library that does not load.

Without a usable GPU, everything except GPU simulation still works, including the CPU reference (pulse.simulate(..., backend="cpu"), the default). GPU simulation fails with a specific error rather than degrading:

Situation Error raised by pulse.simulate(..., backend="gpu")
Wheel without GPU support (macOS, or a compiler-only source build) GpuSupportNotBuiltError
GPU support built in, but no CUDA extra, both extras, or a library fails to load GpuRuntimeLoadError
Libraries load, but no device, or the driver is too old GpuDeviceUnavailableError

All three derive from cudaq_pulse.runtime.GpuRuntimeError. The runtime for CUDA 12 or 13 is chosen from the installed extra; set CUDAQ_PULSE_CUDA=12 or CUDAQ_PULSE_CUDA=13 to choose it explicitly.

Quick example

import cudaq_pulse as pulse

cal = {"duration": 32 * pulse.ns, "sigma": 8 * pulse.ns}


@pulse.kernel
def rabi_oscillation(qubit, amplitude: float):
    drive_line = get_drive_line(qubit)
    drive(drive_line, gaussian(cal["duration"], amplitude, cal["sigma"]))


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

result = pulse.simulate(rabi_oscillation, qubit, 0.5)  # NumPy reference, no GPU needed
print(f"P(1) = {result.level_population(1):.3f}")  # P(1) = 0.972
print(rabi_oscillation.lower(qubit, 0.5).mlir())  # the scheduled Pulse MLIR

pulse.simulate(kernel, *args) compiles the call for the quantum system of its qudit handles, with frequencies from the quantum system, and evolves it; this pulse leaves the qubit almost fully excited. kernel.lower(*args) compiles the call without running it. Calling the kernel, rabi_oscillation(qubit, 0.5), compiles and runs it in one step, and pulse.compile(kernel) compiles ahead of the call. A float parameter stays symbolic, so a sweep over it compiles once. The compiler traces the Python kernel, builds Pulse dialect IR, applies the selected transformations, and emits scheduled MLIR. The wheel also installs cudaq-pulse-opt, the MLIR driver for the pulse dialects:

cudaq-pulse-opt --pulse-to-qop kernel.mlir

The user guide covers the kernel model, operations, compilation, custom passes, and GPU execution. examples/ has runnable programs, and examples/custom_passes/ shows how to write passes in Python and as C++ plugins.

Kernels can also call classical functions while the QPU runs (@pulse.classical, fn.submit(...).result()): decoders, estimators or calibration updates whose answers the same shot uses, scheduled with their latency budget and simulated or emulated in virtual time. A compiled kernel exports to an out-of-tree controller backend with ScheduledKernel.export_to_controller(), and cudaq_pulse.backends finds the backends installed beside cudaq-pulse; see the "Classical Calls at QPU Runtime" and "Writing a Controller Backend" guides.

Run the test suite against your installation

The tests live in this repository, not in the wheel. They import whichever cudaq_pulse is installed, so they check exactly what you installed:

git clone https://github.com/NVIDIA/cudaq-pulse.git
cd cudaq-pulse
pip install --group test        # pytest, hypothesis, lit (pip 25.1+)

pytest tests -m "not gpu"       # any installation
pytest tests                    # GPU installations: also runs the GPU suite

Selecting the GPU tests on an installation that cannot run them stops pytest immediately with the reason, instead of skipping them.

Build from source

See CONTRIBUTING.md. In short, pip install ./packaging/cudaq-pulse-tools . from a clone builds the two wheels, cudaq-pulse-tools and cudaq-pulse, locally against the pinned, checksum-verified MLIR toolchain, which CMake downloads on supported platforms (or set MLIR_DIR to your own MLIR 22 build). Nothing else is built from source. Each GitHub release carries the wheels and the source distribution.

Notice and disclaimer

NOTICE AND DISCLAIMER: This software automatically retrieves, accesses or interacts with external materials. Those retrieved materials are not distributed with this software and are governed solely by separate terms, conditions and licenses. You are solely responsible for finding, reviewing and complying with all applicable terms, conditions, and licenses, and for verifying the security, integrity and suitability of any retrieved materials for your specific use case. This software is provided "AS IS", without warranty of any kind. The author makes no representations or warranties regarding any retrieved materials, and assumes no liability for any losses, damages, liabilities or legal consequences from your use or inability to use this software or any retrieved materials. Use this software and the retrieved materials at your own risk.

What installing and building retrieve:

Contributing and support

CONTRIBUTING.md covers building, testing and the versioning policy, SUPPORT.md where to ask for help, and CHANGELOG.md what changed in each release. Everyone taking part follows the Code of Conduct.

License

cudaq-pulse is licensed under the Apache License 2.0. The wheels also contain third-party software (LLVM and MLIR, nanobind, robin-map) under the licenses listed, with their texts, in THIRD_PARTY_NOTICES; the texts are also in LICENSES/.

Security

Report security vulnerabilities to NVIDIA as described in SECURITY.md, not through GitHub issues.

About

No description, website, or topics provided.

Resources

Code of conduct

Contributing

Security policy

Stars

17 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages