A python implementation of Gate Set Tomography
Clone or download
Failed to load latest commit information.
CI Hopefully removes output from Cmake install Jun 18, 2018
doc Adds local documentation building requirements Jun 7, 2018
jupyter_notebooks Updates to tutorial notebooks 16, 17, 18. Aug 30, 2018
packages/pygsti Updates version -> 0.9.5 in preparation for release. Aug 29, 2018
scripts Adds effect penalties to spam_penalty_factor terms. Oct 4, 2017
test Updates testCalcMethods1Q.py to gauge opt before comparing gatesets. Aug 4, 2018
.gitattributes Comments out .gitattributes restrictions on .travis.yml Aug 10, 2016
.gitignore Removes accidentally added fastcalc.c; adds to .gitignore w/other C f… Jun 20, 2018
.lint.conf WIP: further refactors directories Jul 19, 2016
.travis.yml Cleans up TravisCI scripts from prior commits' experimentation. Aug 3, 2018
COPYING Added GPL license (COPYING), license.txt, and initial README with ove… Jan 25, 2016
MANIFEST.in Updates setup.py and related files. Aug 2, 2018
README.md Updates beta->master links in README.md [ci skip] Mar 2, 2018
install_locally.py 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 setup.py and related files. Aug 2, 2018
requirements.txt Updates setup.py and related files. Aug 2, 2018
rtd-requirements.txt Adds a new "rtd-requirements.txt" for doc building that includes nump… Mar 1, 2018
setup.cfg Updates setup.py and related files. Aug 2, 2018
setup.py Adds timing information to TravisCI tests. Aug 3, 2018


pyGSTi 0.9

Build Status


This is the root directory of the pyGSTi software, which is a Python implementation of Gate Set Tomography. pyGSTi free software, licensed under the GNU General Public License (GPL). Copyright and license information can be found in license.txt, and the GPL itself in COPYING.

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 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
  4. pyGSTi takes the data file and outputs a "report" - currently a HTML web page.

There are numerous Tutorial and Example ipython notebooks (especially Tutorial 0 ) included in this repository that demonstrate pyGSTi's syntax and use, as well as a FAQ.

Getting Started:

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 Jupyter notebook is highly recommended) if you haven't already. In order to use pyGSTi you need to tell your Python distribution where pyGSTi lives, which can be done in one of several ways:

  • User-Only Installation

    To install pyGSTi for the current user, you can run from the top-level directory either pip install -e . or python install_locally.py.

    This adds the current pyGSTi path to Python's list of search paths, and doesn't require administrative access. 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'd like long-term access the tutorial notebook files in the jupyter_notebooks directory under this one, since this means you'll be keeping this directory around anyway. The pip install -e . is slightly preferable since it will automatically build the optional Cython extension.

  • System-Wide Installation

    To install pyGSTi for all users, run: python setup.py install

    This installs the pyGSTi Python 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 this directory so long as you want to use pyGSTi.

    Reasons you may not want to use this installation method are

    • pyGSTi comes with (Jupyter notebook) tutorials that you may want to access for weeks and years to come (i.e. you plan to keep this pyGSTi directory around for a while).
    • you've cloned the pyGSTi repository and want this local set of files to be the one Python uses when you import pygsti.

Using pyGSTi

After you've installed pyGSTi, you should be able to import the pygsti Python package. The next thing to do is take a look at the tutorials, which you do by:

  • 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 "0th" tutorial notebook. (Note that the key command to execute a cell within the Jupyter notebook is Shift+Enter, not just Enter.) Example notebooks, found in the jupyter_notebooks/Examples/ directory, are focused on more specific tasks than the tutorials, and will be most useful for those looking to get a quick start using pyGSTi in a typical scenario.

Congratulations! You're up and running with pyGSTi!


Online documentation is hosted on Read the Docs. Instructions for building the documentation locally are contained in the file doc/build/howToBuild.txt.


For help and support with pyGSTi, please contact the authors at pygsti@sandia.gov.

Brief description of the directory structure:

doc/  :  Directory containing the HTML documentation and other
         reference documents.

jupyter_notebooks/  : Parent directory of all Jupyter notebook tutorial
		      files included with pyGSTi.  It is convenient to
		      start an Jupyter notebook server from within this

packages/  :  Directory containing the (one) package provided by pyGSTi.
	             All of the Python source code lies here.

tests/  :  Directory containing pyGSTi unit tests.

install_locally.py :  A Python script that sets up the software to run 
                      from its current location within the file system.  This
                      essentially adds the packages directory to the list of
                      directories Python uses to search for packages in, so
                      that ``import pygsti`` will work for any Python script,
                      regardless of its location in the file system.  This
                      action is local to the user running the script, and does
                      not copy any files to any system directories, making it a
                      good option for a user without administrative access.

COPYING  :  A text version of the GNU General Public License.

license.txt  :  A text file giving copyright and licensing information
	        about pyGSTi.