{"id":13776780,"url":"https://github.com/jacobmarks/QTop","last_synced_at":"2025-05-11T10:31:15.382Z","repository":{"id":79134543,"uuid":"63372599","full_name":"jacobmarks/QTop","owner":"jacobmarks","description":"Topological Quantum Computing Simulator","archived":false,"fork":false,"pushed_at":"2020-02-15T01:37:58.000Z","size":2731,"stargazers_count":32,"open_issues_count":2,"forks_count":12,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-04-16T07:21:08.021Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jacobmarks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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}},"created_at":"2016-07-14T21:58:20.000Z","updated_at":"2023-10-26T08:59:13.000Z","dependencies_parsed_at":"2023-04-17T10:56:11.043Z","dependency_job_id":null,"html_url":"https://github.com/jacobmarks/QTop","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacobmarks%2FQTop","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacobmarks%2FQTop/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacobmarks%2FQTop/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacobmarks%2FQTop/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jacobmarks","download_url":"https://codeload.github.com/jacobmarks/QTop/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253551672,"owners_count":21926333,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-08-03T18:00:32.951Z","updated_at":"2025-05-11T10:31:13.485Z","avatar_url":"https://github.com/jacobmarks.png","language":"Python","readme":"# QTop\n# *** NOTE: This software is not being actively maintained. Use at your own risk.\n\n\n## Version 0.3 - 11 July 2017\n\nQTop is an open-source python module for simulation and visualization of \ntopological quantum codes. QTop is object-oriented and easy to read,\nfacilitating the addition and assessment of new topological computing\narchitectures, as well as the development of novel decoders.\n\nQTop allows for the simulation of topologies with arbitrary code depth,\nqudit dimension, and error models. Currently, QTop features Kitaev quantum \ndouble models, as well as color codes in 3-regular planar tilings. In \nthe future, I hope to add 3-dimensional color codes, gauge color codes, and \nmore exotic topological systems.\n\nSpecial thanks to Vlad Gheorghiu for his help with plotting, and Tomas Jochym-O'Connor for help implementing DSP and GCC decoders.\n\n\nCopyright (c) 2017 Jacob Marks, jamarks AT stanford DOT edu.\n\n---\nQTop is free software: you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nQTop is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with QTop.  If not, see \u003chttp://www.gnu.org/licenses/\u003e.\n\n---\n\n# Brief Tutorial\n\n## Basics\nQTop's base classes are `Code`, `ErrorModel`, and `decoder`. The methods of `Code` are included in the 'common' module. In this first installment of the tutorial, you will learn how to create instances of topological quantum error correcting codes.\n\nIn QTop, `Code` is the base class for topological error correcting codes. From this, surface and color codes are derived as subclasses. In addition, this base class can easily be extended to 3D color codes, gauge color codes, and more exotic topological codes. `Code` contains all information about the data and measurement qudits, the dimension of each qudit, and the code depth, i.e. the smallest number of physical qubits that must present errors for there to be a logical error. In addition, `Code` stores the network connections on the primal and dual lattices.\n\nLet's say we want to instantiate a 6-6-6 color code of code depth 11, and qudit dimension 3. The relevant subclass of `Code` is `Color666`, and this class resides in the `color_codes` module. \n\n```python\ncode = color_codes.Color666(11, 3)\n```\n\nWe can view this code with the plotting methods\n\n```python\nvisualization.PlotPlaquette(code, \"Color Code\")\nplt.show()\n```\n\nwhich produces the following plot:\n\n![alt text](/visualizations/plaquette.png)\n\nBlack dots represent data qubits. Measurement qubits, which come in types 'red', 'blue', and 'green', lie at the center of each hexagonal stabilizer. The edges of each color are the edges of the dual shrunk lattice of that color. Diamonds of a given color show external 'pseudo' measurement qudits, and their 'pseudo' connections to internal measurement qudits are pictured as dashed lines.\n\nIf instead, we wanted to view only the primal lattice (connections between data qudits) we could type:\n\n```python\nvisualization.PlotPrimal(code, \"Color Code\")\nplt.show()\n```\n\n![alt text](/visualizations/primal.png)\n\n## Error Models\n\nOnce we have our code, we need to choose an error model under which to simulate the code's time evolution. In QTop, error models are represented by objects containing the Pauli X, Y and Z error probabilities associated with each gate. All error model objects are instances of the base class `ErrorModel`, or a subclass thereof. Inherent subclasses include `CodeCapacity`, `Phenomenological`, and `CircuitLevel`, which are the three most commonly used error models in the literature.\n\nIf we want to create our own error model, we just need to specify the faulty gates in `ErrorModel`. Suppose we want to create an error model with faulty initialization, which presents a Pauli X error with probability p, and Pauli Z error with probability p/2 for some p. \nQTop ErrorModel objects take as input lambda functions, not probabilities. This way, you don't have to create a new object each time you want to run a simulation with a new probability.\n\n```python\ndef probs():\n  return lambda p: [float(p), 0, float(p)/2]\n\nerrors = probs()\n```\n\n\n\n\nThen we instantiate our model:\n\n```python\nmodel = error_models.ErrorModel(initialize = errors)\n```\n\nWe can simulate our code under this error model with the `CodeCycle` method:\n\nFor simplicity, we will set `p = 0.1`.\n\n\n```python\ncode = code.CodeCycle(model, p)\n```\n\nafter this, errors in our code, i.e. non-trivial eigenvalue measurements, are indicated by stars. The size of the star scales with the magnitude of the error.\n\n![alt text](/visualizations/before_decoding.png)\n\nIf we want to find all 'red' measurement qudits with Pauli Z errors, we write\n\n```python\ns = code.Syndrome('red', 'Z')\nprint s\n```\n\n## Decoders\n\nAt this point, we have a code with errors given by the action of our error model. We want to return the code to its codespace by correcting for those errors in an efficient and effective way. To do this, we need to apply homologically trivial correction chains.\n\nEvery decoding object has a matching algorithm - the algorithm that matches up elements of the overall error syndrome. In the case of the qubit surface code, an effective algorithm is Edmunds' Blossom algorithm for minimum weight perfect matching, which splits the syndrome into localized pairs of measurement qubits.\n\nAlternatively, renormalization group clustering identifies all maximally disjoint neutral clusters at a given distance scale, and then pairs off elements of the same charge within these clusters. One element in this pair has its excitation charge 'transported' to the other one. This is continued until these neutral clusters are annihilated. Then, the scale is increased and the process starts again. This ensues until the syndrome is empty.\n\nFor the purpose of demonstration, we will use our novel Generalized Color Clustering (GCC) decoder. All decoders lie in the `decoders` module:\n\n```python\ndecoder = gcc.GCC_decoder()\n```\n\nThen we perform error correction by applying this decoder:\n\n```python\ncode = decoder(code)\n```\n\nThis leads to the corrected lattice represented below:\n\n![alt text](/visualizations/after_decoding.png)\n\nFinally, we can assess our decoding by checking to see if any logical errors have occurred. \n\n```python\nprint code.hasLogicalError()\n```\n\nOur above decoding was successful in returning the code to the codespace, as can be seen by the presence of only combinations of stabilizers in the corrected lattice. This means that there was no logical error. If, instead we had started with the pre-decoding code\n\n![alt text](/visualizations/before_error.png)\n\nour decoding procedure would result in a collection of excitations that anticommutes with the logical operators supported on the code. This is visualized by a string of data excitations connecting boundaries of all three types.\n\n![alt text](/visualizations/after_error.png)\n\n\n## Putting it all Together\n\nIn this brief tutorial, we've introduced the fundamentals of codes, error models, and decoders. These are the three basic ingredients of a `simulation`. Then, `sim = simulation(2, \"666 Color Code\", [model, \"Test Model\"], [decoder, \"GCC\"])` instantiates a simulation object. The first two input arguments are used to construct the code itself. We can run a simulation by calling our simulation object, with a code depth `L`, and a physical error rate `p`. We succeed if we decode our code without any logical errors, in which case `sim(L, p)` returns `True `. Otherwise, we fail.\n\nWe can `run` this simulation by specifying a range of probabilities and code depths, and the number of trials to conduct for each depth-probability combination.\n\n```python\nimport numpy as np\ndepths = np.linspace(5,55,6)\nprobabilities = np.logspace(-3,-0.5,10)\ntrials = 1000\nrun(sim, depths, probabilities, trials)\n```\nThis will store a time-stamped pickled file of the logical error rate for each depth-probability combination. If this is stored in the file `data.pickle`, then we can plot out results and obtain a threshold estimate with uncertainties by typing `plot_results.py data.pickle output.png mode` in the command line, where `mode` specifies the type of the plot and must be either `linear`, `loglog` or `semilog`.\n\n\n---\n\n\n\n\n\n\n\n\n\n---\n\n","funding_links":[],"categories":["Quantum simulators"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjacobmarks%2FQTop","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjacobmarks%2FQTop","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjacobmarks%2FQTop/lists"}