pygsti.drivers
pyGSTi HighLevel Drivers Python Package
Submodules
Package Contents
Classes
A calculator of circuit outcome probability calculations and their derivatives w.r.t. model parameters. 
Functions

Creates a DataSet used for generating bootstrapped error bars. 

Creates a series of "bootstrapped" Models. 

Optimizes the "spam weight" parameter used when gauge optimizing a set of models. 



Compares a 

Perform Linear Gate Set Tomography (LGST). 

Perform longsequence GST (LSGST). 

A more fundamental interface for performing endtoend GST. 

Perform endtoend GST analysis using standard practices. 
Attributes
 pygsti.drivers.create_bootstrap_dataset(input_data_set, generation_method, input_model=None, seed=None, outcome_labels=None, verbosity=1)
Creates a DataSet used for generating bootstrapped error bars.
Parameters
 input_data_setDataSet
The data set to use for generating the “bootstrapped” data set.
 generation_method{ ‘nonparametric’, ‘parametric’ }
The type of dataset to generate. ‘parametric’ generates a DataSet with the same circuits and sample counts as input_data_set but using the probabilities in input_model (which must be provided). ‘nonparametric’ generates a DataSet with the same circuits and sample counts as input_data_set using the count frequencies of input_data_set as probabilities.
 input_modelModel, optional
The model used to compute the probabilities for circuits when generation_method is set to ‘parametric’. If ‘nonparametric’ is selected, this argument must be set to None (the default).
 seedint, optional
A seed value for numpy’s random number generator.
 outcome_labelslist, optional
The list of outcome labels to include in the output dataset. If None are specified, defaults to the spam labels of input_data_set.
 verbosityint, optional
How verbose the function output is. If 0, then printing is suppressed. If 1 (or greater), then printing is not suppressed.
Returns
DataSet
 pygsti.drivers.create_bootstrap_models(num_models, input_data_set, generation_method, fiducial_prep, fiducial_measure, germs, max_lengths, input_model=None, target_model=None, start_seed=0, outcome_labels=None, lsgst_lists=None, return_data=False, verbosity=2)
Creates a series of “bootstrapped” Models.
Models are created from a single DataSet (and possibly Model) and are typically used for generating bootstrapped error bars. The resulting Models are obtained by performing MLGST on data generated by repeatedly calling
create_bootstrap_dataset()
with consecutive integer seed values.Parameters
 num_modelsint
The number of models to create.
 input_data_setDataSet
The data set to use for generating the “bootstrapped” data set.
 generation_method{ ‘nonparametric’, ‘parametric’ }
The type of data to generate. ‘parametric’ generates DataSets with the same circuits and sample counts as input_data_set but using the probabilities in input_model (which must be provided). ‘nonparametric’ generates DataSets with the same circuits and sample counts as input_data_set using the count frequencies of input_data_set as probabilities.
 fiducial_preplist of Circuits
The state preparation fiducial circuits used by MLGST.
 fiducial_measurelist of Circuits
The measurement fiducial circuits used by MLGST.
 germslist of Circuits
The germ circuits used by MLGST.
 max_lengthslist of ints
List of integers, one per MLGST iteration, which set truncation lengths for repeated germ strings. The list of circuits for the ith LSGST iteration includes the repeated germs truncated to the Lvalues up to and including the ith one.
 input_modelModel, optional
The model used to compute the probabilities for circuits when generation_method is set to ‘parametric’. If ‘nonparametric’ is selected, this argument must be set to None (the default).
 target_modelModel, optional
Mandatory model to use for as the target model for MLGST when generation_method is set to ‘nonparametric’. When ‘parametric’ is selected, this should be the ideal version of input_model.
 start_seedint, optional
The initial seed value for numpy’s random number generator when generating data sets. For each succesive dataset (and model) that are generated, the seed is incremented by one.
 outcome_labelslist, optional
The list of Outcome labels to include in the output dataset. If None are specified, defaults to the effect labels of input_data_set.
 lsgst_listslist of circuit lists, optional
Provides explicit list of circuit lists to be used in analysis; to be given if the dataset uses “incomplete” or “reduced” sets of circuit. Default is None.
 return_databool
Whether generated data sets should be returned in addition to models.
 verbosityint
Level of detail printed to stdout.
Returns
 modelslist
The list of generated Model objects.
 datalist
The list of generated DataSet objects, only returned when return_data == True.
 pygsti.drivers.gauge_optimize_models(gs_list, target_model, gate_metric='frobenius', spam_metric='frobenius', plot=True)
Optimizes the “spam weight” parameter used when gauge optimizing a set of models.
This function gauge optimizes multiple times using a range of spam weights and takes the one the minimizes the average spam error multiplied by the average gate error (with respect to a target model).
Parameters
 gs_listlist
The list of Model objects to gauge optimize (simultaneously).
 target_modelModel
The model to compare the gaugeoptimized gates with, and also to gaugeoptimize them to.
 gate_metric{ “frobenius”, “fidelity”, “tracedist” }, optional
The metric used within the gauge optimization to determing error in the gates.
 spam_metric{ “frobenius”, “fidelity”, “tracedist” }, optional
