Add OpenQASM 3 exporter for circuits

This commit introduces an OpenQASM 3 exporter for Graphix
circuits. The functionality was originally proposed in #245 but has
not yet been merged.

The added tests verify that a round-trip through the OpenQASM 3
representation preserves Graphix circuits, using the
graphix-qasm3-parser plugin.  This plugin is therefore
added as a `requirements-dev.txt` dependency.

CI is updated so that `pip install .` can detect the current version
number of Graphix, instead of the default `0.1`: to do so, the whole
history and the tags should be available.  We removed the "-e" option
from CI because it is useless in the CI context.

In the long term the `qasm3_exporter` module will also host the
pattern exporter, but that feature is intentionally omitted from this
PR to keep the change focused.

Author: thierry-martinez

.github/workflows/ci.yml

@@ -23,7 +23,10 @@ jobs:
     runs-on: ${{ matrix.os }}
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0  # Fetch all, necessary to find tags and branches
+          fetch-tags: true
 
       - uses: actions/setup-python@v5
         with:

.github/workflows/cov.yml

@@ -14,7 +14,10 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0  # Fetch all, necessary to find tags and branches
+          fetch-tags: true
 
       - name: Set up Python
         uses: actions/setup-python@v5

.github/workflows/doc.yml

@@ -20,7 +20,10 @@ jobs:
     name: "Check documentation"
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0  # Fetch all, necessary to find tags and branches
+          fetch-tags: true
 
       - uses: actions/setup-python@v5
         with:

.github/workflows/typecheck.yml

@@ -19,7 +19,10 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0  # Fetch all, necessary to find tags and branches
+          fetch-tags: true
 
       - uses: actions/setup-python@v5
         with:
@@ -46,7 +49,10 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0  # Fetch all, necessary to find tags and branches
+          fetch-tags: true
 
       - uses: actions/setup-python@v5
         with:

CHANGELOG.md

@@ -9,6 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- #343: Circuit exporter to OpenQASM3:
+  `graphix.qasm3_exporter.circuit_to_qasm3`.
+
 - #337: New module `graphix.find_pauliflow` with the $O(N^3)$
   Pauli-flow finding algorithm introduced in Mitosek and Backens, 2024
   (arXiv:2410.23439).

graphix/qasm3_exporter.py

@@ -0,0 +1,95 @@
+"""Exporter to OpenQASM3."""
+
+from __future__ import annotations
+
+from fractions import Fraction
+from math import pi
+from typing import TYPE_CHECKING
+
+# assert_never added in Python 3.11
+from typing_extensions import assert_never
+
+from graphix.instruction import Instruction, InstructionKind
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from graphix import Circuit
+
+
+def circuit_to_qasm3(circuit: Circuit) -> str:
+    """Export circuit instructions to OpenQASM 3.0 representation.
+
+    Returns
+    -------
+    str
+        The OpenQASM 3.0 string representation of the circuit.
+    """
+    return "\n".join(circuit_to_qasm3_lines(circuit))
+
+
+def circuit_to_qasm3_lines(circuit: Circuit) -> Iterator[str]:
+    """Export circuit instructions to line-by-line OpenQASM 3.0 representation.
+
+    Returns
+    -------
+    Iterator[str]
+        The OpenQASM 3.0 lines that represent the circuit.
+    """
+    yield "OPENQASM 3;"
+    yield 'include "stdgates.inc";'
+    yield f"qubit[{circuit.width}] q;"
+    if any(instr.kind == InstructionKind.M for instr in circuit.instruction):
+        yield f"bit[{circuit.width}] b;"
+    for instr in circuit.instruction:
+        yield f"{instruction_to_qasm3(instr)};"
+
+
+def instruction_to_qasm3(instruction: Instruction) -> str:
+    """Get the qasm3 representation of a single circuit instruction."""
+    if instruction.kind == InstructionKind.M:
+        return f"b[{instruction.target}] = measure q[{instruction.target}]"
+    # Use of `==` here for mypy
+    if (
+        instruction.kind == InstructionKind.RX  # noqa: PLR1714
+        or instruction.kind == InstructionKind.RY
+        or instruction.kind == InstructionKind.RZ
+    ):
+        if not isinstance(instruction.angle, float):
+            raise ValueError("QASM export of symbolic pattern is not supported")
+        rad_over_pi = instruction.angle / pi
+        tol = 1e-9
+        frac = Fraction(rad_over_pi).limit_denominator(1000)
+        if abs(rad_over_pi - float(frac)) > tol:
+            angle = f"{rad_over_pi}*pi"
+        num, den = frac.numerator, frac.denominator
+        sign = "-" if num < 0 else ""
+        num = abs(num)
+        if den == 1:
+            angle = f"{sign}pi" if num == 1 else f"{sign}{num}*pi"
+        else:
+            angle = f"{sign}pi/{den}" if num == 1 else f"{sign}{num}*pi/{den}"
+        return f"{instruction.kind.name.lower()}({angle}) q[{instruction.target}]"
+
+    # Use of `==` here for mypy
+    if (
+        instruction.kind == InstructionKind.H  # noqa: PLR1714
+        or instruction.kind == InstructionKind.I
+        or instruction.kind == InstructionKind.S
+        or instruction.kind == InstructionKind.X
+        or instruction.kind == InstructionKind.Y
+        or instruction.kind == InstructionKind.Z
+    ):
+        return f"{instruction.kind.name.lower()} q[{instruction.target}]"
+    if instruction.kind == InstructionKind.CNOT:
+        return f"cx q[{instruction.control}], q[{instruction.target}]"
+    if instruction.kind == InstructionKind.SWAP:
+        return f"swap q[{instruction.targets[0]}], q[{instruction.targets[1]}]"
+    if instruction.kind == InstructionKind.RZZ:
+        return f"rzz q[{instruction.control}], q[{instruction.target}]"
+    if instruction.kind == InstructionKind.CCX:
+        return f"ccx q[{instruction.controls[0]}], q[{instruction.controls[1]}], q[{instruction.target}]"
+    # Use of `==` here for mypy
+    if instruction.kind == InstructionKind._XC or instruction.kind == InstructionKind._ZC:  # noqa: PLR1714
+        raise ValueError("Internal instruction should not appear")
+    assert_never(instruction.kind)

