📝 MLIR - Getting Started Guide

[DRovara]

Note

This issue is part of unitaryDESIGN 2026; note that you have to be registered to complete this issue. Learn more about the PR review process here. 

A message from unitaryDESIGN about AI Slop: "While we are open to collaboration with LLMs for unitaryDESIGN, please note that fully AI-generated PRs are not acceptable. It is up to the discretion of the individual maintainers whether or not LLM-generated PRs are the right fit for their issues, and they have the right to reject those that appear fully AI-generated."

Learn more about unitaryDESIGN rules and opportunities here!

Problem Statement

This repository could really profit from a "Getting Started with MLIR" guide that reaches from installing the correct version of LLVM/MLIR to writing and understanding QC/QCO IR and having it optimized with our optimization passes.

Proposed Solution

The goal is to create a markdown tutorial (e.g., docs/getting_started.md) that covers all required steps of working with our MLIR dialects QC and QCO. This tutorial should not be in typical "documentation-speak". Instead, it can be written in an engaging manner so that users are actually motivated to read it through.

The following lists the main concepts that should be covered in such a guide. This does not mean that the section structure has to exactly follow these suggestions. Any reasonable and intuitive structure of the document that somehow covers these topics should be good.

1. The Setup
   Link the user to our Installation page, where they can find instructions for building MQT Core. In 📝 Improve developer documentation #1456, installation instructions for MLIR will be added to the page, so there is no need to go into more detail here.

2. "Hello Quantum"
   Walk the user through creating their first quantum program. The example should begin from just allocating a single qubit and executing some gate, and end with a simple quantum circuit, e.g., to prepare a Bell state. For a starting point, refer to the code in test_compiler_pipeline.cpp.

3. QC vs. QCO
   This section should, in detail, explain the fundamental differences between QC (reference semantics, input/output dialect) and QCO (value semantics, linear types, used for optimizations, similar to DAG representations).
   It should explain these concepts with the help of a running example that shows off the main differences between the dialects.

4. Advanced Constructs
   Move beyond simple gates. Showcase how to define multiple functions, demonstrate Control Flow structures (e.g., scf.for or scf.if interacting with quantum blocks). For the control flow structures, also highlight the required considerations to uphold SSA and linear types in QCO, i.e., make sure that scf.yield is used and entry-arguments are employed to make sure variables are not re-used.

---

All code snippets used in the guide should be verified to compile/run. The guide should not expect any prior knowledge on MLIR. It can use diagrams or ASCII art where helpful to explain the flow from QC $\to$ QCO.

#1225 may form a basis for some of the content.