The metric used within the gauge optimization to determing error in the state preparation and measurement.
 plotbool, optional
Whether to create a plot of the modeltarget discrepancy as a function of spam weight (figure displayed interactively).
Returns
 list
The list of Models gaugeoptimized using the best spamWeight.
 pygsti.drivers.create_explicit_model(processor_spec, custom_gates=None, depolarization_strengths=None, stochastic_error_probs=None, lindblad_error_coeffs=None, depolarization_parameterization='depolarize', stochastic_parameterization='stochastic', lindblad_parameterization='auto', evotype='default', simulator='auto', ideal_gate_type='auto', ideal_spam_type='computational', embed_gates=False, basis='pp')
 class pygsti.drivers.ForwardSimulator(model=None)
Bases:
pygsti.baseobjs.nicelyserializable.NicelySerializable
A calculator of circuit outcome probability calculations and their derivatives w.r.t. model parameters.
Some forward simulators may also be used to perform operationproduct calculations.
This functionality exists in a class separate from Model to allow for additional model classes (e.g. ones which use entirely different – nongatelocal – parameterizations of operation matrices and SPAM vectors) access to these fundamental operations. It also allows for the easier addition of new forward simulators.
Note: a model holds or “contains” a forward simulator instance to perform its computations, and a forward simulator holds a reference to its parent model, so we need to make sure the forward simulator doesn’t serialize the model or we have a circular reference.
Parameters
 modelModel, optional
The model this forward simulator will use to compute circuit outcome probabilities.
 property model
 Castable
 classmethod cast(obj: ForwardSimulator, num_qubits=None)
num_qubits only used if obj == ‘auto’
 probs(circuit, outcomes=None, time=None, resource_alloc=None)
Construct a dictionary containing the outcome probabilities for a single circuit.
Parameters
 circuitCircuit or tuple of operation labels
The sequence of operation labels specifying the circuit.
 outcomeslist or tuple
A sequence of outcomes, which can themselves be either tuples (to include intermediate measurements) or simple strings, e.g. ‘010’. If None, only nonzero outcome probabilities will be reported.
 timefloat, optional
The start time at which circuit is evaluated.
 resource_allocResourceAllocation, optional
The resources available for computing circuit outcome probabilities.
Returns
 probsOutcomeLabelDict
A dictionary with keys equal to outcome labels and values equal to probabilities. If no target outcomes provided, only nonzero probabilities will be reported.
 dprobs(circuit, resource_alloc=None)
Construct a dictionary containing outcome probability derivatives for a single circuit.
Parameters
 circuitCircuit or tuple of operation labels
The sequence of operation labels specifying the circuit.
 resource_allocResourceAllocation, optional
The resources available for computing circuit outcome probability derivatives.
Returns
 dprobsOutcomeLabelDict
A dictionary with keys equal to outcome labels and values equal to an array containing the (partial) derivatives of the outcome probability with respect to all model parameters.
 hprobs(circuit, resource_alloc=None)
Construct a dictionary containing outcome probability Hessians for a single circuit.
Parameters
 circuitCircuit or tuple of operation labels
The sequence of operation labels specifying the circuit.
 resource_allocResourceAllocation, optional
The resources available for computing circuit outcome probability Hessians.
Returns
 hprobsOutcomeLabelDict
A dictionary with keys equal to outcome labels and values equal to a 2D array that is the Hessian matrix for the corresponding outcome probability (with respect to all model parameters).
 create_layout(circuits, dataset=None, resource_alloc=None, array_types=(), derivative_dimensions=None, verbosity=0)
Constructs an circuitoutcomeprobabilityarray (COPA) layout for circuits and dataset.
Parameters
 circuitslist
The circuits whose outcome probabilities should be computed.
 datasetDataSet
The source of data counts that will be compared to the circuit outcome probabilities. The computed outcome probabilities are limited to those with counts present in dataset.
 resource_allocResourceAllocation
A available resources and allocation information. These factors influence how the layout (evaluation strategy) is constructed.
 array_typestuple, optional
A tuple of stringvalued array types, as given by
CircuitOutcomeProbabilityArrayLayout.allocate_local_array()
. These types determine what types of arrays we anticipate computing using this layout (and forward simulator). These are used to check available memory against the limit (if it exists) within resource_alloc. The array types also determine the number of derivatives that this layout is able to compute. So, for example, if you ever want to compute derivatives or Hessians of element arrays then array_types must contain at least one ‘ep’ or ‘epp’ type, respectively or the layout will not allocate needed intermediate storage for derivativecontaining types. If you don’t care about accurate memory limits, use (‘e’,) when you only ever compute probabilities and never their derivatives, and (‘e’,’ep’) or (‘e’,’ep’,’epp’) if you need to compute Jacobians or Hessians too. derivative_dimensionstuple, optional
A tuple containing, optionally, the parameterspace dimension used when taking first and second derivatives with respect to the cirucit outcome probabilities. This should have minimally 1 or 2 elements when array_types contains ‘ep’ or ‘epp’ types, respectively. If array_types contains either of these strings and derivative_dimensions is None on input then we automatically set derivative_dimensions based on self.model.
 verbosityint or VerbosityPrinter
