Home of a set of fast tools for compiling lattice surgery instructions. Part of the Lattice Surgery Compiler family. The liblsqecc
library contains the functionality used by the lsqecc_slicer
executable. We are working on exposing its functionality as a Python API in the Lattice Surgery Compiler package.
git clone --recursive https://github.com/latticesurgery-com/liblsqecc.git
cd liblsqecc
mkdir build
cd build
cmake ..
Note: The lsqecc_slicer
executable will be at the top level of the build
directory.
Optional: Install the Boost development headers for your platform. These are used for faster path finding in some cases.
lsqecc_slicer
Found at the top level of the build directory. Produces latticesurgery.com style slices from LS Instructions, using a layout spec.
# Basic example of using LLI instructions generated from LSC
lsqecc_slicer -i instructions.txt -l 10_by_10_layout.txt -o output.json
# Litinski's compact layout
lsqecc_slicer -q -i examples/qasm/compact_layout_demo.qasm -o out.json --compactlayout --graceful
Where:
instructions.txt
contains LS Instructions10_by_10_layout.txt
is a layout spec file.output.json
is a file containing the 3D assembly of slices. Those can just be uploaded latticesurgery.com for viewingUsage: lsqecc_slicer [options...]
Options:
-i, --input File with input. If not provided will read LS Instructions from stdin
-q, --qasm File name of file with QASM. When not provided will read as LLI (not QASM)
-l, --layout File name of file with layout spec, otherwise the layout is auto-generated (configure with -L)
-o, --output File name of output. When not provided outputs to stdout
-f, --output-format Requires -o, STDOUT output format: progress, noprogress, machine, stats
-t, --timeout Set a timeout in seconds after which stop producing slices
-r, --router Set a router: graph_search (default), graph_search_cached
-P, --pipeline pipeline mode: stream (default), dag, wave
-g, --graph-search Set a graph search provider: djikstra (default), astar, boost (not always available) [ignored by -P wave pipeline, which uses astar]
--graceful If there is an error when slicing, print the error and terminate
--printlli Output LLI instead of JSONs. options: before (default), sliced (prints lli on the same slice separated by semicolons)
--printdag Prints a dependancy dag of the circuit. Modes: input (default), processedlli
--noslices Do the slicing but don't write the slices out
--cnotcorrections Add Xs and Zs to correct the the negative outcomes: never (default), always
--layoutgenerator, -L Automatically generates a layout for the given number of qubits. Incompatible with -l. Options:
- compact (default): Uses Litinski's Game of Surace Code compact layout (https://arxiv.org/abs/1808.02892)
- compact_no_clogging: same as compact, but fewer cells for ancillas and magic state queues
- edpc: Uses a layout specified in the EDPC paper by Beverland et. al. (https://arxiv.org/abs/2110.11493)
--nostagger Turns off staggered distillation block timing
--disttime Set the distillation time (default 10)
--local Compile gates using a local lattice surgery instruction set
-h, --help Shows this page
LibLSQECC can parse a small subset of OpenQASM 2.0 instead of LLI. We call this type of assembly OpenQASMmin.
In general, OpenQASMmin should be valid OpenQASM, with the restrictions below:
OPENQASM 2.0;
in the first lineg q[n];
where g
is one of h
,x
,z
,s
,t
, sdg
, tdg
, reset
and n
is a non-negative integerrz(expr)
and crz(expr)
where expr
has form pi/m
or n*pi/m
for n, m integers. No whitespace.cx q[n],q[m];
where n
and m
are non-negative. Target comes first, as per OpenQASM convention (Fig 2)cx q[0],q[7]; // %ZXWithMBMTargetFirst,AncillaNextToTarget
Our OpenQASM dialect, OpenQASMMin, does not support arbitrary single qubit rotations. These need to be decomposed into supported gates. Gridsynth (aka Newsynth) is a Haskell program that can approximate arbitrary rotations with Clifford+T gates.
We can take advantage of Gridsynth's functionality to decompose arbitrary rz
's in our input circuits. To do so we've created a fork of Gridsynth with a C API wrapper do that we can call Gridsynth from our C++ code.
However due to the Haskell platform's own portability challenges and some low level interfacing with C and C++ being required, at this point enabling Gridsynth is still manual:
external/rotation/decomposer/newsynth
newsynth.cabal
installghc
target in theMakefile
in the newsynth
folder contains the ghcup commands used to buildmake buildhs
in the newsynth
folder folder to build Gridsynth with the C API
make runtests
to verify a succesful build of Gridsynth and the C API
USE_GRIDSYNTH
variable defined (E.g. cmake .. -DUSE_GRIDSYNTH:STRING=YES
)newsynth
directory is readable and shows what's required to run lsqecc
with Gridsynth
lsqecc_slicer
as usualrz
and crz
gates will be approximated using Gridsynth where applicable--rzprecision
to set Gridsynth's precision epsilon=10^(-rzprecision)
(equivalent to Gridsynth's default precision mode -d
)Note: Other ways are probably possible with Cabal or Stack
To generate results according to the compilation scheme written about in our recent paper, use the following options:
lsqecc_slicer -q -i {qasm_filename} -L edpc --disttime 1 --nostagger --local -P wave --printlli sliced -o {lli_filename} -f stats > {stats_filename}
Results in that paper were generated using PR #106, and should be reproducible using the current release.
Liblsqecc was primarily developed at Aalto University by George Watkins under Alexandru Paler's supervision, and is now maintained by George Watkins.
A special thanks to Tyler LeBlond (Oak Ridge National Laboratory) and Christopher Dean (Dalhousie University) for adding the EDPC layout family, the local compilation layer, the wave pipeline, and other contributions according to the compilation strategy outlined in their recent paper.
Alex Nguyen maintains the NPM package and associated infrastructure.
Please cite as follows:
@article{watkins2023high,
title={A High Performance Compiler for Very Large Scale Surface Code Computations},
author={Watkins, George and Nguyen, Hoang Minh and Seshadri, Varun and Watkins, Keelan and Pearce, Steven and Lau, Hoi-Kwan and Paler, Alexandru},
journal={arXiv preprint arXiv:2302.02459},
year={2023}
}