{"id":9154,"library":"openpulse","title":"OpenPulse Python AST Reference","description":"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.","status":"active","version":"1.0.1","language":"en","source_language":"en","source_url":"https://github.com/openqasm/openpulse/","tags":["Quantum Computing","AST","OpenQASM","Pulse","Grammar","Quantum Control"],"install":[{"cmd":"pip install openpulse","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"OpenPulse reuses classical types and statements from OpenQASM 3, making 'openqasm3' a core dependency for correct AST structure and parsing.","package":"openqasm3"}],"imports":[{"note":"The primary entry point for parsing OpenPulse strings into an AST.","symbol":"parser","correct":"from openpulse import parser"},{"note":"Accesses the Abstract Syntax Tree node definitions for OpenPulse constructs. Many nodes are re-exported from `openqasm3.ast`.","symbol":"ast","correct":"from openpulse import ast"}],"quickstart":{"code":"from openpulse import parser\nfrom openpulse.ast import Program\n\n# Define a simple OpenPulse string\npulse_string = \"\"\"\nOPENQASM 3.0;\ncal {\n  waveform w = sine(1.0, 0.5, 0.0, 0.0);\n  play(0, w);\n}\n\"\"\"\n\n# Parse the OpenPulse string into an AST\nast_program = parser.parse(pulse_string)\n\n# Verify the type of the parsed program\nassert isinstance(ast_program, Program)\nprint(\"Successfully parsed OpenPulse program.\")\n# print(ast_program.pretty_print()) # Uncomment to see structured output if available\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions, especially with new OpenQASM/OpenPulse specification releases."},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Use `from openpulse import parser` and then call `parser.parse(pulse_string)`.","cause":"The main parsing function is not directly exposed as `parse` at the top-level `openpulse` module. It resides in `openpulse.parser`.","error":"from openpulse import parse\nModuleNotFoundError: No module named 'openpulse.parse'"},{"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.","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.","error":"openpulse.parser.exceptions.ParseError: MismatchedTokenException(...)\nopenpulse.parser.exceptions.NoViableAltException(...)"}]}