Determines how much output to send to stdout. 0 means no output, higher integers mean more output.
Returns
CircuitOutcomeProbabilityArrayLayout
 bulk_probs(circuits, clip_to=None, resource_alloc=None, smartc=None)
Construct a dictionary containing the probabilities for an entire list of circuits.
Parameters
 circuitslist of Circuits
The list of circuits. May also be a
CircuitOutcomeProbabilityArrayLayout
object containing precomputed quantities that make this function run faster. clip_to2tuple, optional
(min,max) to clip return value if not None.
 resource_allocResourceAllocation, optional
A resource allocation object describing the available resources and a strategy for partitioning them.
 smartcSmartCache, optional
A cache object to cache & use previously cached values inside this function.
Returns
 probsdictionary
A dictionary such that probs[circuit] is an ordered dictionary of outcome probabilities whose keys are outcome labels.
 bulk_dprobs(circuits, resource_alloc=None, smartc=None)
Construct a dictionary containing the probability derivatives for an entire list of circuits.
Parameters
 circuitslist of Circuits
The list of circuits. May also be a
CircuitOutcomeProbabilityArrayLayout
object containing precomputed quantities that make this function run faster. resource_allocResourceAllocation, optional
A resource allocation object describing the available resources and a strategy for partitioning them.
 smartcSmartCache, optional
A cache object to cache & use previously cached values inside this function.
Returns
 dprobsdictionary
A dictionary such that dprobs[circuit] is an ordered dictionary of derivative arrays (one element per differentiated parameter) whose keys are outcome labels
 bulk_hprobs(circuits, resource_alloc=None, smartc=None)
Construct a dictionary containing the probability Hessians for an entire list of circuits.
Parameters
 circuitslist of Circuits
The list of circuits. May also be a
CircuitOutcomeProbabilityArrayLayout
object containing precomputed quantities that make this function run faster. resource_allocResourceAllocation, optional
A resource allocation object describing the available resources and a strategy for partitioning them.
 smartcSmartCache, optional
A cache object to cache & use previously cached values inside this function.
Returns
 hprobsdictionary
A dictionary such that hprobs[circuit] is an ordered dictionary of Hessian arrays (a square matrix with one row/column per differentiated parameter) whose keys are outcome labels
 bulk_fill_probs(array_to_fill, layout)
Compute the outcome probabilities for a list circuits.
This routine fills a 1D array, array_to_fill with circuit outcome probabilities as dictated by a
CircuitOutcomeProbabilityArrayLayout
(“COPA layout”) object, which is usually specifically tailored for efficiency.The array_to_fill array must have length equal to the number of elements in layout, and the meanings of each element are given by layout.
Parameters
 array_to_fillnumpy ndarray
an alreadyallocated 1D numpy array of length equal to the total number of computed elements (i.e. len(layout)).
 layoutCircuitOutcomeProbabilityArrayLayout
A layout for array_to_fill, describing what circuit outcome each element corresponds to. Usually given by a prior call to
create_layout()
.
Returns
None
 bulk_fill_dprobs(array_to_fill, layout, pr_array_to_fill=None)
Compute the outcome probabilityderivatives for an entire tree of circuits.
This routine fills a 2D array, array_to_fill with circuit outcome probabilities as dictated by a
CircuitOutcomeProbabilityArrayLayout
(“COPA layout”) object, which is usually specifically tailored for efficiency.The array_to_fill array must have length equal to the number of elements in layout, and the meanings of each element are given by layout.
Parameters
 array_to_fillnumpy ndarray
an alreadyallocated 2D numpy array of shape (len(layout), Np), where Np is the number of model parameters being differentiated with respect to.
 layoutCircuitOutcomeProbabilityArrayLayout
A layout for array_to_fill, describing what circuit outcome each element corresponds to. Usually given by a prior call to
create_layout()
. pr_mx_to_fillnumpy array, optional
when not None, an alreadyallocated lengthlen(layout) numpy array that is filled with probabilities, just as in
bulk_fill_probs()
.
Returns
None
 bulk_fill_hprobs(array_to_fill, layout, pr_array_to_fill=None, deriv1_array_to_fill=None, deriv2_array_to_fill=None)
Compute the outcome probabilityHessians for an entire list of circuits.
Similar to bulk_fill_probs(…), but fills a 3D array with the Hessians for each circuit outcome probability.
Parameters
 array_to_fillnumpy ndarray
an alreadyallocated numpy array of shape (len(layout),M1,M2) where M1 and M2 are the number of selected model parameters (by wrt_filter1 and wrt_filter2).
 layoutCircuitOutcomeProbabilityArrayLayout
A layout for array_to_fill, describing what circuit outcome each element corresponds to. Usually given by a prior call to
create_layout()
. pr_mx_to_fillnumpy array, optional
when not None, an alreadyallocated lengthlen(layout) numpy array that is filled with probabilities, just as in
bulk_fill_probs()
. deriv1_array_to_fillnumpy array, optional
when not None, an alreadyallocated numpy array of shape (len(layout),M1) that is filled with probability derivatives, similar to
bulk_fill_dprobs()
(see array_to_fill for a definition of M1). deriv2_array_to_fillnumpy array, optional
when not None, an alreadyallocated numpy array of shape (len(layout),M2) that is filled with probability derivatives, similar to
bulk_fill_dprobs()
(see array_to_fill for a definition of M2).
Returns
None
 iter_hprobs_by_rectangle(layout, wrt_slices_list, return_dprobs_12=False)
