app.processing.pre.converter
============================

.. py:module:: app.processing.pre.converter

.. autoapi-nested-parse::

   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
---------------

.. py:class:: 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.


.. py:exception:: QASMConversionError(msg: str, node: app.model.CompileRequest.Node | None = None)



   Custom exception raised for errors occurring during QASM conversion.


.. py:class:: 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.


   .. py:method:: visit_QuantumGate(node: openqasm3.ast.QuantumGate) -> openqasm3.ast.QASMNode

      Search for usages of custom declared gates.

      :param node: Quantum gate AST node.



   .. py:method:: visit_Include(node: openqasm3.ast.Include) -> None

      Remove and store required includes, possible modify via lib_replacements.

      :param node: The include node from the OpenQASM AST.



   .. py:method:: 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

      :return: The modified program node with injected gates and imports.



.. py:class:: 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.


   .. py:method:: add_custom_gate_lib(lib: CustomOpenqasmLib) -> None

      Append custom lib to internal data.

      :param lib: The custom gate library to add.



   .. py:method:: 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

      :param qasm2_code: A string containing OpenQASM 2.x/3.x code to be converted.

      :return: AST in OpenQASM 3.x format.

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



.. py:function:: 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.

   :param code: The code-string to be parsed and converted if required.
   :param custom_libs: An optional list of custom provided libraries. "qelib1.inc" is builtin.
   :return: The converted/parsed OpenQASM 3.1 AST.