OpenPulse Python AST Reference

1.0.1 · active · verified Thu Apr 16

OpenPulse (version 1.0.1) is a Python library providing a reference Abstract Syntax Tree (AST) for the OpenPulse grammar. It enables the representation and manipulation of pulse-level definitions (`cal` and `defcal` blocks) within the OpenQASM 3 ecosystem, reusing classical types and statements from the `openqasm3` library. The library includes AST nodes and a parser, serving as a foundational component for tools that process pulse-level control in quantum computing.

Common errors

```
from openpulse import parse
ModuleNotFoundError: No module named 'openpulse.parse'
```
cause The main parsing function is not directly exposed as `parse` at the top-level `openpulse` module. It resides in `openpulse.parser`.

fix Use `from openpulse import parser` and then call `parser.parse(pulse_string)`.
```
openpulse.parser.exceptions.ParseError: MismatchedTokenException(...)
openpulse.parser.exceptions.NoViableAltException(...)
```
cause The input OpenPulse string does not conform to the OpenPulse grammar. This could be due to syntax errors, incorrect keywords, or malformed pulse definitions.

fix Carefully review the `pulse_string` for syntax errors against the OpenPulse specification. Ensure all required elements (like `OPENQASM 3.0;` or `cal { ... }`) are present and correctly formatted. Consult OpenPulse examples for valid syntax.

Warnings

breaking Updates to the OpenPulse or OpenQASM 3 grammar specifications can lead to breaking changes in the `openpulse` AST structure and parser behavior. Code relying on specific AST node names or hierarchies may need adjustment.
Fix: Always review the release notes of `openpulse` and `openqasm3` for grammar updates. Update your code to reflect changes in AST node names, attributes, or the expected parsing output.
gotcha The `openpulse` library heavily depends on and reuses components from `openqasm3`. Errors related to classical types, statements, or overall program structure within OpenPulse definitions often stem from issues or misunderstandings of the underlying OpenQASM 3 grammar.
Fix: Ensure `openqasm3` is correctly installed and compatible. Familiarize yourself with the OpenQASM 3 specification in addition to OpenPulse, particularly regarding classical control flow and type systems.

Install

pip install openpulse Install latest version

Imports

parser
```
from openpulse import parser
```
The primary entry point for parsing OpenPulse strings into an AST.
ast
```
from openpulse import ast
```
Accesses the Abstract Syntax Tree node definitions for OpenPulse constructs. Many nodes are re-exported from `openqasm3.ast`.

Quickstart

This quickstart demonstrates how to use the `openpulse.parser` to parse a basic OpenPulse string into its Abstract Syntax Tree representation. The resulting `Program` object is an instance of the `openpulse.ast.Program` class, allowing programmatic inspection and manipulation of the pulse-level instructions.

from openpulse import parser
from openpulse.ast import Program

# Define a simple OpenPulse string
pulse_string = """
OPENQASM 3.0;
cal {
  waveform w = sine(1.0, 0.5, 0.0, 0.0);
  play(0, w);
}
"""

# Parse the OpenPulse string into an AST
ast_program = parser.parse(pulse_string)

# Verify the type of the parsed program
assert isinstance(ast_program, Program)
print("Successfully parsed OpenPulse program.")
# print(ast_program.pretty_print()) # Uncomment to see structured output if available

view raw JSON →