Iterates over the 2nd derivatives of a layout’s circuit probabilities one rectangle at a time.
This routine can be useful when memory constraints make constructing the entire Hessian at once impractical, and as it only computes a subset of the Hessian’s rows and colums (a “rectangle”) at once. For example, the Hessian of a function of many circuit probabilities can often be computed rectanglebyrectangle and without the need to ever store the entire Hessian at once.
Parameters
 layoutCircuitOutcomeProbabilityArrayLayout
A layout for generated arrays, describing what circuit outcome each element corresponds to. Usually given by a prior call to
create_layout()
. wrt_slices_listlist
A list of (rowSlice,colSlice) 2tuples, each of which specify a “rectangle” of the Hessian to compute. Iterating over the output of this function iterates over these computed rectangles, in the order given by wrt_slices_list. rowSlice and colSlice must by Python slice objects.
 return_dprobs_12boolean, optional
If true, the generator computes a 2tuple: (hessian_col, d12_col), where d12_col is a column of the matrix d12 defined by: d12[iSpamLabel,iOpStr,p1,p2] = dP/d(p1)*dP/d(p2) where P is is the probability generated by the sequence and spam label indexed by iOpStr and iSpamLabel. d12 has the same dimensions as the Hessian, and turns out to be useful when computing the Hessian of functions of the probabilities.
Returns
 rectangle_generator
A generator which, when iterated, yields the 3tuple (rowSlice, colSlice, hprobs) or (rowSlice, colSlice, hprobs, dprobs12) (the latter if return_dprobs_12 == True). rowSlice and colSlice are slices directly from wrt_slices_list. hprobs and dprobs12 are arrays of shape E x B x B’, where:
E is the length of layout elements
B is the number of parameter rows (the length of rowSlice)
B’ is the number of parameter columns (the length of colSlice)
If mx, dp1, and dp2 are the outputs of
bulk_fill_hprobs()
(i.e. args mx_to_fill, deriv1_mx_to_fill, and deriv2_mx_to_fill), then:hprobs == mx[:,rowSlice,colSlice]
dprobs12 == dp1[:,rowSlice,None] * dp2[:,None,colSlice]
 pygsti.drivers.ROBUST_SUFFIX_LIST = ['.robust', '.Robust', '.robust+', '.Robust+']
 pygsti.drivers.DEFAULT_BAD_FIT_THRESHOLD = 2.0
 pygsti.drivers.run_model_test(model_filename_or_object, data_filename_or_set, processorspec_filename_or_object, prep_fiducial_list_or_filename, meas_fiducial_list_or_filename, germs_list_or_filename, max_lengths, gauge_opt_params=None, advanced_options=None, comm=None, mem_limit=None, output_pkl=None, verbosity=2, checkpoint=None, checkpoint_path=None, disable_checkpointing=False, simulator: pygsti.forwardsims.ForwardSimulator.Castable  None = None)
Compares a
Model
’s predictions to a DataSet using GSTlike circuits.This routine tests a Model model against a DataSet using a specific set of structured, GSTlike circuits (given by fiducials, max_lengths and germs). In particular, circuits are constructed by repeating germ strings an integer number of times such that the length of the repeated germ is less than or equal to the maximum length set in max_lengths. Each string thus constructed is sandwiched between all pairs of (preparation, measurement) fiducial sequences.
model_filename_or_object is used directly (without any optimization) as the the model estimate at each maximumlength “iteration”. The model is given a trivial default_gauge_group so that it is not altered during any gauge optimization step.
A
ModelEstimateResults
object is returned, which encapsulates the model estimate and related parameters, and can be used with reportgeneration routines.Parameters
 model_filename_or_objectModel or string
The model model, specified either directly or by the filename of a model file (text format).
 data_filename_or_setDataSet or string
The data set object to use for the analysis, specified either directly or by the filename of a dataset file (assumed to be a pickled DataSet if extension is ‘pkl’ otherwise assumed to be in pyGSTi’s text format).
 processorspec_filename_or_objectProcessorSpec or string
A specification of the processor this model test is to be run on, given either directly or by the filename of a processorspec file (text format). The processor specification contains basic interfacelevel information about the processor being tested, e.g., its state space and available gates.
 prep_fiducial_list_or_filename(list of Circuits) or string
The state preparation fiducial circuits, specified either directly or by the filename of a circuit list file (text format).
 meas_fiducial_list_or_filename(list of Circuits) or string or None
The measurement fiducial circuits, specified either directly or by the filename of a circuit list file (text format). If
None
, then use the same strings as specified by prep_fiducial_list_or_filename. germs_list_or_filename(list of Circuits) or string
The germ circuits, specified either directly or by the filename of a circuit list file (text format).
 max_lengthslist of ints
