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: 8.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: 9.9s
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.029784 seconds
  targetGatesBoxTable                           took 0.073533 seconds
  datasetOverviewTable                          took 0.067227 seconds
  bestGatesetSpamParametersTable                took 0.001424 seconds
  bestGatesetSpamBriefTable                     took 0.078665 seconds
  bestGatesetSpamVsTargetTable                  took 0.600843 seconds
  bestGatesetGaugeOptParamsTable                took 0.001099 seconds
  bestGatesetGatesBoxTable                      took 0.099083 seconds
  bestGatesetChoiEvalTable                      took 0.13824 seconds
  bestGatesetDecompTable                        took 0.126771 seconds
  bestGatesetEvalTable                          took 0.01089 seconds
  bestGermsEvalTable                            took 0.046017 seconds
  bestGatesetVsTargetTable                      took 1.00876 seconds
  bestGatesVsTargetTable_gv                     took 1.750243 seconds
  bestGatesVsTargetTable_gvgerms                took 0.265853 seconds
  bestGatesVsTargetTable_gi                     took 0.040023 seconds
  bestGatesVsTargetTable_gigerms                took 0.078355 seconds
  bestGatesVsTargetTable_sum                    took 1.75444 seconds
  bestGatesetErrGenBoxTable                     took 0.346165 seconds
  metadataTable                                 took 0.076896 seconds
  stdoutBlock                                   took 0.000291 seconds
  profilerTable                                 took 0.001549 seconds
  softwareEnvTable                              took 0.014964 seconds
  exampleTable                                  took 0.01149 seconds
  singleMetricTable_gv                          took 1.743935 seconds
  singleMetricTable_gi                          took 0.041049 seconds
  fiducialListTable                             took 0.000722 seconds
  prepStrListTable                              took 0.000168 seconds
  effectStrListTable                            took 0.000159 seconds
  colorBoxPlotKeyPlot                           took 0.010593 seconds
  germList2ColTable                             took 0.000259 seconds
  progressTable                                 took 7.121575 seconds
*** Generating plots ***
  gramBarPlot                                   took 0.08473 seconds
  progressBarPlot                               took 0.792423 seconds
  progressBarPlot_sum                           took 0.001194 seconds
  finalFitComparePlot                           took 0.195339 seconds
  bestEstimateColorBoxPlot                      took 36.530809 seconds
  bestEstimateTVDColorBoxPlot                   took 36.321816 seconds
  bestEstimateColorScatterPlot                  took 42.492365 seconds
  bestEstimateColorHistogram                    took 35.946169 seconds
  progressTable_scl                             took 6.923695 seconds
  progressBarPlot_scl                           took 0.522607 seconds
  bestEstimateColorBoxPlot_scl                  took 24.227339 seconds
  bestEstimateColorScatterPlot_scl              took 28.239644 seconds
  bestEstimateColorHistogram_scl                took 24.613683 seconds
  dataScalingColorBoxPlot                       took 0.198145 seconds
*** Merging into template file ***
  Rendering topSwitchboard                      took 0.000246 seconds
  Rendering maxLSwitchboard1                    took 0.000136 seconds
  Rendering targetSpamBriefTable                took 0.040771 seconds
  Rendering targetGatesBoxTable                 took 0.03743 seconds
  Rendering datasetOverviewTable                took 0.000966 seconds
  Rendering bestGatesetSpamParametersTable      took 0.003958 seconds
  Rendering bestGatesetSpamBriefTable           took 0.073358 seconds
  Rendering bestGatesetSpamVsTargetTable        took 0.00688 seconds
  Rendering bestGatesetGaugeOptParamsTable      took 0.002755 seconds
  Rendering bestGatesetGatesBoxTable            took 0.072141 seconds
  Rendering bestGatesetChoiEvalTable            took 0.054203 seconds
  Rendering bestGatesetDecompTable              took 0.04594 seconds
  Rendering bestGatesetEvalTable                took 0.052549 seconds
  Rendering bestGermsEvalTable                  took 0.179015 seconds
  Rendering bestGatesetVsTargetTable            took 0.002305 seconds
  Rendering bestGatesVsTargetTable_gv           took 0.011405 seconds
  Rendering bestGatesVsTargetTable_gvgerms      took 0.024074 seconds
  Rendering bestGatesVsTargetTable_gi           took 0.008997 seconds
  Rendering bestGatesVsTargetTable_gigerms      took 0.012173 seconds
  Rendering bestGatesVsTargetTable_sum          took 0.009914 seconds
  Rendering bestGatesetErrGenBoxTable           took 0.134905 seconds
  Rendering metadataTable                       took 0.008872 seconds
  Rendering stdoutBlock                         took 0.001558 seconds
  Rendering profilerTable                       took 0.004032 seconds
  Rendering softwareEnvTable                    took 0.003016 seconds
  Rendering exampleTable                        took 0.006037 seconds
  Rendering metricSwitchboard_gv                took 9e-05 seconds
  Rendering metricSwitchboard_gi                took 6.1e-05 seconds
  Rendering singleMetricTable_gv                took 0.013462 seconds
  Rendering singleMetricTable_gi                took 0.00785 seconds
  Rendering fiducialListTable                   took 0.002778 seconds
  Rendering prepStrListTable                    took 0.002255 seconds
  Rendering effectStrListTable                  took 0.002011 seconds
  Rendering colorBoxPlotKeyPlot                 took 0.006833 seconds
  Rendering germList2ColTable                   took 0.003413 seconds
  Rendering progressTable                       took 0.016861 seconds
  Rendering gramBarPlot                         took 0.006237 seconds
  Rendering progressBarPlot                     took 0.005492 seconds
  Rendering progressBarPlot_sum                 took 0.005855 seconds
  Rendering finalFitComparePlot                 took 0.002357 seconds
  Rendering bestEstimateColorBoxPlot            took 0.146263 seconds
  Rendering bestEstimateTVDColorBoxPlot         took 0.136855 seconds
  Rendering bestEstimateColorScatterPlot        took 0.112607 seconds
  Rendering bestEstimateColorHistogram          took 0.08189 seconds
  Rendering progressTable_scl                   took 0.013337 seconds
  Rendering progressBarPlot_scl                 took 0.005941 seconds
  Rendering bestEstimateColorBoxPlot_scl        took 0.089555 seconds
  Rendering bestEstimateColorScatterPlot_scl    took 0.072658 seconds
  Rendering bestEstimateColorHistogram_scl      took 0.060206 seconds
  Rendering dataScalingColorBoxPlot             took 0.024509 seconds
Output written to tutorial_files/gettingStartedReport directory
*** Report Generation Complete!  Total time 254.7s ***
< at 0x10c174978>

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 [ ]: