wisq

wisq is a powerful and flexible compiler for quantum circuits. It is especially well-suited for targeting fault-tolerant devices using the surface code. The full_ft mode optimizes the input circuit, then maps the circuit qubits to the architecture and routes two-qubit gates (including distillation-based T gates). wisq also provides a dedicated circuit optimization mode opt that can optimize circuits over arbitrary gate sets by invoking GUOQ [1] with different arguments.

Dependencies

wisq requires Python 3.8, Java 21 or later, and gcc.

Installation

Once the above requirements are satisfied, the wisq command line tool can be painlessly installed via pip:

pip install wisq

To test the installation, try the example command:

wisq wisq-circuits/3_17_13.qasm -ap 1e-10 -ot 10

If everything is working properly, the tool should run for about 10 seconds before outputting a compiled result into the file out.json. (See below for how to interpret this output)

Developer Installation

To extend or modify wisq, you can clone the Github repo and build from the package from source. For example, using uv for package management, this might look like:

git clone https://github.com/qqq-wisc/wisq.git
cd wisq
uv venv
source .venv/bin/activate
uv pip install build
python -m build --sdist
uv pip install -e .
cd src/wisq

To extend or modify the circuit optimization (GUOQ [1]/QUESO [3]) component of wisq, you will need to clone the GUOQ repository, make your changes, build, and copy the new JAR to lib. The Python component of GUOQ can be directly modified here in src/wisq/resynth.py. For example, the circuit optimization phase of wisq can be extended to handle new gate sets in this manner.

Usage

Compiler modes

wisq takes circuits in the OpenQASM 2 format as input. The compiler passes that are applied, and consequently the final output, depends on the compiler mode. This is configured with the --mode flag. The three modes are

• opt: Optimize the input circuit and write the result to a QASM file
• scmr: Apply a mapping and routing pass only and output a schedule to a JSON file.
• full_ft (default): The composition of the above; optimize the input circuit, then apply mapping and routing to the result.

The table below summarizes the compiler modes.

Flag	Description	Input	Output
--mode opt	optimization only	QASM	QASM
--mode scmr	mapping/routing only	QASM	JSON
--mode full_ft (or no mode specified)	optimization + mapping/routing	QASM	JSON

Mapping and Routing Output Format

In modes that apply mapping and routing, the resulting JSON object has two keys: "map", representing the qubit map and "steps", which is a list of time steps. Each step is a list of parallel gates and the paths along which they are routed.

Example commands

wisq includes an array of additional configuration options which can be viewed with the wisq --help command. Below we provide a few examples to highlight some of these options.

Example 1: Basic optimization configuration

Let's revisit the installation test command.

wisq wisq-circuits/3_17_13.qasm -ap 1e-10 -ot 10

Here, we run the default full_ft compiler mode with some configuration of the optimization. We set an approximation distance of 10^-10 with the -ap flag and a timeout for the optimization pass with the -ot flag.

Example 2: Basic mapping and routing configuration

We can target a compact architecture with less routing space using the -arch flag (see also Custom Architectures)

wisq wisq-circuits/3_17_13.qasm --mode scmr -arch compact_layout

Example 3: Advanced optimization configuration

The optimization pass can also be configured with different optimization objectives and gate sets.

wisq wisq-circuits/3_17_13.qasm --mode opt -obj TOTAL -tg IBM -aa advanced_args.json

Here we set the optimization objective to minimize total gate with the obj flag and set the target gate set to the native gates on IBM machines with the -tg flag.

Additionally, we use the -aa flag and the file advanced_args.json to pass more advanced arguments to the optimizer. The possible entries in one of these advanced arguments files can be viewed with the command wisq --guoq-help.

Custom Architectures

wisq allows users to specify a custom architecture for mapping and routing. The format for specifying an architecture is

{"height" : GRID_HEIGHT, "width" : GRID_WIDTH, "alg_qubits" : ALG_INDEX_LIST, "magic_states" : MS_INDEX_LIST}

where

• GRID_HEIGHT and GRID_WIDTH are integers;
• ALG_INDEX_LIST and MS_VERTEX_LIST are lists of integers indicating which grid positions are available for algorithmic qubits and which are reserved for magic states.

To pass in a custom architecture, use the flag -arch PATH where PATH is the path to a file in the above format.

Benchmarks

A few example circuits are included in the circuits directory. Additional benchmarks can be found at this repo.

References

wisq implements the techniques proposed in the following papers:

[1] Amanda Xu, Abtin Molavi, Swamit Tannu, Aws Albarghouthi. "Optimizing Quantum Circuits, Fast and Slow," International Conference on Architectural Support for Programming Languages and Operating Systems (ASPLOS),2025

[2] Abtin Molavi, Amanda Xu, Swamit Tannu, Aws Albarghouthi. "Dependency-Aware Compilation for Surface Code Quantum Architectures"

[3] Amanda Xu, Abtin Molavi, Lauren Pick, Swamit Tannu, Aws Albarghouthi. Synthesizing quantum-circuit optimizers. Proceedings of the ACM on Programming Languages. Volume 7, PLDI, 2023. https://doi.org/10.1145/3591254