List of integers, one per LSGST iteration, which set truncation lengths for repeated germ strings. The list of circuits for the ith LSGST iteration includes the repeated germs truncated to the Lvalues up to and including the ith one.
 gauge_opt_paramsdict, optional
A dictionary of arguments to
gaugeopt_to_target()
, specifying how the final gauge optimization should be performed. The keys and values of this dictionary may correspond to any of the arguments ofgaugeopt_to_target()
except for the first model argument, which is specified internally. The target_model argument, can be set, but is specified internally when it isn’t. If None, then the dictionary {‘item_weights’: {‘gates’:1.0, ‘spam’:0.001}} is used. If False, then then no gauge optimization is performed. advanced_optionsdict, optional
Specifies advanced options most of which deal with numerical details of the objective function or expertlevel functionality.
 commmpi4py.MPI.Comm, optional
When not
None
, an MPI communicator for distributing the computation across multiple processors. mem_limitint or None, optional
A rough memory limit in bytes which restricts the amount of memory used (per core when run on multiCPUs).
 output_pklstr or file, optional
If not None, a file(name) to pickle.dump the returned Results object to (only the rank 0 process performs the dump when comm is not None).
 verbosityint, optional
The ‘verbosity’ option is an integer specifying the level of detail printed to stdout during the calculation.
 checkpointModelTestCheckpoint, optional (default None)
If specified use a previously generated checkpoint object to restart or warm start this run part way through.
 checkpoint_pathstr, optional (default None)
A string for the path/name to use for writing intermediate checkpoint files to disk. Format is {path}/{name}, without inclusion of the json file extension. This {path}/{name} combination will have the latest completed iteration number appended to it before writing it to disk. If none, the value of {name} will be set to the name of the protocol being run.
 disable_checkpointingbool, optional (default False)
When set to True checkpoint objects will not be constructed and written to disk during the course of this protocol. It is strongly recommended that this be kept set to False without good reason to disable the checkpoints.
 simulatorForwardSimulator.Castable or None
 Ignored if None. If not None, then we call
fwdsim = ForwardSimulator.cast(simulator),
and we set the .sim attribute of every Model we encounter to fwdsim.
Returns
Results
 pygsti.drivers.run_linear_gst(data_filename_or_set, target_model_filename_or_object, prep_fiducial_list_or_filename, meas_fiducial_list_or_filename, gauge_opt_params=None, advanced_options=None, comm=None, mem_limit=None, output_pkl=None, verbosity=2)
Perform Linear Gate Set Tomography (LGST).
This function differs from the lower level
run_lgst()
function in that it may perform a postLGST gauge optimization and this routine returns aResults
object containing the LGST estimate.Overall, this is a highlevel driver routine which can be used similarly to
run_long_sequence_gst()
whereas run_lgst is a lowlevel routine used when building your own algorithms.Parameters
 data_filename_or_setDataSet or string
The data set object to use for the analysis, specified either directly or by the filename of a dataset file (assumed to be a pickled DataSet if extension is ‘pkl’ otherwise assumed to be in pyGSTi’s text format).
 target_model_filename_or_objectModel or string
The target model specifying the gates and SPAM elements that LGST is to be run on, given either directly or by the filename of a model file (text format).
 prep_fiducial_list_or_filename(list of Circuits) or string
The state preparation fiducial circuits, specified either directly or by the filename of a circuit list file (text format).
 meas_fiducial_list_or_filename(list of Circuits) or string or None
The measurement fiducial circuits, specified either directly or by the filename of a circuit list file (text format). If
None
, then use the same strings as specified by prep_fiducial_list_or_filename. gauge_opt_paramsdict, optional
A dictionary of arguments to
gaugeopt_to_target()
, specifying how the final gauge optimization should be performed. The keys and values of this dictionary may correspond to any of the arguments ofgaugeopt_to_target()
except for the first model argument, which is specified internally. The target_model argument, can be set, but is specified internally when it isn’t. If None, then the dictionary {‘item_weights’: {‘gates’:1.0, ‘spam’:0.001}} is used. If False, then then no gauge optimization is performed. advanced_optionsdict, optional
Specifies advanced options most of which deal with numerical details of the objective function or expertlevel functionality. See
run_long_sequence_gst()
. commmpi4py.MPI.Comm, optional
When not
None
, an MPI communicator for distributing the computation across multiple processors. In this LGST case, this is just the gauge optimization. mem_limitint or None, optional
A rough memory limit in bytes which restricts the amount of memory used (per core when run on multiCPUs).
 output_pklstr or file, optional
If not None, a file(name) to pickle.dump the returned Results object to (only the rank 0 process performs the dump when comm is not None).
 verbosityint, optional
The ‘verbosity’ option is an integer specifying the level of detail printed to stdout during the calculation.
Returns
Results
 pygsti.drivers.run_long_sequence_gst(data_filename_or_set, target_model_filename_or_object, prep_fiducial_list_or_filename, meas_fiducial_list_or_filename, germs_list_or_filename, max_lengths, gauge_opt_params=None, advanced_options=None, comm=None, mem_limit=None, output_pkl=None, verbosity=2, checkpoint=None, checkpoint_path=None, disable_checkpointing=False, simulator: pygsti.forwardsims.ForwardSimulator.Castable  None = None)
