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.

pyGSTi is written entirely in Python, so 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 two 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.

  2. 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 iPython 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 iPython notebook, note that the key command to execute a cell within a notebook is <Shift+Enter>, not just <Enter>. Static HTML versions of these tutorials are linked to in the "Tutorials" section below.

Congratulations! You're up and running with pyGSTi!


Below is a list of tutorials for getting started with pyGSTi. These are HTML versions of the tutorials you can run interactively from iPython notebook after installing pyGSTi (see above). We've converted them to HTML and made them available here both to serve as a reference and so you can see pyGSTi in action before you (or without needing to) install it.

  1. Quick and easy GST Get started with pyGSTi using the high-level interface. This may be the only tutorial many users will need.
  2. Gate sets Covers the GateSet object and related functions.
  3. Gate strings Covers the GateString object and related functions, specifically how to make lists of gate strings.
  4. Data sets Covers construction and use of DataSet objects.
  5. Algorithms How to invoke pyGSTi's algorithms (at a lower level than in the first tutorial).
  6. Making Plots Shows how to construct various types of plots from a GST estimate.
  7. Advanced: Algorithms An advanced and incomplete tutorial showing how to use some of pyGSTi's model selection routines.
  8. Generating Reports Covers how to generate reports from a GST estimate.
  9. Advanced: Fiducial Reduction An advanced tutorial demonstrating fiducial-pair-reduction.
  10. Advanced: Bootstrapped Error Bars An advanced tutorial which constructs error bars on a GST estimate using parametric and non-parametric bootstrapping.
  11. Fiducial Selection A tutorial demonstrating how the fiducial gate sequences are chosen (1-qubit example).
  12. Fiducial Selection II A tutorial demonstrating how the fiducial gate sequences are chosen (2-qubit example).
  13. Germ Selection A tutorial demonstrating how germ sequences are chosen.
  14. 2-qubit GST A tutorial demonstrating how to peform GST on a 2-qubit system.
  15. Custom 2-qubit gate A tutorial demonstrating a process that can be used to construct a custom 2-qubit gate (i.e. a gate not included in one of pyGSTi's standard gate sets).


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