The pygsti
package provides multiple levels of abstraction over the core Gate Set Tomography (GST) algorithms. This initial tutorial will show you how to work with pygsti
's highest level of abstraction to get you started using GST quickly. Subsequent tutorials will delve into the details of pygsti
objects and algorithms, and how to use them in detail.
do_long_sequence_gst
driver function¶Let's first look at how to use the do_long_sequence_gst
which combines all the steps of running typical GST algortithms into a single function.
#Import the pygsti module (always do this)
import pygsti
Gate sets and other pygsti
objects are constructed using routines within pygsti.construction
, and so we construct a gateset by calling pygsti.construction.build_gateset
:
#Construct a target gateset
gs_target = pygsti.construction.build_gateset([2],[('Q0',)], ['Gi','Gx','Gy'],
[ "I(Q0)","X(pi/2,Q0)", "Y(pi/2,Q0)"],
prepLabels=['rho0'], prepExpressions=["0"],
effectLabels=['E0'], effectExpressions=["1"],
spamdefs={'plus': ('rho0','E0'), 'minus': ('rho0','remainder') } )
The parameters to build_gateset
, specify:
plus
minus
Reading from and writing to files is done mostly via routines in pygsti.io
. To store this gateset in a file (for reference or to load it somewhere else), you just call pygsti.io.write_gateset
:
#Write it to a file
pygsti.io.write_gateset(gs_target, "tutorial_files/MyTargetGateset.txt")
#To load the gateset back into a python object, do:
# gs_target = pygsti.io.load_gateset("tutorial_files/MyTargetGateset.txt")
These three lists will specify what experiments GST will use in its estimation procedure, and depend on the target gateset as well as the expected quality of the qubit being measured. They are:
fiducials
): gate sequences that immediately follow state preparation or immediately precede measurement.germs
): gate sequences that are repeated to produce a string that is as close to some "maximum length" as possible without exceeding it.maxLengths
): a list of maximum lengths used to specify the increasingly long gate sequences (via more germ repeats) used by each iteration of the GST estimation procedure.To make GST most effective, these gate strings lists should be computed. Typically this computation is done by the Sandia GST folks and the gate string lists are sent to you, though there is preliminary support within pygsti
for computing these string lists directly. Here, we'll assume we have been given the lists. The maximum lengths list typically starts with [0,1] and then contains successive powers of two. The largest maximum length should roughly correspond to the number of gates ones qubit can perform before becoming depolarized beyond ones ability to measure anything other than the maximally mixed state. Since we're constructing gate string lists, the routines used are in pygsti.construction
:
#Create fiducial gate string lists
fiducials = pygsti.construction.gatestring_list( [ (), ('Gx',), ('Gy',), ('Gx','Gx'), ('Gx','Gx','Gx'), ('Gy','Gy','Gy') ])
#Create germ gate string lists
germs = pygsti.construction.gatestring_list( [('Gx',), ('Gy',), ('Gi',), ('Gx', 'Gy',),
('Gx', 'Gy', 'Gi',), ('Gx', 'Gi', 'Gy',), ('Gx', 'Gi', 'Gi',), ('Gy', 'Gi', 'Gi',),
('Gx', 'Gx', 'Gi', 'Gy',), ('Gx', 'Gy', 'Gy', 'Gi',),
('Gx', 'Gx', 'Gy', 'Gx', 'Gy', 'Gy',)] )
#Create maximum lengths list
maxLengths = [0,1,2,4,8,16,32]
If we want to, we can save these lists in files (but this is not necessary):
pygsti.io.write_gatestring_list("tutorial_files/MyFiducials.txt", fiducials, "My fiducial gate strings")
pygsti.io.write_gatestring_list("tutorial_files/MyGerms.txt", germs, "My germ gate strings")
import pickle
pickle.dump( maxLengths, open("tutorial_files/MyMaxLengths.pkl", "wb"))
# To load these back into python lists, do:
#fiducials = pygsti.io.load_gatestring_list("tutorial_files/MyFiducials.txt")
#germs = pygsti.io.load_gatestring_list("tutorial_files/MyGerms.txt")
#maxLengths = pickle.load( open("tutorial_files/MyMaxLengths.pkl"))
Before experimental data is obtained, it is useful to create a "template" dataset file which specifies which gate sequences are required to run GST. Since we don't actually have an experiment for this example, we'll generate some "fake" experimental data from a set of gates that are just depolarized versions of the targets. First we construct the list of experiments used by GST using make_lsgst_experiment_list
, and use the result to specify which experiments to simulate. The abbreviation "LSGST" (lowercase in function names to follow Python naming conventions) stands for "Long Sequence Gate Set Tomography", and refers to the more powerful flavor of GST that utilizes long sequences to find gate set estimates. LSGST can be compared to Linear GST, or "LGST", which only uses short sequences and as a result provides much less accurate estimates.
#Create a list of GST experiments for this gateset, with
#the specified fiducials, germs, and maximum lengths
listOfExperiments = pygsti.construction.make_lsgst_experiment_list(gs_target.gates.keys(), fiducials, fiducials, germs, maxLengths)
#Create an empty dataset file, which stores the list of experiments
#plus extra columns where data can be inserted
pygsti.io.write_empty_dataset("tutorial_files/MyDataTemplate.txt", listOfExperiments,
"## Columns = plus count, count total")
Since we don't actually have a experiment to generate real data, let's now create and save a dataset using depolarized target gates and spam operations:
#Create a gateset of depolarized gates and SPAM relative to target, and generate fake data using this gateset.
gs_datagen = gs_target.depolarize(gate_noise=0.1, spam_noise=0.001)
ds = pygsti.construction.generate_fake_data(gs_datagen, listOfExperiments, nSamples=1000000,
sampleError="binomial", seed=2015)
We could at this point just use the generated dataset directly, but let's save it as though it were a file filled with experimental results.
#Save our dataset
pygsti.io.write_dataset("tutorial_files/MyDataset.txt", ds)
#Note; to load the dataset back again, do:
#ds = pygsti.io.load_dataset("tutorial_files/MyDataset.txt")
Now we're all set to call the driver routine. All of the possible arguments to this function are detailed in the included help (docstring), and so here we just make a few remarks:
fiducials
is supplied twice since the state preparation fiducials (those sequences following a state prep) need not be the same as the measurement fiducials (those sequences preceding a measurement).constrainToTP
set to True
(the default).gaugeOptRatio
specifies the ratio of the state preparation and measurement (SPAM) weight to the gate weight when performing a gauge optimization. When this is set to 0.001, as below, the gate parameters are weighted 1000 times more relative to the SPAM parameters. Typically it is good to weight the gates parameters more heavily since GST amplifies gate parameter errors via long gate sequences but cannot amplify SPAM parameter errors. If unsure, 0.001 is a good value to start with.results = pygsti.do_long_sequence_gst("tutorial_files/MyDataset.txt", gs_target,
fiducials, fiducials, germs, maxLengths,
gaugeOptRatio=1e-3, constrainToTP=True)
import pickle
s = pickle.dumps(results)
r2 = pickle.loads(s)
print r2.gatesets['final estimate']
The analysis routine returns a pygsti.report.Results
object which encapsulates intermediate and final GST estimates, as well as quantities derived from these "raw" estimates. (The object also caches derived quantities so that repeated queries for the same quanties do not require recalculation.) Finally, a Results
object can generate reports and presentations containing many of the raw and derived GST results. We give examples of these uses below.
# Access to raw GST best gateset estimate
print results.gatesets['final estimate']
#create a full GST report (most detailed and pedagogical; best for those getting familiar with GST)
results.create_full_report_pdf(confidenceLevel=95, filename="tutorial_files/easy_full.pdf", verbosity=2)
#create a brief GST report (just highlights of full report but fast to generate; best for folks familiar with GST)
results.create_brief_report_pdf(confidenceLevel=95, filename="tutorial_files/easy_brief.pdf", verbosity=2)
#create GST slides (tables and figures of full report in latex-generated slides; best for folks familiar with GST)
results.create_presentation_pdf(confidenceLevel=95, filename="tutorial_files/easy_slides.pdf", verbosity=2)
#create GST slides (tables and figures of full report in Powerpoint slides; best for folks familiar with GST)
results.create_presentation_ppt(confidenceLevel=95, filename="tutorial_files/easy_slides.pptx", verbosity=2)
If all has gone well, the above lines have produced the four primary types of reports pygsti
is capable of generating:
beamer
) slides, and is best for folks familiar with GST who want to show other people their great results.A significant component of running GST as show above is constructing things: the target gateset, the fiducial, germ, and maximum-length lists, etc. We've found that many people who use GST have one of only a few different target gatesets, and for these commonly used target gatesets we've created modules that perform most of the constructions for you. If you gateset isn't one of these standard ones then you'll have to follow the above approach for now, but please let us know and we'll try to add a module for your gateset in the future.
The standard construction modules are located under pygsti.construction
(surprise, surprise) and are prefixed with "std
". In the example above, our gateset (comprised of single qubit $I$, X($\pi/2$), and Y($\pi/2$) gates) is one of the commonly used gatesets, and relevant constructions are importable via:
#Import the "stardard 1-qubit quantities for a gateset with X(pi/2), Y(pi/2), and idle gates"
from pygsti.construction import std1Q_XYI
We follow the same order of constructing things as above, but it's much easier since almost everything has been constructed already:
gs_target = std1Q_XYI.gs_target
fiducials = std1Q_XYI.fiducials
germs = std1Q_XYI.germs
maxLengths = [0,1,2,4,8,16,32] #still need to define this manually
We generate a fake dataset as before:
gs_datagen = gs_target.depolarize(gate_noise=0.1, spam_noise=0.001)
listOfExperiments = pygsti.construction.make_lsgst_experiment_list(gs_target.gates.keys(), fiducials, fiducials, germs, maxLengths)
ds = pygsti.construction.generate_fake_data(gs_datagen, listOfExperiments, nSamples=1000000,
sampleError="binomial", seed=1234)
And run the analysis function (this time using the dataset object directly instead of loading from a file), and then create a report in the specified file.
results = pygsti.do_long_sequence_gst(ds, gs_target, fiducials, fiducials, germs, maxLengths)
results.create_full_report_pdf(confidenceLevel=95,filename="tutorial_files/MyEvenEasierReport.pdf",verbosity=2)
Now open tutorial_files/MyEvenEasierReport.pdf to see the results. You've just run GST (again)!
# Printing a Results object gives you information about how to extract information from it
print results