noxfile.py

@@ -16,7 +16,7 @@ def install_pytest(session: Session) -> None:
 @nox.session(python=["3.9", "3.10", "3.11", "3.12", "3.13"])
 def tests_minimal(session: Session) -> None:
     """Run the test suite with minimal dependencies."""
-    session.install("-e", ".")
+    session.install(".")
     install_pytest(session)
     # We cannot run `pytest --doctest-modules` here, since some tests
     # involve optional dependencies, like pyzx.
@@ -27,7 +27,7 @@ def tests_minimal(session: Session) -> None:
 @nox.session(python=["3.10", "3.11", "3.12", "3.13"])
 def tests_dev(session: Session) -> None:
     """Run the test suite with dev dependencies."""
-    session.install("-e", ".[dev]")
+    session.install(".[dev]")
     # We cannot run `pytest --doctest-modules` here, since some tests
     # involve optional dependencies, like pyzx.
     session.run("pytest")
@@ -36,7 +36,7 @@ def tests_dev(session: Session) -> None:
 @nox.session(python=["3.9", "3.10", "3.11", "3.12", "3.13"])
 def tests_extra(session: Session) -> None:
     """Run the test suite with extra dependencies."""
-    session.install("-e", ".[extra]")
+    session.install(".[extra]")
     install_pytest(session)
     session.install("nox")  # needed for `--doctest-modules`
     session.run("pytest", "--doctest-modules")
@@ -45,14 +45,14 @@ def tests_extra(session: Session) -> None:
 @nox.session(python=["3.10", "3.11", "3.12", "3.13"])
 def tests_all(session: Session) -> None:
     """Run the test suite with all dependencies."""
-    session.install("-e", ".[dev,extra]")
+    session.install(".[dev,extra]")
     session.run("pytest", "--doctest-modules")
 
 
 @nox.session(python=["3.9", "3.10", "3.11", "3.12", "3.13"])
 def tests_symbolic(session: Session) -> None:
     """Run the test suite of graphix-symbolic."""
-    session.install("-e", ".")
+    session.install(".")
     install_pytest(session)
     session.install("nox")  # needed for `--doctest-modules`
     # Use `session.cd` as a context manager to ensure that the
@@ -67,3 +67,21 @@ def tests_symbolic(session: Session) -> None:
         # session.run("git", "clone", "https://github.com/TeamGraphix/graphix-symbolic")
         with session.cd("graphix-symbolic"):
             session.run("pytest", "--doctest-modules")
+
+
+@nox.session(python=["3.9", "3.10", "3.11", "3.12", "3.13"])
+def tests_qasm_parser(session: Session) -> None:
+    """Run the test suite of graphix-qasm-parser."""
+    session.install(".")
+    install_pytest(session)
+    session.install("nox")  # needed for `--doctest-modules`
+    # Use `session.cd` as a context manager to ensure that the
+    # working directory is restored afterward. This is important
+    # because Windows cannot delete a temporary directory while it
+    # is the working directory.
+    with TemporaryDirectory() as tmpdir, session.cd(tmpdir):
+        # See https://github.com/TeamGraphix/graphix-qasm-parser/pull/1
+        session.run("git", "clone", "-b", "fix_typing_issues", "https://github.com/TeamGraphix/graphix-qasm-parser")
+        with session.cd("graphix-qasm-parser"):
+            session.install(".")
+            session.run("pytest", "--doctest-modules")

requirements-dev.txt

@@ -21,3 +21,5 @@ pytest-mock
 # Optional dependencies
 qiskit>=1.0
 qiskit-aer
+
+graphix-qasm-parser @ git+https://github.com/TeamGraphix/graphix-qasm-parser.git@fix_typing_issues

tests/test_qasm3_exporter.py

@@ -0,0 +1,36 @@
+"""Test exporter to OpenQASM3."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+from numpy.random import PCG64, Generator
+
+from graphix.qasm3_exporter import circuit_to_qasm3
+from graphix.random_objects import rand_circuit
+
+try:
+    from graphix_qasm_parser import OpenQASMParser
+except ImportError:
+    pytestmark = pytest.mark.skip(reason="graphix-qasm-parser not installed")
+
+    if TYPE_CHECKING:
+        import sys
+
+        # We skip type-checking the case where there is no
+        # graphix-qasm-parser, since pyright cannot figure out that
+        # tests are skipped in this case.
+        sys.exit(1)
+
+
+@pytest.mark.parametrize("jumps", range(1, 11))
+def test_circuit_to_qasm3(fx_bg: PCG64, jumps: int) -> None:
+    rng = Generator(fx_bg.jumped(jumps))
+    nqubits = 5
+    depth = 4
+    circuit = rand_circuit(nqubits, depth, rng)
+    qasm = circuit_to_qasm3(circuit)
+    parser = OpenQASMParser()
+    parsed_circuit = parser.parse_str(qasm)
+    assert parsed_circuit.instruction == circuit.instruction