Perform longsequence GST (LSGST).
This analysis fits a model (target_model_filename_or_object) to data (data_filename_or_set) using the outcomes from periodic GST circuits constructed by repeating germ strings an integer number of times such that the length of the repeated germ is less than or equal to the maximum length set in max_lengths. When LGST is applicable (i.e. for explicit models with full or TP parameterizations), the LGST estimate of the gates is computed, gauge optimized, and used as a starting seed for the remaining optimizations.
LSGST iterates
len(max_lengths)
times, optimizing the chi2 using successively larger sets of circuits. On the ith iteration, the repeated germs sequences limited bymax_lengths[i]
are included in the growing set of circuits used by LSGST. The final iteration maximizes the loglikelihood.Once computed, the model estimates are optionally gauge optimized as directed by gauge_opt_params. A
ModelEstimateResults
object is returned, which encapsulates the input and outputs of this GST analysis, and can generate final enduser output such as reports and presentations.Parameters
 data_filename_or_setDataSet or string
The data set object to use for the analysis, specified either directly or by the filename of a dataset file (assumed to be a pickled DataSet if extension is ‘pkl’ otherwise assumed to be in pyGSTi’s text format).
 target_model_filename_or_objectModel or string
The target model, specified either directly or by the filename of a model file (text format).
 prep_fiducial_list_or_filename(list of Circuits) or string
The state preparation fiducial circuits, specified either directly or by the filename of a circuit list file (text format).
 meas_fiducial_list_or_filename(list of Circuits) or string or None
The measurement fiducial circuits, specified either directly or by the filename of a circuit list file (text format). If
None
, then use the same strings as specified by prep_fiducial_list_or_filename. germs_list_or_filename(list of Circuits) or string
The germ circuits, specified either directly or by the filename of a circuit list file (text format).
 max_lengthslist of ints
List of integers, one per LSGST iteration, which set truncation lengths for repeated germ strings. The list of circuits for the ith LSGST iteration includes the repeated germs truncated to the Lvalues up to and including the ith one.
 gauge_opt_paramsdict, optional
