NB!!! There have been 3 recent major merges (folder restructuring, dependency clean-up, and Ruff) aimed at facilitating things for potential contributors. All seems to be running in order. However, if something does not work, go back a few merges and try again if you're looking to test Topologiq or open an Issue about and suggest a fix if you're looking to contribute.

Topologiq: Algorithmic Lattice Surgery

Topologiq is tool to convert ZX circuits into logical versions of themselves. It is based on the surface code and lattice surgery.

Interoperable with:

• PyZX: click here for an example.
• Qiskit: click here for an example.

Work in progress. Check "main" for latest stable checkpoint. Venture into open branches for the latest updates.

Summary

As visualised in the animated GIF below, Topologiq uses the connectivity information in a ZX-graph to produce a topologically-correct lattice surgery / space-time diagram. It picks a starting point randomly based on a centrality measure. It builds incrementally from that starting point, one edge at a time.

Topologiq's outputs can be used as inputs for TQEC/tqec and, theoretically, other similar tools.

Figure 1. Algorithmic lattice surgery of a CNOT.

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 .

Examples

You can quickly test Topologiq from the terminal using pre-defined circuit examples.

Check ./outputs/txt/ for results. All information in TXT outputs is also available for programmatic use.

# PyZX examples (Available examples: cnot, cnots, simple_mess)
uv run src/topologiq/run.py --pyzx:<circuit_name>
python3 src/topologiq/run.py --pyzx:<circuit_name>  # Requires active .venv

# Dict-based graph examples (Available examples: hadamard_line, hadamard_bend, steane, steane_obfs, or hadamard_mess)
uv run src/topologiq/run.py --graph:<circuit_name>
python3 src/topologiq/run.py --graph:<circuit_name>  # Requires active .venv

There are also optional parameters to enable 3D visuals, animations, and debug options.

# Enable "final" result or "detail" edge-by-edge progress visualisations
uv run src/topologiq/run.py --pyzx:<circuit_name> --vis:<final|detail>
python3 src/topologiq/run.py --pyzx:<circuit_name> --vis:<final|detail>  # Requires active .venv

# Produce a "GIF" or "MP4" animation of the process (MP4 requires FFmpeg).
uv run src/topologiq/run.py --pyzx:<circuit_name> --animate:<GIF|MP4>
python3 src/topologiq/run.py --pyzx:<circuit_name> --animate:<GIF|MP4>  # Requires active .venv

# Run a circuit a specific number of times irrespective of outcome for each inidividual run
uv run src/topologiq/run.py --pyzx:<circuit_name> --repeat:50
python3 src/topologiq/run.py --pyzx:<circuit_name> --repeat:50  # Requires active .venv

# Log run-time and performance statistics
uv run src/topologiq/run.py --pyzx:<circuit_name> --log_stats
python3 src/topologiq/run.py --pyzx:<circuit_name> --log_stats  # Requires active .venv

# Enable debug mode (incrementally detailed logs and visuals) (available modes: 1, 2, 3, 4) .
uv run src/topologiq/run.py --pyzx:<circuit_name> --vis:detail --debug:1
python3 src/topologiq/run.py --pyzx:<circuit_name> --vis:detail --debug:1  # Requires active .venv

There is also an accessible debug facility to quickly run any edge case encountered while running Topologiq with log_stats enabled.

# Pick up and replicate any available edge case (i.e. circuits Topologiq failed to build).
uv run src/topologiq/debug.py
python3 src/topologiq/debug.py  # Requires active .venv

# NB! Case must have been logged to stats, which only happens when Topologiq runs with `log_stats` enabled.
# NB! Currently available only for example graphs (the foundational graph must exist in file to replicate it).

Yeah, but how does it work, really?

Detailed insight into Topologiq and, hopefully, a paper, is in progress. Meanwhile, below, a quick overview of what goes on under the hood.

Input. Topologiq will look for an incoming ZX graph and, if needed and possible, convert it into a native format.

• Native format: A simple dictionary of nodes and edges (see ./src/topologiq/assets/graphs/simple_graphs.py for examples).
• PyZX interoperability: PyZX graphs supported (check docs/examples/pyzx_cnots.ipynb for an example).
  • NB. If using a random PyZX circuit, ensure all qubit lines are interconnected. Else, the graph has independent subgraphs, which Topologiq does not support.

Process. Topologiq will traverse the ZX graph transforming each spider into an equivalent lattice surgery "primitive" positioned in a 3D space.

• Positioning: define a number of tentative 3D positions for each spider.
• Pathfinding: determine which tentative positions allow topologically-correct paths.
• Value function: choose best of any number of topologically-correct paths from previous step

The final choice considers the length of each topologically-correct path found in during pathfinding, as well as their relative impact to the feasibility of future placements. Having said that, all steps in the process share objects and undertake checks that avoid overloading the final step with many unreasonably suboptimal paths.

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!