A running quantum algorithm spends most of its physical qubits not on data, but on the magic-state factories that distill the non-Clifford (T) resources it consumes. Provision too few and the computation stalls waiting for magic states; provision too many and idle factory tiles bloat the footprint. This repo compiles a Clifford+T circuit into a surface-code lattice-surgery layout, schedules the factories against the circuit's T-demand, and optimizes the factory ratio to minimize spacetime volume.
This is repo 10 of a ten-part QEC research portfolio.
Where fault-tolerance-economics reproduces
an algorithm-level resource estimate, this repo works one level down, at the layout-and-scheduling
trade-off that turns a logical circuit into a physical-qubit budget.
Spacetime volume (physical qubits × runtime cycles) versus factory count for a T-heavy benchmark. Volume falls steeply while the computation is factory-limited, bottoms out at the optimum (here 361 factories), then rises as additional idle factories only add area.
The runtime is the maximum of the factory-limited time (orange, ∝ 1/factories) and the logic-limited floor (green). The volume-optimal factory count sits exactly at the crossover, where buying more factories stops shortening the runtime.
- Compiler pass: a Clifford+T circuit is scheduled as-soon-as-possible to extract the quantities that drive cost — T-count, T-depth, peak parallel T-demand, and logical depth.
- An explicit architecture model: logical data, routing, and factories are costed in surface-code tiles (
2 d^2physical qubits each); factories produce one T-state every~5.5 dcycles. - Factory-ratio optimization: the factory ratio that minimizes spacetime volume is an interior minimum, found by scanning and located at the factory/logic crossover.
| Quantity | Model |
|---|---|
| Physical qubits per logical tile | 2 d^2 |
| Data + routing footprint | routing_tiles_per_qubit × logical qubits |
| Factory footprint | factory_tiles per factory |
| Factory throughput | one T-state per ~5.5 d cycles |
| Logic runtime | logical_depth × d cycles |
| Factory runtime | t_count × period / num_factories cycles |
| Runtime | max(logic, factory) cycles |
| Spacetime volume | physical qubits × runtime cycles |
Every parameter is overridable in HardwareSpec.
pip install -e ".[dev]"pytest
python examples/compile_adder.py # writes docs/{volume_vs_factories,runtime_breakdown}.pngavcompile compile --tbench 200 --t-layers 5000 --distance 15
avcompile compile --adder 64
avcompile scan --adder 64 --output outputs/scan.jsonfrom avcompiler import HardwareSpec, analyze_circuit, optimize_factories, ripple_carry_adder
circuit = analyze_circuit(ripple_carry_adder(64))
result = optimize_factories(circuit, HardwareSpec(code_distance=15))
best = result.best
print(best.num_factories, best.physical_qubits, best.wall_clock_seconds)This is an architecture-level estimator, not a placement-and-routing compiler. It models the factory/data trade-off with a first-order cost model; it does not lay out individual patches, schedule lattice-surgery operations cycle by cycle, or implement Litinski's full active-volume accounting. The defaults are order-of-magnitude values from the literature and are meant to make the shape of the trade-off — and the existence of a volume-optimal factory ratio — reproducible, not to certify a specific device's qubit count.
src/avcompiler/circuits.py— Clifford+T circuit, ASAP scheduler, example generatorssrc/avcompiler/resources.py— footprint and runtime modelsrc/avcompiler/optimize.py— factory-count scan and volume minimizersrc/avcompiler/types.py—CircuitSpec,HardwareSpec, estimate recordssrc/avcompiler/viz/plots.py,cli.pyexamples/compile_adder.py
- Fowler AG, Mariantoni M, Martinis JM, Cleland AN. Surface codes: towards practical large-scale quantum computation. Physical Review A 2012; 86:032324.
- Litinski D. A game of surface codes: large-scale quantum computation with lattice surgery. Quantum 2019; 3:128.
- Litinski D. Magic state distillation: not as costly as you think. Quantum 2019; 3:205.
- Litinski D, Nickerson N. Active volume: an architecture for efficient fault-tolerant quantum computers. arXiv 2022; 2211.15465.
MIT — see LICENSE.