A dictionary of arguments to
gaugeopt_to_target()
, specifying how the final gauge optimization should be performed. The keys and values of this dictionary may correspond to any of the arguments ofgaugeopt_to_target()
except for the first model argument, which is specified internally. The target_model argument, can be set, but is specified internally when it isn’t. If None, then the dictionary {‘item_weights’: {‘gates’:1.0, ‘spam’:0.001}} is used. If False, then then no gauge optimization is performed. advanced_optionsdict, optional
Specifies advanced options most of which deal with numerical details of the objective function or expertlevel functionality. The allowed keys and values include:  objective = {‘chi2’, ‘logl’}  op_labels = list of strings  circuit_weights = dict or None  starting_point = “LGSTifpossible” (default), “LGST”, or “target”  depolarize_start = float (default == 0)  randomize_start = float (default == 0)  contract_start_to_cptp = True / False (default)  cptpPenaltyFactor = float (default = 0)  tolerance = float or dict w/’relx’,’relf’,’f’,’jac’,’maxdx’ keys  max_iterations = int  finitediff_iterations = int  min_prob_clip = float  min_prob_clip_for_weighting = float (default == 1e4)  prob_clip_interval = tuple (default == (1e6,1e6)  radius = float (default == 1e4)  use_freq_weighted_chi2 = True / False (default)  XX nested_circuit_lists = True (default) / False  XX include_lgst = True / False (default is True)  distribute_method = “default”, “circuits” or “deriv”  profile = int (default == 1)  check = True / False (default)  XX op_label_aliases = dict (default = None)  always_perform_mle = bool (default = False)  only_perform_mle = bool (default = False)  XX truncScheme = “whole germ powers” (default) or “truncated germ powers” or “length as exponent”  appendTo = Results (default = None)  estimateLabel = str (default = “default”)  XX missingDataAction = {‘drop’,’raise’} (default = ‘drop’)  XX string_manipulation_rules = list of (find,replace) tuples  germ_length_limits = dict of form {germ: maxlength}  record_output = bool (default = True)  timeDependent = bool (default = False)
 commmpi4py.MPI.Comm, optional
When not
None
, an MPI communicator for distributing the computation across multiple processors. mem_limitint or None, optional
A rough memory limit in bytes which restricts the amount of memory used (per core when run on multiCPUs).
 output_pklstr or file, optional
If not None, a file(name) to pickle.dump the returned Results object to (only the rank 0 process performs the dump when comm is not None).
 verbosityint, optional
The ‘verbosity’ option is an integer specifying the level of detail printed to stdout during the calculation.  0 – prints nothing  1 – shows progress bar for entire iterative GST  2 – show summary details about each individual iteration  3 – also shows outer iterations of LM algorithm  4 – also shows inner iterations of LM algorithm  5 – also shows detailed info from within jacobian and objective function calls.
 checkpointGateSetTomographyCheckpoint, optional (default None)
If specified use a previously generated checkpoint object to restart or warm start this run part way through.
 checkpoint_pathstr, optional (default None)
A string for the path/name to use for writing intermediate checkpoint files to disk. Format is {path}/{name}, without inclusion of the json file extension. This {path}/{name} combination will have the latest completed iteration number appended to it before writing it to disk. If none, the value of {name} will be set to the name of the protocol being run.
 disable_checkpointingbool, optional (default False)
When set to True checkpoint objects will not be constructed and written to disk during the course of this protocol. It is strongly recommended that this be kept set to False without good reason to disable the checkpoints.
 simulatorForwardSimulator.Castable or None
 Ignored if None. If not None, then we call
fwdsim = ForwardSimulator.cast(simulator),
and we set the .sim attribute of every Model we encounter to fwdsim.
Returns
Results
 pygsti.drivers.run_long_sequence_gst_base(data_filename_or_set, target_model_filename_or_object, lsgst_lists, gauge_opt_params=None, advanced_options=None, comm=None, mem_limit=None, output_pkl=None, verbosity=2, checkpoint=None, checkpoint_path=None, disable_checkpointing=False, simulator: pygsti.forwardsims.ForwardSimulator.Castable  None = None)
A more fundamental interface for performing endtoend GST.
Similar to
run_long_sequence_gst()
except this function takes lsgst_lists, a list of either raw circuit lists or ofPlaquetteGridCircuitStructure
objects to define which circuits are used on each GST iteration.Parameters
 data_filename_or_setDataSet or string
The data set object to use for the analysis, specified either directly or by the filename of a dataset file (assumed to be a pickled DataSet if extension is ‘pkl’ otherwise assumed to be in pyGSTi’s text format).
 target_model_filename_or_objectModel or string
The target model, specified either directly or by the filename of a model file (text format).
 lsgst_listslist of lists or PlaquetteGridCircuitStructure(s)
An explicit list of either the raw circuit lists to be used in the analysis or of
PlaquetteGridCircuitStructure
objects, which additionally contain the structure of a set of circuits. A single PlaquetteGridCircuitStructure object can also be given, which is equivalent to passing a list of successive Lvalue truncations of this object (e.g. if the object has Ls = [1,2,4] then this is like passing a list of three PlaquetteGridCircuitStructure objects w/truncations [1], [1,2], and [1,2,4]). gauge_opt_paramsdict, optional
A dictionary of arguments to
gaugeopt_to_target()
, specifying how the final gauge optimization should be performed. The keys and values of this dictionary may correspond to any of the arguments ofgaugeopt_to_target()
except for the first model argument, which is specified internally. The target_model argument, can be set, but is specified internally when it isn’t. If None, then the dictionary {‘item_weights’: {‘gates’:1.0, ‘spam’:0.001}} is used. If False, then then no gauge optimization is performed. advanced_optionsdict, optional
Specifies advanced options most of which deal with numerical details of the objective function or expertlevel functionality. See
run_long_sequence_gst()
for a list of the allowed keys, with the exception “nested_circuit_lists”, “op_label_aliases”, “include_lgst”, and “truncScheme”. commmpi4py.MPI.Comm, optional
When not
None
, an MPI communicator for distributing the computation across multiple processors. mem_limitint or None, optional
A rough memory limit in bytes which restricts the amount of memory used (per core when run on multiCPUs).
 output_pklstr or file, optional
If not None, a file(name) to pickle.dump the returned Results object to (only the rank 0 process performs the dump when comm is not None).
 verbosityint, optional
The ‘verbosity’ option is an integer specifying the level of detail printed to stdout during the calculation.  0 – prints nothing  1 – shows progress bar for entire iterative GST  2 – show summary details about each individual iteration  3 – also shows outer iterations of LM algorithm  4 – also shows inner iterations of LM algorithm  5 – also shows detailed info from within jacobian and objective function calls.
 checkpointGateSetTomographyCheckpoint, optional (default None)
If specified use a previously generated checkpoint object to restart or warm start this run part way through.
 checkpoint_pathstr, optional (default None)
A string for the path/name to use for writing intermediate checkpoint files to disk. Format is {path}/{name}, without inclusion of the json file extension. This {path}/{name} combination will have the latest completed iteration number appended to it before writing it to disk. If none, the value of {name} will be set to the name of the protocol being run.
 disable_checkpointingbool, optional (default False)
When set to True checkpoint objects will not be constructed and written to disk during the course of this protocol. It is strongly recommended that this be kept set to False without good reason to disable the checkpoints.
 simulatorForwardSimulator.Castable or None
 Ignored if None. If not None, then we call
fwdsim = ForwardSimulator.cast(simulator),
and we set the .sim attribute of every Model we encounter to fwdsim.
Returns
Results
 pygsti.drivers.run_stdpractice_gst(data_filename_or_set, target_model_filename_or_object, prep_fiducial_list_or_filename, meas_fiducial_list_or_filename, germs_list_or_filename, max_lengths, modes=('full TP', 'CPTPLND', 'Target'), gaugeopt_suite='stdgaugeopt', gaugeopt_target=None, models_to_test=None, comm=None, mem_limit=None, advanced_options=None, output_pkl=None, verbosity=2, checkpoint=None, checkpoint_path=None, disable_checkpointing=False, simulator: pygsti.forwardsims.ForwardSimulator.Castable  None = None)
Perform endtoend GST analysis using standard practices.
This routines is an even higherlevel driver than
run_long_sequence_gst()
. It performs bottled, typicallyuseful, runs of long sequence GST on a dataset. This essentially boils down to runningrun_long_sequence_gst()
one or more times using different model parameterizations, and performing commonlyuseful gauge optimizations, based only on the highlevel modes argument.Parameters
 data_filename_or_setDataSet or string
The data set object to use for the analysis, specified either directly or by the filename of a dataset file (assumed to be a pickled DataSet if extension is ‘pkl’ otherwise assumed to be in pyGSTi’s text format).
 target_model_filename_or_objectModel or string
A specification of the target model that GST is to be run on, given either directly or by the filename of a model (text format).
 prep_fiducial_list_or_filename(list of Circuits) or string
The state preparation fiducial circuits, specified either directly or by the filename of a circuit list file (text format).
 meas_fiducial_list_or_filename(list of Circuits) or string or None
The measurement fiducial circuits, specified either directly or by the filename of a circuit list file (text format). If
None
, then use the same strings as specified by prep_fiducial_list_or_filename. germs_list_or_filename(list of Circuits) or string
The germ circuits, specified either directly or by the filename of a circuit list file (text format).
 max_lengthslist of ints
List of integers, one per LSGST iteration, which set truncation lengths for repeated germ strings. The list of circuits for the ith LSGST iteration includes the repeated germs truncated to the Lvalues up to and including the ith one.
 modesiterable of strs, optional (default (‘full TP’,’CPTPLND’,’Target’)
An iterable strings corresponding to modes which dictate what types of analyses are performed. Currently, these correspond to different types of parameterizations/constraints to apply to the estimated model. The default value is usually fine. Allowed values are:
“full” : full (completely unconstrained)
“TP” : TPconstrained
“CPTP” : Lindbladian CPTPconstrained
“H+S” : Only Hamiltonian + Stochastic errors allowed (CPTP)
“S” : Only Stochastic errors allowed (CPTP)
“Target” : use the target (ideal) gates as the estimate
<model> : any key in the models_to_test argument
 gaugeopt_suitestr or list or dict, optional
Specifies which gauge optimizations to perform on each estimate. A string or list of strings (see below) specifies builtin sets of gauge optimizations, otherwise gaugeopt_suite should be a dictionary of gaugeoptimization parameter dictionaries, as specified by the gauge_opt_params argument of
run_long_sequence_gst()
. The key names of gaugeopt_suite then label the gauge optimizations within the resuling Estimate objects. The builtin suites are:“single” : performs only a single “best guess” gauge optimization.
“varySpam” : varies spam weight and toggles SPAM penalty (0 or 1).
“varySpamWt” : varies spam weight but no SPAM penalty.
“varyValidSpamWt” : varies spam weight with SPAM penalty == 1.
“toggleValidSpam” : toggles spame penalty (0 or 1); fixed SPAM wt.
“unreliable2Q” : adds branch to a spam suite that weights 2Q gates less
“none” : no gauge optimizations are performed.
 gaugeopt_targetModel, optional
If not None, a model to be used as the “target” for gauge optimization (only). This argument is useful when you want to gauge optimize toward something other than the ideal target gates given by target_model_filename_or_object, which are used as the default when gaugeopt_target is None.
 models_to_testdict, optional
A dictionary of Model objects representing (gateset) models to test against the data. These Models are essentially hypotheses for which (if any) model generated the data. The keys of this dictionary can (and must, to actually test the models) be used within the comma separate list given by the modes argument.
 commmpi4py.MPI.Comm, optional
When not
None
, an MPI communicator for distributing the computation across multiple processors. mem_limitint or None, optional
A rough memory limit in bytes which restricts the amount of memory used (per core when run on multiCPUs).
 advanced_optionsdict, optional
Specifies advanced options most of which deal with numerical details of the objective function or expertlevel functionality. See
run_long_sequence_gst()
for a list of the allowed keys for each such dictionary. output_pklstr or file, optional
If not None, a file(name) to pickle.dump the returned Results object to (only the rank 0 process performs the dump when comm is not None).
 verbosityint, optional
The ‘verbosity’ option is an integer specifying the level of detail printed to stdout during the calculation.
 checkpointStandardGSTCheckpoint, optional (default None)
If specified use a previously generated checkpoint object to restart or warm start this run part way through.
 checkpoint_pathstr, optional (default None)
A string for the path/name to use for writing intermediate checkpoint files to disk. Format is {path}/{name}, without inclusion of the json file extension. This {path}/{name} combination will have the latest completed iteration number appended to it before writing it to disk. If none, the value of {name} will be set to the name of the protocol being run.
 disable_checkpointingbool, optional (default False)
When set to True checkpoint objects will not be constructed and written to disk during the course of this protocol. It is strongly recommended that this be kept set to False without good reason to disable the checkpoints.
 simulatorForwardSimulator.Castable or None
 Ignored if None. If not None, then we call
fwdsim = ForwardSimulator.cast(simulator),
and we set the .sim attribute of every Model we encounter to fwdsim.
Returns
Results