{"id":19863959,"url":"https://github.com/sandialabs/pygsti","last_synced_at":"2025-05-16T01:05:14.037Z","repository":{"id":37270685,"uuid":"50546915","full_name":"sandialabs/pyGSTi","owner":"sandialabs","description":"A python implementation of Gate Set Tomography","archived":false,"fork":false,"pushed_at":"2025-05-15T22:33:47.000Z","size":133210,"stargazers_count":148,"open_issues_count":103,"forks_count":54,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-05-15T23:26:47.786Z","etag":null,"topics":["characterization","gst","qcvv","quantum-computing","scr-2018","snl-quantum-computing","tomography"],"latest_commit_sha":null,"homepage":"http://www.pygsti.info","language":"Jupyter Notebook","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/sandialabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-01-27T23:59:04.000Z","updated_at":"2025-03-25T18:45:53.000Z","dependencies_parsed_at":"2025-05-08T21:23:57.575Z","dependency_job_id":null,"html_url":"https://github.com/sandialabs/pyGSTi","commit_stats":null,"previous_names":["sandialabs/pygsti","pygstio/pygsti"],"tags_count":39,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandialabs%2FpyGSTi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandialabs%2FpyGSTi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandialabs%2FpyGSTi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sandialabs%2FpyGSTi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sandialabs","download_url":"https://codeload.github.com/sandialabs/pyGSTi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254448579,"owners_count":22072764,"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":["characterization","gst","qcvv","quantum-computing","scr-2018","snl-quantum-computing","tomography"],"created_at":"2024-11-12T15:16:56.417Z","updated_at":"2025-05-16T01:05:09.027Z","avatar_url":"https://github.com/sandialabs.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"********************************************************************************\n  pyGSTi 0.9.13.1\n********************************************************************************\n\n[![master build](https://img.shields.io/github/actions/workflow/status/sandialabs/pyGSTi/beta-master.yml?branch=master\u0026label=master)](https://github.com/sandialabs/pyGSTi/actions/workflows/beta-master.yml)\n[![develop build](https://img.shields.io/github/actions/workflow/status/sandialabs/pyGSTi/develop.yml?branch=develop\u0026label=develop)](https://github.com/sandialabs/pyGSTi/actions/workflows/develop.yml)\n[![beta build](https://img.shields.io/github/actions/workflow/status/sandialabs/pyGSTi/beta-master.yml?branch=beta\u0026label=beta)](https://github.com/sandialabs/pyGSTi/actions/workflows/beta-master.yml)\n\npyGSTi\n------\n**pyGSTi** is an open-source software for *modeling and characterizing noisy quantum information processors*\n(QIPs), i.e., systems of one or more qubits.  It is licensed under the Apache License, Version 2.0.\nCopyright information can be found in ``NOTICE``, and the license itself in ``LICENSE``.\n\nThere are three main objects in pyGSTi:\n- `Circuit`: a quantum circuit (can have many qubits).\n- `Model`: a description of a QIP's gate and SPAM operations (a noise model).\n- `DataSet`: a dictionary-like container holding experimental data.\n\nYou can do various things by with these objects:\n\n- **Circuit simulation**: compute a the outcome probabilities of a `Circuit` using a `Model`.\n- **Data simulation**: simulate experimental data (a `DataSet`) using a `Model`.\n- **Model testing**: Test whether a given `Model` fits the data in a `DataSet`.\n- **Model estimation**: Estimate a `Model` from a `DataSet` (e.g. using GST).\n- **Model-less characterization**: Perform Randomized Benchmarking on a `DataSet`.\n\nIn particular, there are a number of characterization protocols currently implemented in pyGSTi:\n- **Gate Set Tomography (GST)** is the most complex and is where the software derives its name\n (a \"python GST implementation\").\n- **Randomized Benchmarking (RB)** is a well-known method for assessing the\n quality of a QIP in an average sense.  PyGSTi implements standard \"Clifford\" RB\n as well as the more scalable \"Direct\" RB methods.\n- **Robust Phase Estimation (RPE)** is a method designed for quickly learning\n a few noise parameters of a QIP that particularly useful for tuning up qubits.\n\nPyGSTi is designed with a modular structure so as to be highly customizable\nand easily integrated to new or existing python software.  It runs using\npython 3.9 or higher.  To faclilitate integration with software for running\ncloud-QIP experiments, pyGSTi `Circuit` objects can be converted to IBM's\n**OpenQASM** and Rigetti Quantum Computing's **Quil** circuit description languages.\n\nInstallation\n------------\nApart from several optional Cython modules, pyGSTi is written entirely in Python.\nTo install pyGSTi and only its required dependencies run:\n\n``pip install pygsti``\n\n**Or**, to install pyGSTi with all its optional dependencies too, run:\n\n``pip install pygsti[complete]``\n\nThe disadvantage to these approaches is that the numerous tutorials\nincluded in the package will then be buried within your Python's\n`site_packages` directory, which you'll likely want to access later on.\n**Alternatively**, you can **locally install** pyGSTi using the following commands:\n\n~~~\ncd \u003cinstall_directory\u003e\ngit clone https://github.com/pyGSTio/pyGSTi.git\ncd pyGSTi\npip install -e .[complete]\n~~~\n\nAs above, you can leave off the `.[complete]` if you only went the minimal\nset of dependencies installed.  You could also replace the `git clone ...`\ncommand with `unzip pygsti-0.9.x.zip` where the latter file is a downloaded\npyGSTi source archive.  Any of the above installations *should* build\nthe set of optional Cython extension modules if a working C/C++ compiler\nand the `Cython` package are present.  If, however, compilation fails or\nyou later decided to add Cython support, you can rebuild the extension\nmodules (without reinstalling) if you've followed the local installation\napproach above using the command:\n\n`python setup.py build_ext --inplace`\n\nFinally, [Jupyter notebook](http://jupyter.org/) is highly recommended as\nit is generally convenient and the format of the included tutorials and\nexamples.  It is installed automatically when `[complete]` is used, otherwise\nit can be installed separately.\n\nGetting Started\n---------------\nHere's a couple of simple examples to get you started.\n\n#### Circuit simulation\nTo compute the outcome probabilities of a circuit, you just need to create\na `Circuit` object (describing your circuit) and a `Model` object containing\nthe operations contained in your circuit.  Here we use a \"stock\" single-qubit `Model`\ncontaining *Idle*, *X(\u0026pi;/2)*, and *Y(\u0026pi;/2)* gates labelled `Gi`, `Gx`,\nand `Gy`, respectively:\n~~~\nimport pygsti\nfrom pygsti.modelpacks import smq1Q_XYI\n\nmycircuit = pygsti.circuits.Circuit([('Gxpi2',0), ('Gypi2',0), ('Gxpi2',0)])\nmodel = smq1Q_XYI.target_model()\noutcome_probabilities = model.probabilities(mycircuit)\n~~~\n\n\n#### Gate Set Tomography\nGate Set Tomography is used to characterize the operations performed by\nhardware designed to implement a (small) system of quantum bits (qubits).\nHere's the basic idea:\n\n  1. you tell pyGSTi what gates you'd ideally like to perform\n  2. pyGSTi tells you what circuits it want's data for\n  3. you perform the requested experiments and place the resulting\n     data (outcome counts) into a text file that looks something like:\n\n     ```\n     ## Columns = 0 count, 1 count\n     {} 0 100  # the empty sequence (just prep then measure)\n     Gx 10 90  # prep, do a X(pi/2) gate, then measure\n     GxGy 40 60  # prep, do a X(pi/2) gate followed by a Y(pi/2), then measure\n     Gx^4 20 80  # etc...\n     ```\n\n  4. pyGSTi takes the data file and outputs a \"report\" - currently a\n     HTML web page.\n\nIn code, running GST looks something like this:\n~~~\nimport pygsti\nfrom pygsti.modelpacks import smq1Q_XYI\n\n# 1) get the ideal \"target\" Model (a \"stock\" model in this case)\nmdl_ideal = smq1Q_XYI.target_model()\n\n# 2) generate a GST experiment design\nedesign = smq1Q_XYI.create_gst_experiment_design(4) # user-defined: how long do you want the longest circuits?\n\n# 3) write a data-set template\npygsti.io.write_empty_dataset(\"MyData.txt\", edesign.all_circuits_needing_data, \"## Columns = 0 count, 1 count\")\n\n# STOP! \"MyData.txt\" now has columns of zeros where actual data should go.\n# REPLACE THE ZEROS WITH ACTUAL DATA, then proceed with:\nds = pygsti.io.load_dataset(\"MyData.txt\") # load data -\u003e DataSet object\n\n# OR: Create a simulated dataset with:\n# ds = pygsti.data.simulate_data(mdl_ideal, edesign, num_samples=1000)\n\n# 4) run GST (now using the modern object-based interface)\ndata = pygsti.protocols.ProtocolData(edesign, ds) # Step 1: Bundle up the dataset and circuits into a ProtocolData object\nprotocol = pygsti.protocols.StandardGST() # Step 2: Select a Protocol to run\nresults = protocol.run(data) # Step 3: Run the protocol!\n\n# 5) Create a nice HTML report detailing the results\nreport = pygsti.report.construct_standard_report(results, title=\"My Report\", verbosity=1)\nreport.write_html(\"myReport\", auto_open=True, verbosity=1) # Can also write out Jupyter notebooks!\n~~~\n\nTutorials and Examples\n----------------------\nThere are numerous tutorials (meant to be pedagogical) and examples (meant to be demonstrate\nhow to do some particular thing) in the form of Jupyter notebooks beneath the `pyGSTi/jupyter_notebooks`\ndirectory.  The root \"START HERE\" notebook will direct you where to go based on what you're most\ninterested in learning about.  You can view the\n[read-only GitHub version of this notebook](https://github.com/pyGSTio/pyGSTi/blob/master/jupyter_notebooks/START_HERE.ipynb)\nor you can [explore the tutorials interactively](https://mybinder.org/v2/gh/pyGSTio/pyGSTi/master)\nusing JupyterHub via Binder.  Note the existence of a\n[FAQ](https://github.com/pyGSTio/pyGSTi/blob/master/jupyter_notebooks/FAQ.ipynb), which\naddresses common issues.\n\n\n#### Running notebooks *locally*\nWhile it's possible to view the notebooks on GitHub using the links above, it's\nusually nicer to run them *locally* so you can mess around with the code as\nyou step through it.  To do this, you'll need to start up a Jupyter notebook\nserver using the following steps (this assumes you've followed the *local\ninstallation* directions above):\n\n* Changing to the notebook directory, by running:\n    ``cd jupyter_notebooks/Tutorials/``\n\n* Start up the Jupyter notebook server by running:\n  ``jupyter notebook``\n\nThe Jupyter server should open up your web browser to the server root, from\nwhere you can start the first \"START_HERE.ipynb\" notebook.  Note that the key\ncommand to execute a cell within the Jupyter notebook is ``Shift+Enter``, not\njust ``Enter``.\n\n\nDocumentation\n-------------\nOnline documentation is hosted on [Read the Docs](http://pygsti.readthedocs.io).\n\nLicense\n-------\nPyGSTi is licensed under the [Apache License Version 2.0](https://github.com/pyGSTio/pyGSTi/blob/master/LICENSE).\n\n\nQuestions?\n----------\nFor help and support with pyGSTi, please contact the authors at\npygsti@sandia.gov.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsandialabs%2Fpygsti","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsandialabs%2Fpygsti","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsandialabs%2Fpygsti/lists"}