Skip to content
A python implementation of Gate Set Tomography
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/ISSUE_TEMPLATE Added default labels for issue templates Apr 24, 2019
CI CI push script merges and fast-forwards instead of rebasing May 1, 2019
doc Adds local documentation building requirements Jun 7, 2018
jupyter_notebooks Final updates to notebooks before 0.9.8 release. Jun 29, 2019
packages/pygsti Corrects PEP8 warnings. Jun 29, 2019
scripts Adds convenience scripts/ and Jun 4, 2019
test Circumvents python2.7 NaN error by adding try/except to problem tests. Jun 28, 2019
.flake8 Manual fixes to redundant line continuations (E502) Apr 17, 2019
.flake8-critical Added more comprehensive flake8 config & split into seperate 'critica… Apr 16, 2019
.gitattributes Comments out .gitattributes restrictions on .travis.yml Aug 10, 2016
.gitignore Gitignored pyGSTi egg-info (case-sensitive) Jun 30, 2019
.lint.conf WIP: further refactors directories Jul 19, 2016
.travis.yml Disabling Travis wheel build on deploy Jun 30, 2019 Adds text about emailing us if you want a CLA :) Apr 30, 2019
COPYING Added GPL license (COPYING), license.txt, and initial README with ove… Jan 25, 2016 Adds to (forgotten in 0.9.7 release!) Jan 21, 2019 Adds Binder link to Jan 31, 2019 Adds indentation-fix to pre-commit hook Jul 21, 2016
license.txt Added GPL license (COPYING), license.txt, and initial README with ove… Jan 25, 2016
optional-requirements.txt Updates and related files. Aug 2, 2018
requirements.txt Reverting requirements.txt back to *not* pinning plotly (merging Apr 23, 2019
rtd-requirements.txt Adds a new "rtd-requirements.txt" for doc building that includes nump… Mar 1, 2018
setup.cfg Added more comprehensive flake8 config & split into seperate 'critica… Apr 16, 2019 Unpinned scipy version (not needed) and broke up Travis install into … Jun 28, 2019

pyGSTi 0.9

Build Status


pyGSTi is an open-source software for modeling and characterizing noisy quantum information processors (QIPs), i.e., systems of one or more qubits. It is licensed under the GNU General Public License (GPL). Copyright and license information can be found in license.txt, and the GPL itself in COPYING.

There are three main objects in pyGSTi:

  • Circuit: a quantum circuit (can have many qubits).
  • Model: a description of a QIP's gate and SPAM operations (a noise model).
  • DataSet: a dictionary-like container holding experimental data.

You can do various things by with these objects:

  • Circuit simulation: compute a the outcome probabilities of a Circuit using a Model.
  • Data simulation: simulate experimental data (a DataSet) using a Model.
  • Model testing: Test whether a given Model fits the data in a DataSet.
  • Model estimation: Estimate a Model from a DataSet (e.g. using GST).
  • Model-less characterization: Perform Randomized Benchmarking on a DataSet.

In particular, there are a number of characterization protocols currently implemented in pyGSTi:

  • Gate Set Tomography (GST) is the most complex and is where the software derives its name (a "python GST implementation").
  • Randomized Benchmarking (RB) is a well-known method for assessing the quality of a QIP in an average sense. PyGSTi implements standard "Clifford" RB as well as the more scalable "Direct" RB methods.
  • Robust Phase Estimation (RPE) is a method designed for quickly learning a few noise parameters of a QIP that particularly useful for tuning up qubits.

PyGSTi is designed with a modular structure so as to be highly customizable and easily integrated to new or existing python software. It runs using python2.7 or python3. To faclilitate integration with software for running cloud-QIP experiments, pyGSTi Circuit objects can be converted to IBM's OpenQASM and Rigetti Quantum Computing's Quil circuit description languages.


Apart from several optional Cython modules, pyGSTi is written entirely in Python. To install pyGSTi and only its required dependencies run:

pip install pygsti

Or, to install pyGSTi with all its optional dependencies too, run:

pip install pygsti[complete]

The disadvantage to these approaches is that the numerous tutorials included in the package will then be buried within your Python's site_packages directory, which you'll likely want to access later on. Alternatively, you can locally install pyGSTi using the following commands:

cd <install_directory>
git clone
cd pyGSTi
pip install -e .[complete]

As above, you can leave off the .[complete] if you only went the minimal set of dependencies installed. You could also replace the git clone ... command with unzip where the latter file is a downloaded pyGSTi source archive. Any of the above installations should build the set of optional Cython extension modules if a working C/C++ compiler and the Cython package are present. If, however, compilation fails or you later decided to add Cython support, you can rebuild the extension modules (without reinstalling) if you've followed the local installation approach above using the command:

python build_ext --inplace

Finally, Jupyter notebook is highly recommended as it is generally convenient and the format of the included tutorials and examples. It is installed automatically when [complete] is used, otherwise it can be installed separately.

Getting Started

Here's a couple of simple examples to get you started.

Circuit simulation

To compute the outcome probabilities of a circuit, you just need to create a Circuit object (describing your circuit) and a Model object containing the operations contained in your circuit. Here we use a "stock" single-qubit Model containing Idle, X(π/2), and Y(π/2) gates labelled Gi, Gx, and Gy, respectively:

import pygsti
from import std1Q_XYI

mycircuit = pygsti.obj.Circuit( ('Gx','Gy','Gx') )
model = std1Q_XYI.target_model()
outcome_probabilities = model.probs(mycircuit)

Gate Set Tomography

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 gates you'd ideally like to perform

  2. pyGSTi tells you what circuits it want's data for

  3. you perform the requested experiments and place the resulting data (outcome counts) into a text file that looks something like:

    ## Columns = 0 count, 1 count
    {} 0 100  # the empty sequence (just prep then measure)
    Gx 10 90  # prep, do a X(pi/2) gate, then measure
    GxGy 40 60  # prep, do a X(pi/2) gate followed by a Y(pi/2), then measure
    Gx^4 20 80  # etc...
  4. pyGSTi takes the data file and outputs a "report" - currently a HTML web page.

In code, running GST looks something like this:

import pygsti
from import std1Q_XYI

# 1) get the ideal "target" Model (a "stock" model in this case)
mdl_ideal = std1Q_XYI.target_model()

# 2) get the building blocks needed to specify which circuits are needed
prepfids, measfids, germs = std1Q_XYI.prepStrs, std1Q_XYI.effectStrs, std1Q_XYI.germs
maxLengths = [1,2,4] # user-defined: how long do you want the circuits?

# 3) generate a list of circuits for GST & write a data-set template
listOfExperiments =
    mdl_ideal, prepfids, measfids, germs, maxLengths)"MyData.txt", listOfExperiments, "## Columns = 0 count, 1 count")

