Metadata-Version: 2.2
Name: qoala-mlir
Version: 0.1.0
Keywords: compiler,quantum,bindings
Author-Email: Sacha Bernheim <s.b.bernheim@tudelft.nl>, Bart van der Vecht <b.vandervecht@tudelft.nl>, Diego Rivera <d.a.g.a.rivera@tudelft.nl>
Maintainer-Email: Sacha Bernheim <s.b.bernheim@tudelft.nl>, Bart van der Vecht <b.vanderVecht@tudelft.nl>, Diego Rivera <d.a.g.a.rivera@tudelft.nl>
License: MIT License
         
         Copyright (c) 2025 QuTech
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
         
Requires-Python: <3.13,>=3.10
Requires-Dist: numpy<=1.26,>=1.19.5
Requires-Dist: pybind11<=2.10.3,>=2.9.0
Requires-Dist: PyYAML<=6.0.1,>=5.3.1
Requires-Dist: dataclasses<=0.8,>=0.6
Description-Content-Type: text/markdown

# 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](https://softwarequtech.github.io/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/`](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: [`<PAPER_URL>`](<PAPER_URL>).

## 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`](requirements-docs.txt)) into the container before serving:

```sh
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. A BibTeX entry will be available alongside the paper at the URL above; the placeholder below will be replaced once the paper is published:

```bibtex
<BIBTEX_PLACEHOLDER>
```

## License

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