An ultra fast Clifford+T → lattice-surgery compiler.
MiniFlash turns an OpenQASM 2.0 circuit into a tile program: which tiles hold qubits, magic states and routes, and which tiles merge at each step. It minimizes spacetime volume (height × width × steps, walks included), checks every program with an independent verifier, and renders it as a glTF scene. Read the full documentation.
pip install -e '.[test]'
python -m pytest -q tests
python main.py benchmarks/algorithms/ghz8.qasmEvery circuit prints one verified CSV row and leaves out/<circuit>.gltf. Open it in
any viewer, e.g. https://gltf-viewer.donmccurdy.com/. Time runs upward, two layers
per step. Qubits are red pillars; a CNOT's two halves sit on the lower (blue) and upper
(red) layer, T merges end at green magic states, and walks between partitions are orange.
A hierarchy .json from benchmarks/qualtran/ compiles bottom-up through its call tree:
python main.py benchmarks/toffoli/*.qasm > toffoli.csv
python main.py benchmarks/qualtran/add-4.jsonAs a library:
import miniflash as flash
problem = flash.read_qasm("benchmarks/toffoli/tof-3.qasm")
program = flash.make("layout").solve(problem)
report = flash.verify(problem, program)
flash.write_gltf(program, "tof3.gltf")Every knob lives in miniflash/constant.py, grouped by pass: the solver step and
layout policy, the magic-state factory (FACTORY_HEIGHT, FACTORY_WIDTH,
FACTORY_PERIOD, whether the supply is limited and how many factories are shared),
the initial placement and anneal weights, the router's lane penalty and exact
frontier, the spacing budget, the lassynth window budget and timeouts, and the
output directory. Compiler(...) and flash.make(name, **options) take the same
knobs as keyword arguments for one call.
benchmarks/ holds 206 circuits (GHZ, BV, DJ, QFT, random Clifford, graph states,
Galois-field multipliers, Toffoli, ...); see benchmarks/README.md.
If you use MiniFlash in your research, please cite:
@article{wang2026miniflash,
title = {Demand-Driven Routing Space for Lattice-Surgery Compilation},
author = {Wang, Hanyu and Lin, Wan-Hsuan and Chen, Zihan and Zhang, Eddy Z. and Cong, Jason},
journal = {arXiv preprint arXiv:2610.30747},
year = {2026},
url = {https://arxiv.org/abs/2610.30747}
}MIT