# STOP! "MyData.txt" now has columns of zeros where actual data should go.
ds ="MyData.txt") # load data -> DataSet object

# 4) run GST
results = pygsti.do_stdpractice_gst(ds, mdl_ideal, prepfids, measfids, germs, maxLengths)

# 5) Create a nice HTML report detailing the results, filename="myReport", title="Sample Report")

Tutorials and Examples

There are numerous tutorials (meant to be pedagogical) and examples (meant to be demonstrate how to do some particular thing) in the form of Jupyter notebooks beneath the pyGSTi/jupyter_notebooks directory. The root "START HERE" notebook will direct you where to go based on what you're most interested in learning about. You can view the read-only GitHub version of this notebook or you can explore the tutorials interactively using JupyterHub via Binder. Note the existence of a FAQ, which addresses common issues.

Running notebooks locally

While it's possible to view the notebooks on GitHub using the links above, it's usually nicer to run them locally so you can mess around with the code as you step through it. To do this, you'll need to start up a Jupyter notebook server using the following steps (this assumes you've followed the local installation directions above):

  • Changing to the notebook directory, by running: cd jupyter_notebooks/Tutorials/

  • Start up the Jupyter notebook server by running: jupyter notebook

The Jupyter server should open up your web browser to the server root, from where you can start the first "START_HERE.ipynb" notebook. Note that the key command to execute a cell within the Jupyter notebook is Shift+Enter, not just Enter.


Online documentation is hosted on Read the Docs.


PyGSTi is licensed under the GNU General Public License (GPL).


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

You can’t perform that action at this time.