qoala-mlir

qoala-mlir is the MLIR-based middle and back end of the Qoala compiler stack. It consumes a Qoala HIR module — emitted by the euqalyptus Python frontend — lowers it through three intermediate representations (qnet → qmem → qoalahost + netqasm + qremote), and emits a textual .iqoala executable that can be run on the Qoala runtime. The build produces two command-line tools, qoala-opt (analyses, optimizations, and lowerings) and qoala-translate (LIR-to-.iqoala translation), together with a qnet Python bindings package that the frontend imports to construct HIR programmatically.

Documentation

The full documentation is published at https://softwarequtech.github.io/qoala-mlir/. It covers installation, the three intermediate representations, the pass pipeline, the per-op and per-pass reference, the Python bindings, and contributor-facing material.

Design and paper

For a deeper account of the compiler's design — the design considerations, the optimization passes (peephole rules, quantum dead-code elimination, MILP-based block reordering), the deadline-estimation MILP, and the static analyses — please refer to the accompanying paper, A Multi-Level Compiler Pipeline for Qoala Quantum Internet Programs (IEEE QSW 2026).

Running the documentation locally

You can serve the documentation site locally with the official squidfunk/mkdocs-material Docker image, without installing MkDocs into your environment. Because the site uses the mkdocstrings[python] plugin to render API documentation from the qnet Python bindings' docstrings, the command below installs the docs-build dependencies (listed in requirements-docs.txt) into the container before serving:

docker run --rm -it -p 8000:8000 -v "$(pwd)":/docs \
  --entrypoint sh squidfunk/mkdocs-material:latest \
  -c 'pip install --quiet -r requirements-docs.txt && mkdocs serve --dev-addr=0.0.0.0:8000'

Run the command from the repository root. The site is then available at http://localhost:8000, with live reload on every change to docs/, mkdocs.yml, or the docstrings under lib/Python/mlir_qnet/.

Citation

If you use qoala-mlir in academic work, please cite the accompanying paper:

@inproceedings{bernheim2026qoalacompiler,
  author    = {Bernheim, Sacha and van der Vecht, Bart and Ferrari, Davide and
               Rivera, Diego and Wehner, Stephanie},
  title     = {A Multi-Level Compiler Pipeline for Qoala Quantum Internet Programs},
  booktitle = {2026 IEEE International Conference on Quantum Software (QSW)},
  year      = {2026},
  month     = jul,
  address   = {Sydney, Australia},
  publisher = {IEEE},
  pages     = {12--24},
  doi       = {10.1109/QSW72780.2026.00012},
  url       = {https://ieeexplore.ieee.org/document/11662182},
}

License

qoala-mlir is released under the MIT License (Copyright © 2025 QuTech). See the LICENSE file for the full text.