app.processing.pre.converter

Convert OpenQASM 2.x/3.x code into an OpenQASM 3.1 AST.

The conversion process includes handling unsupported gates, transforming obsolete syntax and integrating necessary gate definitions from external libraries.

Warning

Comment Removal: All single-line (//) and multi-line (/* */) comments will be permanently removed during the conversion process. Ensure that important notes or documentation within the OpenQASM code are backed up separately.

Warning

Can’t handle ``opaque``: This converter will raise an error if it encounters an opaque, as this is unsupported in OpenQASM 3.x.

Warning

Custom gates only for OpenQASM 2.x CustomOpenqasmLib’s have no effect if the code is already OpenQASM 3.x.

..note::

Used OpenQASM version: 3.1 If the code is OpenQASM 2.x, it will be converted to OpenQASM 3.1. If it is already 3.x, the version is not changed.

Key Features

  • Automated OpenQASM Conversion: Seamlessly converts OpenQASM 2.x code into valid OpenQASM 3.1 format.

  • Unsupported Gate Management: Detects and provides definitions for gates specified in “qelib1.inc”.

  • Library Integration: Incorporates additional OpenQASM gate definitions from provided strings.

Module Contents

class app.processing.pre.converter.CustomOpenqasmLib(name: str, content: str)

Encapsulates an OpenQASM 3.x-compatible gate library for custom gate resolution.

Used to provide gate definitions (e.g., from qelib1.inc) that can be injected into converted OpenQASM 2.x code. Only gate definitions (QuantumGateDefinition) are retained.

Parameters:
exception app.processing.pre.converter.QASMConversionError(msg: str, node: app.model.CompileRequest.Node | None = None)

Custom exception raised for errors occurring during QASM conversion.

Parameters:

  • msg (str)

  • node (app.model.CompileRequest.Node | None)

class app.processing.pre.converter.ApplyCustomGates(custom_libs: dict[str, CustomOpenqasmLib], lib_replacements: dict[str, str])

AST visitor that injects custom gate definitions and filters include statements.

This visitor: 1. Tracks which gate definitions from the custom libs are actually used. 2. Replaces outdated include directives (e.g., qelib1.inc) if provided as custom libs. 3. Inserts required gate definitions and imports into the AST.

Parameters:
visit_QuantumGate(node: openqasm3.ast.QuantumGate) → openqasm3.ast.QASMNode

Search for usages of custom declared gates.

Parameters:

node (openqasm3.ast.QuantumGate) – Quantum gate AST node.

Return type:

openqasm3.ast.QASMNode

visit_Include(node: openqasm3.ast.Include) → None

Remove and store required includes, possible modify via lib_replacements.

Parameters:

node (openqasm3.ast.Include) – The include node from the OpenQASM AST.

Return type:

None

visit_Program(node: openqasm3.ast.Program) → openqasm3.ast.QASMNode

Apply the visitor.

  1. Remove imports + gather info

  2. Add required (possible imports) back

  3. Insert definitions of custom gates

Returns:

The modified program node with injected gates and imports.

Parameters:

node (openqasm3.ast.Program)

Return type:

openqasm3.ast.QASMNode

class app.processing.pre.converter.QASMConverter(custom_libs: list[CustomOpenqasmLib] | None = None)

Main interface for converting OpenQASM 2.x into OpenQASM 3.1 ASTs.

If the input code is already in OpenQASM 3.x, it is returned as-is (after parsing). Custom libraries for legacy gates can be provided via CustomOpenqasmLib and will be injected automatically.

Parameters:

custom_libs (list[CustomOpenqasmLib] | None)

add_custom_gate_lib(lib: CustomOpenqasmLib) → None

Append custom lib to internal data.

Parameters:

lib (CustomOpenqasmLib) – The custom gate library to add.

Return type:

None

parse_to_qasm3(qasm2_code: str) → openqasm3.ast.Program

Convert entire OpenQASM 2.x code to OpenQASM 3.1 AST or return parsed OpenQASM 3.x. directly

Warning: All comments present in the given OpenQASM code will be removed!!!

This method processes a OpenQASM 2.x/3.x program, transforming it into valid OpenQASM 3.x. The conversion process includes the following steps:

  1. Check for opaque, raise error when found

  2. Parse into AST

  3. If version 3.x, return AST

  4. If neither version 3.x nor 2.x, raise error

  5. Set version 3.1

  6. Include gates from custom libs, replace/remove obsolete imports

Parameters:

qasm2_code (str) – A string containing OpenQASM 2.x/3.x code to be converted.

Returns:

AST in OpenQASM 3.x format.

Raises:

QASMConversionError – If any line contains an unsupported OpenQASM version, library or opaque was used.

Return type:

openqasm3.ast.Program

app.processing.pre.converter.parse_to_openqasm3(code: str, custom_libs: list[CustomOpenqasmLib] | None = None) → openqasm3.ast.Program

Parse an OpenQASM 2.x/3.x string to an equivalent OpenQASM 3.1 AST.

Parameters:

  • code (str) – The code-string to be parsed and converted if required.

  • custom_libs (list[CustomOpenqasmLib] | None) – An optional list of custom provided libraries. “qelib1.inc” is builtin.

Returns:

The converted/parsed OpenQASM 3.1 AST.

Return type:

openqasm3.ast.Program