Topologiq: Algorithmic Lattice Surgery

Topologiq is tool to convert quantum circuits into logical versions of themselves based on the surface code.

✨ Overview

The general algorithmic rationale is as follows:

• Topologiq traverses the input circuit one edge at a time.
  • Several graph traversing subroutines available, including several BFS flavours.
  • Additional graph traversing subroutines are welcome: open an issue here to contribute additional graph traversing subroutines.
• On each iteration, Topologiq greedily converts the edge into the shortest topologically-correct 3D path it can find.
  • Realised paths often correspond to the actual shortest path possible given constraints.
  • The value function can be used to influence path choices, an aspect of Topologiq that welcomes improvements: open an issue here to give the value function a go.

An animated visualisation is given below.

Figure 1. Algorithmic lattice surgery of three CNOTs using Topologiq.

🔗 Gate support

Topologiq supports the following gate set and combinations thereof:

NB! The block patterns in the images below are SOFT patterns. Topologiq yields the patterns in the images if there are no other gates in the circuit. However, the patterns are flexible and will bend and stretch during the lattice surgery. That is, literally, what Topologiq does. It bends patterns around in ways that do not break the topology of the computation.

CLIFFORD		NON-CLIFFORD
X, Z, I:		Cultivation:
CNOT, CZ:		Conditional:
Hadamard:		T:
Y:
S:

🏛️ Architecture

Topologiq is designed to be (or at the very least, become) highly modular. The final goal is to allow others to easily use tailored components and/or develop end-to-end "flavours" re-interpreting several components.

An overview of Topologiq's general architecture is available here.

Currently, an area where contributors could make a massive difference in the short term is CI/CD workflows for testing and benchmarking. Leaving these "for later" helped in that it enabled rapid experimentation and iteration. However, the codebase is becoming a bit too large to keep it like that. Open an issue to contribute a CI/CD.

🛠 Install

Currently, the best way to test Topologiq is to clone the repository, recreate the environment, and install dependencies.

Using UV

# 1. Clone repository. 
git clone https://github.com/jbolns/topologiq.git

# 2. Sync environment.
uv sync  # Topologiq
# or
uv sync --group integration  # Topologiq w. TQEC/tqec

# Additional steps needed only for contributors
# 3. Opt for an editable installation
uv sync --group all
uv pip install -e .

Using PIP

# 1. Clone repository. 
git clone https://github.com/jbolns/topologiq.git

# 2. Recreate environment.
# 2.1. Environment creation
python -m venv .venv

# 2.2. Environment activation
.venv\Scripts\activate.bat  # Windows
source .venv/bin/activate  # Linux

# 2.3. Install dependencies
pip install -r requirements.txt

# Additional steps needed only for contributors
# 3. Opt for an editable installation
pip install -e .

🚀 Documentation

There is a growing number of examples showing how to use Topologiq in a variety of circumstances.

Beginner

Examples of how to use Topologiq with circuits designed in a number of frameworks compatible with Topologiq:

• Using PyZX circuits in Topologiq (CNOTs, small).¹
• How to use Topologiq with QASM files (CNOTs, multiple).
• How to use with a Qiskit circuit (GHZ).
• Using Qrisp circuits with Topologiq (H-Z-S-T).¹
• $\textcolor{red}{\textsf{[Pending]}}$ Other qBraid supported formats: Open an issue to contribute an example.
• $\textcolor{red}{\textsf{[Pending]}}$ Other circuit design framework able to output QASM: Open an issue to contribute an example.

Intermediate

Examples using Topologiq programmatically and with human-readable output files in BGRAPH format.

• Verifiable lattice surgery with PyZX and Topologiq (Steane).¹
• Using Topologiq with random PyZX graphs and producing a BGRAPH file as primary output (Clifford & non-Clifford).

Advanced

Examples of how to use Topologiq with TQEC/tqec.

• $\textcolor{red}{\textsf{[Pending]}}$ Using Topologiq and TQEC as part of a shared environment: Open an issue to contribute an example.
• $\textcolor{red}{\textsf{[Pending]}}$ Using Topologiq from within a TQEC environment: Open an issue to contribute an example.

🕹️ Desktop UX

Topologiq has an interactive User Interface (UX) powered jointly by qBraid, PyZX, ZXLive and, of course, Topologiq.

The UX is highly recommended for:

• Learning: The UX makes it easy to visually explore Topologiq's capabilities and understand how specific parameter choices impact outputs.
• Research: The UX makes it easy to programmatically and visually create and manage a collection of slightly-different versions of a given circuit and compare the respective outputs.

You can launch the UX from the root of the repository (no additional installation steps needed).

uv run src/topologiq/app.py

You can also find a video showing usage of the UX by clicking here.

👷🏽‍♂️ Contributing

Pull requests and issues are more than welcomed!

See CONTRIBUTING for specific instructions to start contributing.

📜 License

Topologiq is licensed under an Apache 2.0 license.

The ETHICAL_NOTICE.md contains additional ethical use pointers.

🏟️ Community

Every Wednesday at 8:30am PST, we hold meetings to discuss project progress and conduct educational talks related to TQEC.

Here are some helpful links to learn more about the TQEC community and Topologiq:

• Overview of state of the art 2D QEC: Slides/Video
• Introduction to surface code quantum computation: Slides
• Programming a quantum computer using SketchUp: Slides/Video
• Overview of Topologiq: Video
• Qiskit->QASM->Topologiq interoperability: Video.

All the resources and group meeting recordings are available at this link.

Please join the Google group to receive more updates and information!

Footnotes

1. Documents currently demonstrate basic usage but could be improved and expanded. Open an issue to improve or expand. ↩ ↩² ↩³