{"id":37649235,"url":"https://github.com/tqec/topologiq","last_synced_at":"2026-01-16T11:30:11.690Z","repository":{"id":286285369,"uuid":"960960921","full_name":"tqec/topologiq","owner":"tqec","description":"Quantum computing \u003e Algorithmic lattice surgery.","archived":false,"fork":false,"pushed_at":"2026-01-10T22:43:21.000Z","size":20582,"stargazers_count":43,"open_issues_count":5,"forks_count":6,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-11T06:52:58.680Z","etag":null,"topics":["3d-algorithms","algorithms","bfs","python","quantum-computing"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tqec.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-05T12:58:28.000Z","updated_at":"2025-12-14T06:06:51.000Z","dependencies_parsed_at":"2025-04-05T13:40:36.821Z","dependency_job_id":"32194d46-1789-478a-955d-aa7ca4acbb63","html_url":"https://github.com/tqec/topologiq","commit_stats":null,"previous_names":["jbolns/algorithmic_lattice_surgery","jbolns/topologiq","tqec/topologiq"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tqec/topologiq","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tqec%2Ftopologiq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tqec%2Ftopologiq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tqec%2Ftopologiq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tqec%2Ftopologiq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tqec","download_url":"https://codeload.github.com/tqec/topologiq/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tqec%2Ftopologiq/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28478273,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T06:30:42.265Z","status":"ssl_error","status_checked_at":"2026-01-16T06:30:16.248Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d-algorithms","algorithms","bfs","python","quantum-computing"],"created_at":"2026-01-16T11:30:10.929Z","updated_at":"2026-01-16T11:30:11.622Z","avatar_url":"https://github.com/tqec.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e 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.\n\n# Topologiq: Algorithmic Lattice Surgery\n**Topologiq** is tool to convert ZX circuits into logical versions of themselves. It is based on the surface code and lattice surgery.\n\nInteroperable with:\n- PyZX: [click here for an example](docs/examples/pyzx_cnots.ipynb).\n- Qiskit: [click here for an example](docs/examples/qiskit_ghz.py).\n\n\u003cbr\u003e\n\n\u003e **Work in progress**. Check \"main\" for latest stable checkpoint. Venture into open branches for the latest updates.\n\n## Summary\nAs 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.\n\n**Topologiq**'s outputs can be used as inputs for TQEC/tqec and, *theoretically*, other similar tools.\n\n\u003cbr\u003e\n\n![Algorithmic lattice surgery of a CNOT](./docs/media/cnots.gif)\n\n*Figure 1. Algorithmic lattice surgery of a CNOT.*\n\n## Install\nCurrently, the best way to test **Topologiq** is to clone the repository, recreate the environment, and install dependencies.\n\n### Using UV\n```bash\n# 1. Clone repository. \ngit clone https://github.com/jbolns/topologiq.git\n\n# 2. Sync environment.\nuv sync  # Topologiq\n# or\nuv sync --group integration  # Topologiq w. TQEC/tqec\n\n# Additional steps needed only for contributors\n# 3. Opt for an editable installation\nuv sync --group all\nuv pip install -e .\n```\n\n### Using PIP\n```bash\n# 1. Clone repository. \ngit clone https://github.com/jbolns/topologiq.git\n\n# 2. Recreate environment.\n# 2.1. Environment creation\npython -m venv .venv\n\n# 2.2. Environment activation\n.venv\\Scripts\\activate.bat  # Windows\nsource .venv/bin/activate  # Linux\n\n# 2.3. Install dependencies\npip install -r requirements.txt\n\n# Additional steps needed only for contributors\n# 3. Opt for an editable installation\npip install -e .\n```\n\n## Examples\nYou can quickly test **Topologiq** from the terminal using pre-defined circuit examples.\n\nCheck `./outputs/txt/` for results. All information in TXT outputs is also available for programmatic use.\n\n``` bash\n# PyZX examples (Available examples: cnot, cnots, simple_mess)\nuv run src/topologiq/run.py --pyzx:\u003ccircuit_name\u003e\npython3 src/topologiq/run.py --pyzx:\u003ccircuit_name\u003e  # Requires active .venv\n\n# Dict-based graph examples (Available examples: hadamard_line, hadamard_bend, steane, steane_obfs, or hadamard_mess)\nuv run src/topologiq/run.py --graph:\u003ccircuit_name\u003e\npython3 src/topologiq/run.py --graph:\u003ccircuit_name\u003e  # Requires active .venv\n```\n\nThere are also optional parameters to enable 3D visuals, animations, and debug options.\n\n``` bash\n# Enable \"final\" result or \"detail\" edge-by-edge progress visualisations\nuv run src/topologiq/run.py --pyzx:\u003ccircuit_name\u003e --vis:\u003cfinal|detail\u003e\npython3 src/topologiq/run.py --pyzx:\u003ccircuit_name\u003e --vis:\u003cfinal|detail\u003e  # Requires active .venv\n\n# Produce a \"GIF\" or \"MP4\" animation of the process (MP4 requires FFmpeg).\nuv run src/topologiq/run.py --pyzx:\u003ccircuit_name\u003e --animate:\u003cGIF|MP4\u003e\npython3 src/topologiq/run.py --pyzx:\u003ccircuit_name\u003e --animate:\u003cGIF|MP4\u003e  # Requires active .venv\n\n# Run a circuit a specific number of times irrespective of outcome for each inidividual run\nuv run src/topologiq/run.py --pyzx:\u003ccircuit_name\u003e --repeat:50\npython3 src/topologiq/run.py --pyzx:\u003ccircuit_name\u003e --repeat:50  # Requires active .venv\n\n# Log run-time and performance statistics\nuv run src/topologiq/run.py --pyzx:\u003ccircuit_name\u003e --log_stats\npython3 src/topologiq/run.py --pyzx:\u003ccircuit_name\u003e --log_stats  # Requires active .venv\n\n# Enable debug mode (incrementally detailed logs and visuals) (available modes: 1, 2, 3, 4) .\nuv run src/topologiq/run.py --pyzx:\u003ccircuit_name\u003e --vis:detail --debug:1\npython3 src/topologiq/run.py --pyzx:\u003ccircuit_name\u003e --vis:detail --debug:1  # Requires active .venv\n```\n\nThere is also an accessible debug facility to quickly run any edge case encountered while running Topologiq with `log_stats` enabled.\n``` bash\n# Pick up and replicate any available edge case (i.e. circuits Topologiq failed to build).\nuv run src/topologiq/debug.py\npython3 src/topologiq/debug.py  # Requires active .venv\n\n# NB! Case must have been logged to stats, which only happens when Topologiq runs with `log_stats` enabled.\n# NB! Currently available only for example graphs (the foundational graph must exist in file to replicate it).\n```\n\n## Yeah, but how does it work, really?\nDetailed insight into **Topologiq** and, hopefully, a paper, is in progress. Meanwhile, below, a quick overview of what goes on under the hood. \n\n**Input.** **Topologiq** will look for an incoming ZX graph and, if needed and possible, convert it into a native format.\n- ***Native format:*** A simple dictionary of nodes and edges (see `./src/topologiq/assets/graphs/simple_graphs.py` for examples).\n- ***PyZX interoperability:*** PyZX graphs supported (check `docs/examples/pyzx_cnots.ipynb` for an example).\n  - NB. If using a random PyZX circuit, ensure all qubit lines are interconnected. Else, the graph has independent subgraphs, which Topologiq does not support.\n\n**Process.** **Topologiq** will traverse the ZX graph transforming each spider into an equivalent lattice surgery \"primitive\" positioned in a 3D space.\n- ***Positioning:*** define a number of tentative 3D positions for each spider.\n- ***Pathfinding:*** determine which tentative positions allow topologically-correct paths.\n- ***Value function:*** choose best of any number of topologically-correct paths from previous step\n\nThe 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.\n\n## Contributing\nPull requests and issues are more than welcomed!\n\nSee [CONTRIBUTING](./CONTRIBUTING.md) for specific instructions to start contributing.\n\n## License\nTopologiq is licensed under an [Apache 2.0 license](./LICENSE).\n\nThe [`ETHICAL_NOTICE.md`](ETHICAL_NOTICE.md) contains additional **ethical use** pointers.\n\n## Community\nEvery Wednesday at 8:30am PST, we hold [meetings](https://meet.jit.si/TQEC-design-automation) to discuss project progress and conduct educational talks related to TQEC.\n\nHere are some helpful links to learn more about the TQEC community and Topologiq:\n- Overview of state of the art 2D QEC: [Slides](https://docs.google.com/presentation/d/1xYBfkVMpA1YEVhpgTZpKvY8zeOO1VyHmRWvx_kDJEU8/edit?usp=sharing)/[Video](https://www.youtube.com/watch?v=aUtH7wdwBAM\u0026t=2s)\n- Introduction to surface code quantum computation: [Slides](https://docs.google.com/presentation/d/1GxGD9kzDYJA6X47BXGII2qjDVVoub5BsSVrGHRZINO4/edit?usp=sharing)\n- Programming a quantum computer using SketchUp: [Slides](https://docs.google.com/presentation/d/1MjFuODipnmF-jDstEnQrqbsOtbSKZyPsuTOMo8wpSJc/edit?usp=sharing)/[Video](https://drive.google.com/file/d/1o1LMiidtYDcVoEFZXsJPb7XdTkZ83VFX/view?usp=drive_link)\n- Overview of Topologiq: [Video](https://drive.google.com/file/d/1C9Kke4qSYd0lX5qO_yvUX88DsPt8kyaP/view?usp=drive_link)\n- Qiskit-\u003eQASM-\u003eTopologiq interoperability: [Video](https://drive.google.com/file/d/1tFYNmvvyNDT04BK6U3ESRZVXB1PrObGd/view).\n\nAll the resources and group meeting recordings are available at [this link](https://docs.google.com/spreadsheets/d/11DSA2wzKLOrfTGNHunFvzsMYeO7jZ8Ny8kpzoC_wKQg/edit?usp=sharing\u0026resourcekey=0-PdGFkp5s-4XWihMSxk0UIg).\n\nPlease join the [Google group](https://groups.google.com/g/tqec-design-automation) to receive more updates and information!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftqec%2Ftopologiq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftqec%2Ftopologiq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftqec%2Ftopologiq/lists"}