Getting started with pyGSTi and Gate Set Tomography

The pygsti package provides multiple levels of abstraction over the core Gate Set Tomography (GST) algorithms. This initial tutorial will show you how to run Gate Set Tomography on some simulated (generated) data, hopefully giving you an overall sense of what it takes (and how easy it is!) to run GST. Subsequent tutorials will delve into the details of pygsti objects and algorithms, and how to use them in detail.

To run GST, we need three inputs:

  1. a "target gate set" which describes the desired, or ideal, operations we want our experimental hardware to perform. In the example below, we use one of pyGSTi's "standard" gate sets - the on acting on a single qubit with the following operations:

    • three gates: the identity, and $\pi/2$ rotations around the $x$- and $y$-axes.
    • a single state preparation in the $|0\rangle$ state.
    • a 2-outcome measurement with the label "0" associated with measuring $|0\rangle$ and "1" with measuring $|1\rangle$.
  2. a list of GST sequences corresponding to the target gate set; essentially a list of what experiments (= gate sequences) we need to run. Using a standard gate set makes things especially straightforward here, since the building blocks, called germ and fiducial sequences needed to make good GST sequences have already been computed.

  3. data, in the form of experimental outcome counts, for each of the required sequences. In this example we'll generate "fake" or "simulated" data from a depolarized version of our ideal gate set.

In [1]:
#Make print statements compatible with Python 2 and 3
from __future__ import print_function

#Import the pygsti module (always do this) and the standard XYI gate set
import pygsti
from import std1Q_XYI

# 1) get the target GateSet
gs_target = std1Q_XYI.gs_target

# 2) get the building blocks needed to specify which gate sequences are needed
prep_fiducials, meas_fiducials = std1Q_XYI.prepStrs, std1Q_XYI.effectStrs
germs = std1Q_XYI.germs
maxLengths = [1,2,4,8,16,32] # roughly gives the length of the sequences used by GST

# 3) generate "fake" data from a depolarized version of gs_target
gs_datagen = gs_target.depolarize(gate_noise=0.1, spam_noise=0.001)
listOfExperiments =
    gs_target, prep_fiducials, meas_fiducials, germs, maxLengths)
ds =, listOfExperiments, nSamples=1000,
                                            sampleError="binomial", seed=1234)

#Note: from listOfExperiments we can also create an empty dataset file
# which has columns of zeros where actual data should go."tutorial_files/GettingStartedDataTemplate.txt", listOfExperiments,
                              "## Columns = 1 count, count total")
# After replacing the zeros with actual data, the data set can be 
# loaded back into pyGSTi using the line below and used in the rest
# of this tutorial. 
#ds ="tutorial_files/GettingStartedDataTemplate.txt")

Now that we have all of the inputs, we can run GST in a standard way using the do_stdpractice_gst high-level driver function. This returns a object, from which we can generate a report giving us a summary of the analysis.

In [2]:
#Run GST and create a report
results = pygsti.do_stdpractice_gst(ds, gs_target, prep_fiducials, meas_fiducials, germs, maxLengths), filename="tutorial_files/gettingStartedReport",
                                    title="Tutorial0 Example Report", verbosity=2)
