Liblsqecc

Publication link for original compiler release Publication link for upgraded compiler and its usage in resource estimation

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.

Build

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.

Using 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 Instructions
• 10_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 viewing

Parameters

Usage: 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), wave, edpc, dag (deprecated)
    -g, --graph-search     Set a graph search provider: djikstra (default), astar, boost (not always available)
    --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 dependency 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 family of layouts based upon the one specified in the EDPC paper by Beverland et. al. (https://arxiv.org/abs/2110.11493)
    --numlanes             Only compatible with -L edpc. Configures number of free lanes for routing.
    --condensed            Only compatible with -L edpc. Packs logical qubits more compactly.
    --explicitfactories    Only compatible with -L edpc. Explicitly specifies factories but clogs easily (otherwise, uses tiles reserved for magic state re-spawn).
    --nostagger            Turns off staggered distillation block timing
    --disttime             Set the distillation time (default 10)
    --local                Compile gates into a pair-wise local lattice surgery instruction set
    --notwists             Compile S gates using the catalytic teleportation circuit from Fowler, 2012 instead of using the twist-based Y state initialization and teleportation from Gidney, 2024
    -h, --help             Shows this page  

OpenQASMmin: a OpenQASM dialect (Experimental)

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:

• Program must begin with OPENQASM 2.0; in the first line
• Only one register is allowed (whether the names match will not be checked)
• Max one gate per line
• Single qubit gates must be in the form g q[n]; where g is one of h,x,z,s,t, sdg, tdg, reset and n is a non-negative integer
• rz(expr) and crz(expr) where expr has form pi/m or n*pi/m for n, m integers. No whitespace.
• CNOTs must be in the form cx q[n],q[m]; where n and m are non-negative. Target comes first, as per OpenQASM convention (Fig 2)
• No classical control is supported
• No measurement operators are supported
• Only inline comments, for example: cx q[0],q[7]; // %ZXWithMBMTargetFirst,AncillaNextToTarget

Building with Gridsynth support for approximating rz angles

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:

1. Go to external/rotation/decomposer/newsynth
2. Get a Haskell environment compatible with the dependencies in newsynth.cabal
   • Use a user-level install of ghc-9.4.4 with ghcup
   • The installghc target in theMakefile in the newsynth folder contains the ghcup commands used to build
3. Use make buildhs in the newsynth folder folder to build Gridsynth with the C API
   • Likeley to require some manual intevention like adjusting some versions and paths
   • Can use the make runtests to verify a succesful build of Gridsynth and the C API
4. Configure the CMake project with the USE_GRIDSYNTH variable defined (E.g. cmake .. -DUSE_GRIDSYNTH:STRING=YES)
   • If something goes wrong, the Makefile in the newsynth directory is readable and shows what's required to run lsqecc with Gridsynth
5. Run lsqecc_slicer as usual
   • rz and crz gates will be approximated using Gridsynth where applicable
   • can use the --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

Realistic Resource Estimates using Direct Clifford+T Compilation

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 --notwists --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.

Contributors

Liblsqecc was originally developed at Aalto University by George Watkins under Alexandru Paler's supervision and was later upgraded by Tyler LeBlond (Oak Ridge National Laboratory) and Christopher Dean (Dalhousie University) in collaboration with George Watkins. The compiler is currently maintained primarily by Tyler LeBlond and ongoing development is co-led with Alexandru Paler.

Alex Nguyen maintains the NPM package and associated infrastructure.

Citing

The original release of the compiler should be cited as follows:

@article{watkins2024high,
  title={A high performance compiler for very large scale surface code computations},
  author={Watkins, George and Nguyen, Hoang Minh and Watkins, Keelan and Pearce, Steven and Lau, Hoi-Kwan and Paler, Alexandru},
  journal={Quantum},
  volume={8},
  pages={1354},
  year={2024},
  publisher={Verein zur F{\"o}rderung des Open Access Publizierens in den Quantenwissenschaften}
}

The upgraded compiler and its usage in resource estimation should be cited as follows:

@article{leblond2023realistic,
  title={Realistic Cost to Execute Practical Quantum Circuits using Direct Clifford+ T Lattice Surgery Compilation},
  author={LeBlond, Tyler and Dean, Christopher and Watkins, George and Bennink, Ryan},
  journal={ACM Transactions on Quantum Computing},
  year={2023},
  publisher={ACM New York, NY}
}