View on GitHub
pyGSTi icon


A python implementation of Gate Set Tomography

View the online documentation Download this project as a .zip file Download this project as a tar.gz file

Getting Started

pyGSTi is a software package to perform gate set tomography (GST). GST is a kind of quantum tomography, and it provides full characterization of quantum logic gates on quantum devices such as qubits. For a basic (albeit out of date) introduction to GST, see (by the pyGSTi authors) or (by an independent 3rd party). The first of these papers describes a relatively recent use of GST, similar to what's in pyGSTi. The second describes a more primitive initial version of gate set tomography which looks much different than the current pyGSTi code. More recently, the appendix of contains descriptions of GST's major components.

Gate Set Tomography is used to characterize the operations performed by hardware designed to implement a (small) system of quantum bits (qubits). Here's the basic idea:

  1. you tell pyGSTi what quantum operations you'd like to perform
  2. pyGSTi tells you what sequences of operations it want's data for
  3. you perform the requested experiments and place the resulting
  4. data (outcome counts) into a text file that looks something like: ## Columns = 0 count, 1 count {} 0 100 Gx 10 90 GxGy 40 60 Gx^4 20 80
  5. pyGSTi takes the data file and outputs a "report" - currently a HTML web page.

pyGSTi is written almost entirely in Python. Apart from a single (optional!) Cython module, there's no compiling necessary. The first step is to install Python and iPython (Jupyter) notebook (if they aren't installed already). In order to use pyGSTi you need to tell your python distribution where pyGSTi lives, which can be done in one of three ways:

  1. run: python

    This adds the current pyGSTi path to Python's list of search paths, and doesn't required administrative access (but only applies to the current user). Typically you want to do this if you've cloned the pyGSTi GitHub repository and want any changes you make to your local file to have effect when you import pygsti from Python. You'd also want to use this option if you plan to use the tutorial notebook files for a while, since this means you'll be keeping the pyGSTi directory you unpacked or cloned around for a while. This won't build the Cython module, however, so it is now preferable to use the following approach.

  2. run: pip install -e /path/to/pyGSTi

    This performs the same local type of installation as above, but will also build the Cython module. The only downside of this approach compared with the one above, is that it requires you to have pip installed.

  3. run: python install

    This installs the pyGSTi package into one of the Python distribution's search directories. This typically requires administrative privileges, and is the way most Python packages are installed. Installing this way has the advantage that it makes the package available to all users and then allows you to move or delete the directory you're installing from. If you don't use this method you must not delete the pyGSTi directory that you cloned or unpacked so long as you want to use pyGSTi.

    Reasons you may not want to use this installation method are (1) that you want to access the pyGSTi tutorials for weeks and years to or (2) you've cloned the pyGSTi repository and want the resulting local git directory to be the one Python uses when you import pygsti (so that when you do a git pull to update the repository, this actually updates the behavior in your scripts!).

After you've installed pyGSTi, you should be able to import pygsti in Python or an iPython (Jupyter) notebook. The next step is to take a look at the tutorials. To do this:

The Jupyter server should open up your web browser to the server root. From there, you can navigate to the "Tutorials" folder and start the first tutorial notebook, “00 Quick and easy GST”. If you're new to Jupyter notebooks, note that the key command to execute a cell within a notebook is <Shift+Enter>, not just <Enter>. Static HTML versions of these tutorials can be viewed on GitHub as described in the "Tutorials" section below.

Congratulations! You're up and running with pyGSTi!


The next step is to checkout pyGSTi's tutorial notebooks, which explain how to get started with pyGSTi. Following the preceding link and clicking on a notebook file will cause GitHub display a static HTML version of the tutorial. After installing pyGSTi and Jupyter you'll be able to run the tutorials interactively (see above). You don't need to work through all of the tutorials to make good use of the software - in fact, Tutorial 0 demonstrates how to go from experimental qubit data to nice shiny reports. In addition to the tutorials, there are Example notebooks. These are similar to the tutorial notebooks but less pedagogical and more focused on quickly demonstrating how to do a particular task. The example notebooks sit in a peer directory to the tutorials, and their common parent directory contains a Frequently-asked questions notebook that links some of the examples to the questions they're designed to answer.


Detailed documentation of the pyGSTi code (automatically generated from the source code's docstrings) can be found here. These pages provide a searchable reference for just about everything pyGSTi can do. Please let us know if you find any errors.


pyGSTi is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. To cite this work, please use the DOI: 10.5281/zenodo.46200


For help and support with pyGSTi, please contact the authors at