-- Std Practice:  Iter 1 of 3  (TP) --: 
  --- Gate Sequence Creation ---
  --- LGST ---
  --- Iterative MLGST: [##################################################] 100.0%  1702 gate strings ---
  Iterative MLGST Total Time: 5.6s
  --- Re-optimizing logl after robust data scaling ---
  -- Performing 'single' gauge optimization on TP estimate --
  -- Performing 'single' gauge optimization on TP.Robust+ estimate --
-- Std Practice:  Iter 2 of 3  (CPTP) --: 
  --- Gate Sequence Creation ---
  --- Iterative MLGST: [##################################################] 100.0%  1702 gate strings ---
  Iterative MLGST Total Time: 7.3s
WARNING: MLGST failed to improve logl: retaining chi2-objective estimate
  --- Re-optimizing logl after robust data scaling ---
  -- Performing 'single' gauge optimization on CPTP estimate --
  -- Performing 'single' gauge optimization on CPTP.Robust+ estimate --
-- Std Practice:  Iter 3 of 3  (Target) --: 
  --- Gate Sequence Creation ---
  -- Performing 'single' gauge optimization on Target estimate --
*** Creating workspace ***
*** Generating switchboard ***
Found standard clifford compilation from std1Q_XYI
Found standard clifford compilation from std1Q_XYI
Found standard clifford compilation from std1Q_XYI
*** Generating tables ***
  targetSpamBriefTable                          took 0.024079 seconds
  targetGatesBoxTable                           took 0.049723 seconds
  datasetOverviewTable                          took 0.039473 seconds
  bestGatesetSpamParametersTable                took 0.001409 seconds
  bestGatesetSpamBriefTable                     took 0.055416 seconds
  bestGatesetSpamVsTargetTable                  took 0.128986 seconds
  bestGatesetGaugeOptParamsTable                took 0.000854 seconds
  bestGatesetGatesBoxTable                      took 0.060875 seconds
  bestGatesetChoiEvalTable                      took 0.093545 seconds
  bestGatesetDecompTable                        took 0.10065 seconds
  bestGatesetEvalTable                          took 0.006569 seconds
  bestGermsEvalTable                            took 0.034415 seconds
  bestGatesetVsTargetTable                      took 0.684849 seconds
  bestGatesVsTargetTable_gv                     took 0.250023 seconds
  bestGatesVsTargetTable_gvgerms                took 0.12361 seconds
  bestGatesVsTargetTable_gi                     took 0.024128 seconds
  bestGatesVsTargetTable_gigerms                took 0.041821 seconds
  bestGatesVsTargetTable_sum                    took 0.258897 seconds
  bestGatesetErrGenBoxTable                     took 0.287524 seconds
  metadataTable                                 took 0.058242 seconds
  stdoutBlock                                   took 0.000254 seconds
  profilerTable                                 took 0.051182 seconds
  softwareEnvTable                              took 0.040222 seconds
  exampleTable                                  took 0.008485 seconds
  singleMetricTable_gv                          took 0.262942 seconds
  singleMetricTable_gi                          took 0.027719 seconds
  fiducialListTable                             took 0.000513 seconds
  prepStrListTable                              took 0.000213 seconds
  effectStrListTable                            took 0.000173 seconds
  colorBoxPlotKeyPlot                           took 0.008731 seconds
  germList2ColTable                             took 0.000237 seconds
  progressTable                                 took 5.194163 seconds
*** Generating plots ***
  gramBarPlot                                   took 0.07588 seconds
  progressBarPlot                               took 0.494943 seconds
  progressBarPlot_sum                           took 0.000721 seconds
  finalFitComparePlot                           took 0.124227 seconds
  bestEstimateColorBoxPlot                      took 53.459833 seconds
  bestEstimateTVDColorBoxPlot                   took 75.98059 seconds
  bestEstimateColorScatterPlot                  took 67.750746 seconds
  bestEstimateColorHistogram                    took 44.380899 seconds
  progressTable_scl                             took 7.325267 seconds
  progressBarPlot_scl                           took 0.456446 seconds
  bestEstimateColorBoxPlot_scl                  took 26.304752 seconds
  bestEstimateColorScatterPlot_scl              took 29.553466 seconds
  bestEstimateColorHistogram_scl                took 24.489201 seconds
  dataScalingColorBoxPlot                       took 0.20727 seconds
*** Merging into template file ***
  Rendering dataScalingColorBoxPlot             took 0.031526 seconds
  Rendering targetGatesBoxTable                 took 0.04459 seconds
  Rendering bestEstimateColorScatterPlot_scl    took 0.077408 seconds
  Rendering bestGatesetGaugeOptParamsTable      took 0.002586 seconds
  Rendering progressBarPlot_sum                 took 0.00886 seconds
  Rendering exampleTable                        took 0.00435 seconds
  Rendering metricSwitchboard_gi                took 5.9e-05 seconds
  Rendering bestGatesVsTargetTable_gvgerms      took 0.01121 seconds
  Rendering progressTable_scl                   took 0.009098 seconds
  Rendering bestGatesetEvalTable                took 0.047385 seconds
  Rendering progressBarPlot_scl                 took 0.004798 seconds
  Rendering topSwitchboard                      took 0.000179 seconds
  Rendering fiducialListTable                   took 0.003567 seconds
  Rendering finalFitComparePlot                 took 0.003468 seconds
  Rendering singleMetricTable_gv                took 0.010852 seconds
  Rendering bestGatesetVsTargetTable            took 0.002282 seconds
  Rendering progressTable                       took 0.013737 seconds
  Rendering bestEstimateColorHistogram_scl      took 0.061162 seconds
  Rendering progressBarPlot                     took 0.009722 seconds
  Rendering targetSpamBriefTable                took 0.046351 seconds
  Rendering bestEstimateTVDColorBoxPlot         took 0.169958 seconds
  Rendering bestEstimateColorBoxPlot            took 0.149958 seconds
  Rendering singleMetricTable_gi                took 0.008114 seconds
  Rendering prepStrListTable                    took 0.002203 seconds
  Rendering datasetOverviewTable                took 0.000727 seconds
  Rendering gramBarPlot                         took 0.009352 seconds
  Rendering bestEstimateColorHistogram          took 0.097909 seconds
  Rendering bestGatesetErrGenBoxTable           took 0.165587 seconds
  Rendering bestGatesVsTargetTable_gv           took 0.007542 seconds
  Rendering metadataTable                       took 0.00877 seconds
  Rendering bestGatesetSpamVsTargetTable        took 0.005208 seconds
  Rendering bestGatesVsTargetTable_gigerms      took 0.013734 seconds
  Rendering bestGermsEvalTable                  took 0.17799 seconds
  Rendering profilerTable                       took 0.003852 seconds
  Rendering colorBoxPlotKeyPlot                 took 0.008674 seconds
  Rendering bestGatesetSpamParametersTable      took 0.004761 seconds
  Rendering softwareEnvTable                    took 0.003435 seconds
  Rendering metricSwitchboard_gv                took 6.6e-05 seconds
  Rendering bestGatesetChoiEvalTable            took 0.054143 seconds
  Rendering bestGatesetSpamBriefTable           took 0.087761 seconds
  Rendering bestEstimateColorScatterPlot        took 0.125594 seconds
  Rendering bestGatesVsTargetTable_gi           took 0.012523 seconds
  Rendering bestEstimateColorBoxPlot_scl        took 0.120259 seconds
  Rendering bestGatesetDecompTable              took 0.069713 seconds
  Rendering bestGatesetGatesBoxTable            took 0.104572 seconds
  Rendering effectStrListTable                  took 0.002777 seconds
  Rendering maxLSwitchboard1                    took 0.000195 seconds
  Rendering bestGatesVsTargetTable_sum          took 0.011025 seconds
  Rendering stdoutBlock                         took 0.0017 seconds
  Rendering germList2ColTable                   took 0.003185 seconds
Output written to tutorial_files/gettingStartedReport directory
*** Report Generation Complete!  Total time 340.85s ***
< at 0x10de97e10>

You can now open the file tutorial_files/gettingStartedReport/main.html in your browser to view the report. That's it! You've just run GST!

The other tutorials in this directory will explain how to use the various objects and algorithms that comprise pyGSTi. These tutorial notebooks are meant to be fairly pedagogical and include details about the inner workings of and design choices within pyGSTi. In contrast, the "FAQ" directory contains notebooks with attempt to address specific questions as quickly and directly as possible, with little or no explanation of related topics or broader context.

In [ ]: