`pygsti.protocols.gst`

GST Protocol objects

Module Contents

Classes

`HasProcessorSpec`	Adds to an experiment design a processor_spec attribute
`GateSetTomographyDesign`	Minimal experiment design needed for GST
`StandardGSTDesign`	Standard GST experiment design consisting of germ-powers sandwiched between fiducials.
`GSTInitialModel`	Specification of a starting point for GST.
`GSTBadFitOptions`	Options for post-processing a GST fit that was unsatisfactory.
`GSTObjFnBuilders`	Holds the objective-function builders needed for long-sequence GST.
`GSTGaugeOptSuite`	Holds directives to perform one or more gauge optimizations on a model.
`GateSetTomography`	The core gate set tomography protocol, which optimizes a parameterized model to (best) fit a data set.
`LinearGateSetTomography`	The linear gate set tomography protocol.
`StandardGST`	The standard-practice GST protocol.
`ModelEstimateResults`	A results object that holds model estimates.
`GateSetTomographyCheckpoint`	A class for storing intermediate results associated with running
`StandardGSTCheckpoint`	A class for storing intermediate results associated with running

Attributes

`ROBUST_SUFFIX_LIST`
`DEFAULT_BAD_FIT_THRESHOLD`
`GSTDesign`
`GST`
`LGST`

pygsti.protocols.gst.ROBUST_SUFFIX_LIST = ['.robust', '.Robust', '.robust+', '.Robust+']

pygsti.protocols.gst.DEFAULT_BAD_FIT_THRESHOLD = 2.0

class pygsti.protocols.gst.HasProcessorSpec(processorspec_filename_or_obj)

Bases: object

Adds to an experiment design a processor_spec attribute

Parameters

processorspec_filename_or_objQuditProcessorSpec or str: The processor API used by this experiment design.

abstract create_target_model(gate_type='auto', prep_type='auto', povm_type='auto'): Deprecated function.

class pygsti.protocols.gst.GateSetTomographyDesign(processorspec_filename_or_obj, circuit_lists, all_circuits_needing_data=None, qubit_labels=None, nested=False, remove_duplicates=True)

Bases: pygsti.protocols.protocol.CircuitListsDesign, HasProcessorSpec

Minimal experiment design needed for GST

Parameters

processorspec_filename_or_objQuditProcessorSpec or str: The processor API used by this experiment design.
circuit_listslist or PlaquetteGridCircuitStructure: A list whose elements are themselves lists of Circuit objects, specifying the data that needs to be taken. Alternatively, a single PlaquetteGridCircuitStructure object containing a sequence of circuits lists, each at a different “x” value (usually the maximum circuit depth).
all_circuits_needing_datalist, optional: A list of all the circuits in circuit_lists typically with duplicates removed.
qubit_labelstuple, optional: The qubits that this experiment design applies to. If None, the line labels of the first circuit is used.
nestedbool, optional: Whether the elements of circuit_lists are nested, e.g. whether circuit_lists[i] is a subset of circuit_lists[i+1]. This is useful to know because certain operations can be more efficient when it is known that the lists are nested.
remove_duplicatesbool, optional: Whether to remove duplicates when automatically creating all the circuits that need data (this argument isn’t used when all_circuits_needing_data is given).

Create a new CircuitListsDesign object.

Parameters

circuit_listslist or PlaquetteGridCircuitStructure: A list whose elements are themselves lists of Circuit objects, specifying the data that needs to be taken. Alternatively, a single PlaquetteGridCircuitStructure object containing a sequence of circuits lists, each at a different “x” value (usually the maximum circuit depth).
all_circuits_needing_datalist, optional: A list of all the circuits needing data. By default, This is just the concatenation of the elements of circuit_lists with duplicates removed. The only reason to specify this separately is if you happen to have this list lying around.
qubit_labelstuple, optional: The qubits that this experiment design applies to. If None, the line labels of the first circuit is used.
nestedbool, optional: Whether the elements of circuit_lists are nested, e.g. whether circuit_lists[i] is a subset of circuit_lists[i+1]. This is useful to know because certain operations can be more efficient when it is known that the lists are nested.
remove_duplicatesbool, optional: Whether to remove duplicates when automatically creating all the circuits that need data (this argument isn’t used when all_circuits_needing_data is given).

Returns

CircuitListsDesign

map_qubit_labels(mapper)

Creates a new experiment design whose circuits’ qubit labels are updated according to a given mapping.

Parameters

mapperdict or function: A dictionary whose keys are the existing self.qubit_labels values and whose value are the new labels, or a function which takes a single (existing qubit-label) argument and returns a new qubit-label.

Returns

GateSetTomographyDesign

class pygsti.protocols.gst.StandardGSTDesign(processorspec_filename_or_obj, prep_fiducial_list_or_filename, meas_fiducial_list_or_filename, germ_list_or_filename, max_lengths, germ_length_limits=None, fiducial_pairs=None, keep_fraction=1, keep_seed=None, include_lgst=True, nest=True, circuit_rules=None, op_label_aliases=None, dscheck=None, action_if_missing='raise', qubit_labels=None, verbosity=0, add_default_protocol=False)

Bases: GateSetTomographyDesign

Standard GST experiment design consisting of germ-powers sandwiched between fiducials.

Parameters

processorspec_filename_or_objQuditProcessorSpec or str: The processor API used by this experiment design.
prep_fiducial_list_or_filenamelist or str: A list of preparation fiducial Circuit objects or the path to a filename containing them.
meas_fiducial_list_or_filenamelist or str: A list of measurement fiducial Circuit objects or the path to a filename containing them.
germ_list_or_filenamelist or str: A list of germ Circuit objects or the path to a filename containing them.
max_lengthslist: List of integers, one per LSGST iteration, which set truncation lengths for repeated germ strings. The list of circuits for the i-th LSGST iteration includes the repeated germs truncated to the L-values up to and including the i-th one.
germ_length_limitsdict, optional: A dictionary limiting the max-length values used for specific germs. Keys are germ sequences and values are integers. For example, if this argument is {(‘Gx’,): 4} and max_length_list = [1,2,4,8,16], then the germ (‘Gx’,) is only repeated using max-lengths of 1, 2, and 4 (whereas other germs use all the values in max_length_list).
fiducial_pairslist of 2-tuples or dict, optional: Specifies a subset of all fiducial string pairs (prepStr, effectStr) to be used in the circuit lists. If a list, each element of fid_pairs is a (iPrepStr, iEffectStr) 2-tuple of integers, each indexing a string within prep_strs and effect_strs, respectively, so that prepStr = prep_strs[iPrepStr] and effectStr = effect_strs[iEffectStr]. If a dictionary, keys are germs (elements of germ_list) and values are lists of 2-tuples specifying the pairs to use for that germ.
keep_fractionfloat, optional: The fraction of fiducial pairs selected for each germ-power base string. The default includes all fiducial pairs. Note that for each germ-power the selected pairs are different random sets of all possible pairs (unlike fid_pairs, which specifies the same fiducial pairs for all same-germ base strings). If fid_pairs is used in conjuction with keep_fraction, the pairs specified by fid_pairs are always selected, and any additional pairs are randomly selected.
keep_seedint, optional: The seed used for random fiducial pair selection (only relevant when keep_fraction < 1).
include_lgstboolean, optional: If true, then the starting list (only applicable when nest == True) is the list of LGST strings rather than the empty list. This means that when nest == True, the LGST sequences will be included in all the lists.
nestboolean, optional: If True, the GST circuit lists are “nested”, meaning that each successive list of circuits contains all the gate strings found in previous lists (and usually some additional new ones). If False, then the returned circuit list for maximum length == L contains only those circuits specified in the description above, and not those for previous values of L.
circuit_ruleslist, optional: A list of (find,replace) 2-tuples which specify circuit-label replacement rules. Both find and replace are tuples of operation labels (or Circuit objects).
op_label_aliasesdictionary, optional: Dictionary whose keys are operation label “aliases” and whose values are tuples corresponding to what that operation label should be expanded into before querying the dataset. This information is stored within the returned circuit structures. Defaults to the empty dictionary (no aliases defined) e.g. op_label_aliases[‘Gx^3’] = (‘Gx’,’Gx’,’Gx’)
dscheckDataSet, optional: A data set which filters the circuits used for GST. When a standard-GST circuit is missing from this DataSet, action is taken according to action_if_missing.
action_if_missing{“raise”,”drop”}, optional: The action to take when a desired circuit is missing from dscheck (only relevant when dscheck is not None). “raise” causes a ValueError to be raised; “drop” causes the missing sequences to be dropped from the returned set.
qubit_labelstuple, optional: The qubits that this experiment design applies to. If None, the line labels of the first circuit is used.
verbosityint, optional: The level of output to print to stdout.
add_default_protocolbool, optional: Whether a default StandardGST protocol should be added to this experiment design. Setting this to True makes it easy to analyze the data (after it’s gathered) corresponding to this design via a DefaultRunner.

Create a new CircuitListsDesign object.

Parameters

circuit_listslist or PlaquetteGridCircuitStructure: A list whose elements are themselves lists of Circuit objects, specifying the data that needs to be taken. Alternatively, a single PlaquetteGridCircuitStructure object containing a sequence of circuits lists, each at a different “x” value (usually the maximum circuit depth).
all_circuits_needing_datalist, optional: A list of all the circuits needing data. By default, This is just the concatenation of the elements of circuit_lists with duplicates removed. The only reason to specify this separately is if you happen to have this list lying around.
qubit_labelstuple, optional: The qubits that this experiment design applies to. If None, the line labels of the first circuit is used.
nestedbool, optional: Whether the elements of circuit_lists are nested, e.g. whether circuit_lists[i] is a subset of circuit_lists[i+1]. This is useful to know because certain operations can be more efficient when it is known that the lists are nested.
remove_duplicatesbool, optional: Whether to remove duplicates when automatically creating all the circuits that need data (this argument isn’t used when all_circuits_needing_data is given).

Returns

CircuitListsDesign

copy_with_maxlengths(max_lengths, germ_length_limits=None, dscheck=None, action_if_missing='raise', verbosity=0)

Copies this GST experiment design to one with the same data except a different set of maximum lengths.

Parameters

max_lengths_to_keeplist: A list of the maximum lengths that should be present in the returned experiment design.
germ_length_limitsdict, optional: A dictionary limiting the max-length values to keep for specific germs. Keys are germ sequences and values are integers. If None, then the current length limits are used.
dscheckDataSet, optional: A data set which filters the circuits used for GST. When a standard-GST circuit is missing from this DataSet, action is taken according to action_if_missing.
action_if_missing{“raise”,”drop”}, optional: The action to take when a desired circuit is missing from dscheck (only relevant when dscheck is not None). “raise” causes a ValueError to be raised; “drop” causes the missing sequences to be dropped from the returned set.

Returns

StandardGSTDesign

map_qubit_labels(mapper)

Creates a new experiment design whose circuits’ qubit labels are updated according to a given mapping.

Parameters

mapperdict or function: A dictionary whose keys are the existing self.qubit_labels values and whose value are the new labels, or a function which takes a single (existing qubit-label) argument and returns a new qubit-label.

Returns

StandardGSTDesign

class pygsti.protocols.gst.GSTInitialModel(model=None, target_model=None, starting_point=None, depolarize_start=0, randomize_start=0, lgst_gaugeopt_tol=1e-06, contract_start_to_cptp=False)

Bases: pygsti.baseobjs.nicelyserializable.NicelySerializable

Specification of a starting point for GST.

Parameters

modelModel, optional: The model to start at, given explicitly.
starting_point{“target”, “User-supplied-Model”, “LGST”, “LGST-if-possible”}, optional: The starting point type. If None, then defaults to “User-supplied-Model” if model is given, otherwise to “target”.
depolarize_startfloat, optional: Amount to depolarize the starting model just prior to running GST.
randomize_startfloat, optional: Amount to randomly kick the starting model just prior to running GST.
lgst_gaugeopt_tolfloat, optional: Gauge-optimization tolerance for the post-LGST gauge optimization that is performed when starting_point == “LGST” or possibly when “starting_point == “LGST-if-possible”.
contract_start_to_cptpbool, optional: Whether the Model should be forced (“contracted”) to being CPTP just prior to running GST.

classmethod cast(obj)

Cast obj to a GSTInitialModel object.

Parameters

objobject: object to cast. Can be a GSTInitialModel (naturally) or a Model.

Returns

GSTInitialModel

retrieve_model(edesign, gaugeopt_target, dataset, comm)

Retrieve the starting-point Model used to seed a long-sequence GST run.

Parameters

edesignExperimentDesign: The experiment design containing the circuits being used, the qubit labels, and (possibly) a target model (for use when starting_point == “target”) and fiducial circuits (for LGST).
gaugeopt_targetModel: The gauge-optimization target, i.e. distance to this model is the objective function within the post-LGST gauge-optimization step.
datasetDataSet: Data used to execute LGST when needed.
commmpi4py.MPI.Comm: A MPI communicator to divide workload amoung multiple processors.

Returns

Model

class pygsti.protocols.gst.GSTBadFitOptions(threshold=DEFAULT_BAD_FIT_THRESHOLD, actions=(), wildcard_budget_includes_spam=True, wildcard_L1_weights=None, wildcard_primitive_op_labels=None, wildcard_initial_budget=None, wildcard_methods=('neldermead',), wildcard_inadmissable_action='print', wildcard1d_reference='diamond distance')

Bases: pygsti.baseobjs.nicelyserializable.NicelySerializable

Options for post-processing a GST fit that was unsatisfactory.

Parameters

thresholdfloat, optional

A threshold, given in number-of-standard-deviations, below which a GST fit is considered satisfactory (and no “bad-fit” processing is needed).

actionstuple, optional

Actions to take when a GST fit is unsatisfactory. Allowed actions include:

‘wildcard’: Find an admissable wildcard model.
‘wildcard1d’: Fits a single parameter wildcard model in which the amount of wildcard error added to an operation is proportional to the diamond distance between that operation and the target.
‘robust’: scale data according out “robust statistics v1” algorithm,
where we drastically scale down (reduce) the data due to especially poorly fitting circuits. Namely, if a circuit’s log-likelihood ratio exceeds the 95% confidence region about its expected value (the # of degrees of freedom in the circuits outcomes), then the data is scaled by the expected_value / actual_value, so that the new value exactly matches what would be expected. Ideally there are only a few of these “outlier” circuits, which correspond errors in the measurement apparatus.
‘Robust’: same as ‘robust’, but re-optimize the final objective function
(usually the log-likelihood) after performing the scaling to get the final estimate.
‘robust+’: scale data according out “robust statistics v2” algorithm,
which performs the v1 algorithm (see ‘robust’ above) and then further rescales all the circuit data to achieve the desired chi2 distribution of per-circuit goodness-of-fit values without reordering these values.
‘Robust+’: same as ‘robust+’, but re-optimize the final objective function
(usually the log-likelihood) after performing the scaling to get the final estimate.
‘do nothing’: do not perform any additional actions. Used to help avoid
the need for special cases when working with multiple types of bad-fit actions.

wildcard_budget_includes_spambool, optional

Include a SPAM budget within the wildcard budget used to process the “wildcard” action.

wildcard_L1_weightsnp.array, optional

An array of weights affecting the L1 penalty term used to select a feasible wildcard error vector w_i that minimizes sum_i weight_i* |w_i| (a weighted L1 norm). Elements of this array must correspond to those of the wildcard budget being optimized, typically the primitive operations of the estimated model - but to get the order right you should specify wildcard_primitive_op_labels to be sure. If None, then all weights are assumed to be 1.

wildcard_primitive_op_labels: list, optional

The primitive operation labels used to construct the PrimitiveOpsWildcardBudget that is optimized. If None, equal to model.primitive_op_labels + model.primitive_instrument_labels where model is the estimated model, with ‘SPAM’ at the end if wildcard_budget_includes_spam is True. When specified, should contain a subset of the default values.

wildcard_methods: tuple, optional

A list of the methods to use to optimize the wildcard error vector. Default is (“neldermead”,). Options include “neldermead”, “barrier”, “cvxopt”, “cvxopt_smoothed”, “cvxopt_small”, and “cvxpy_noagg”. So many methods exist because different convex solvers behave differently (unfortunately). Leave as the default as a safe option, but “barrier” is pretty reliable and much faster than “neldermead”, and is a good option so long as it runs.

wildcard_inadmissable_action: {“print”, “raise”}, optional

What to do when an inadmissable wildcard error vector is found. The default just prints this information and continues, while “raise” raises a ValueError. Often you just want this information printed so that when the wildcard analysis fails in this way it doesn’t cause the rest of an analysis to abort.

classmethod cast(obj)

Cast obj to a GSTBadFitOptions object.

Parameters

objobject: Object to cast. Can be a GSTBadFitOptions (naturally) or a dictionary of constructor arguments.

Returns

GSTBadFitOptions

class pygsti.protocols.gst.GSTObjFnBuilders(iteration_builders, final_builders=())

Bases: pygsti.baseobjs.nicelyserializable.NicelySerializable

Holds the objective-function builders needed for long-sequence GST.

Parameters

iteration_builderslist or tuple: A list of ObjectiveFunctionBuilder objects used (sequentially) on each GST iteration.
final_builderslist or tuple, optional: A list of ObjectiveFunctionBuilder objects used (sequentially) on the final GST iteration.

classmethod cast(obj)

Cast obj to a GSTObjFnBuilders object.

Parameters

objobject: Object to cast. Can be a GSTObjFnBuilders (naturally), a dictionary of create_from() arguments (or None), or a list or tuple of the (iteration_builders, final_builders) constructor arguments.

Returns

GSTObjFnBuilders

classmethod create_from(objective='logl', freq_weighted_chi2=False, always_perform_mle=False, only_perform_mle=False)

Creates a common GSTObjFnBuilders object from several arguments.

Parameters

objective{‘logl’, ‘chi2’}, optional: Whether to create builders for maximum-likelihood or minimum-chi-squared GST.
freq_weighted_chi2bool, optional: Whether chi-squared objectives use frequency-weighting. If you’re not sure what this is, leave it as False.
always_perform_mlebool, optional: Perform a ML-GST step on each iteration (usually this is only done for the final iteration).
only_perform_mlebool, optional: Only perform a ML-GST step on each iteration, i.e. do not perform any chi2 minimization to “seed” the ML-GST step.

Returns

GSTObjFnBuilders

class pygsti.protocols.gst.GSTGaugeOptSuite(gaugeopt_suite_names=None, gaugeopt_argument_dicts=None, gaugeopt_target=None)

Bases: pygsti.baseobjs.nicelyserializable.NicelySerializable

Holds directives to perform one or more gauge optimizations on a model.

Usually this gauge optimization is done after fitting a parameterized model to data (e.g. after GST), as the data cannot (by definition) prefer any particular gauge choice.

Parameters

gaugeopt_suite_namesstr or list of strs, optional

Names one or more gauge optimization suites to perform. A string or list of strings (see below) specifies built-in sets of gauge optimizations. The built-in 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. When passed individually
(not in a list with other suite names) then this results in an empty GSTGaugeOptSuite object (w/gaugeopt_suite_names set to None).

gaugeopt_argument_dictsdict, optional

A dictionary whose string-valued keys label different gauge optimizations (e.g. within a resulting Estimate object). Each corresponding value can be either a dictionary of arguments to gaugeopt_to_target() or a list of such dictionaries which then describe the different stages of a multi-stage gauge optimization.

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 the target model, which are used as the default when gaugeopt_target is None.

classmethod cast(obj)

is_empty()

Whether this suite is completely empty, i.e., contains NO gauge optimization instructions.

This is a useful check before constructing quantities needed by gauge optimization, e.g. a target model, which can just be skipped when no gauge optimization will be performed.

Returns

bool

to_dictionary(model, unreliable_ops=(), verbosity=0)

Converts this gauge optimization suite into a raw dictionary of dictionaries.

Constructs a dictionary of gauge-optimization parameter dictionaries based on “gauge optimization suite” name(s).

This essentially renders the gauge-optimization directives within this object in an “expanded” form for either running gauge optimization (e.g. within a GateSetTomography.run() call) or for constructing the would-be gauge optimization call arguments so they can be slightly modeified before passing them in as the actual gauge-optimization suite used in an analysis (the resulting dictionary can be used to initialize a new GSTGaugeOptSuite object via the gaugeopt_argument_dicts argument.

Parameters

modelModel: A model which specifies the dimension (i.e. parameterization) of the gauge-optimization and the basis. Typically the model that is optimized or the ideal model using the same parameterization and having the correct default-gauge-group as the model that is optimized.
unreliable_opstuple, optional: A tuple of gate (or circuit-layer) labels that count as “unreliable operations”. Typically these are the multi-qubit (2-qubit) gates.
verbosityint: The verbosity to attach to the various gauge optimization parameter dictionaries.

Returns

dict: A dictionary whose keys are the labels of the different gauge optimizations to perform and whose values are the corresponding dictionaries of arguments to gaugeopt_to_target() (or lists of such dictionaries for a multi-stage gauge optimization).

class pygsti.protocols.gst.GateSetTomography(initial_model=None, gaugeopt_suite='stdgaugeopt', objfn_builders=None, optimizer=None, badfit_options=None, verbosity=2, name=None)

Bases: pygsti.protocols.protocol.Protocol

The core gate set tomography protocol, which optimizes a parameterized model to (best) fit a data set.

Parameters

initial_modelModel or GSTInitialModel, optional: The starting-point Model.
gaugeopt_suiteGSTGaugeOptSuite, optional: Specifies which gauge optimizations to perform on each estimate. Can also be any object that can be cast to a GSTGaugeOptSuite object, such as a string or list of strings (see below) specifying built-in sets of gauge optimizations. This object also optionally stores an alternate target model for gauge optimization. This model is used as the “target” for gauge- optimization (only), and is useful when you want to gauge optimize toward something other than the ideal target gates.
objfn_buildersGSTObjFnBuilders, optional: The objective function(s) to optimize. Can also be anything that can be cast to a GSTObjFnBuilders object.
optimizerOptimizer, optional: The optimizer to use. Can also be anything that can be cast to a Optimizer.
badfit_optionsGSTBadFitOptions, optional: Options specifying what post-processing actions should be performed if the GST fit is unsatisfactory. Can also be anything that can be cast to a GSTBadFitOptions object.
verbosityint, optional: The ‘verbosity’ option is an integer specifying the level of detail printed to stdout during the calculation.
namestr, optional: The name of this protocol, also used to (by default) name the results produced by this protocol. If None, the class name will be used.

Create a new Protocol object.

Parameters

namestr, optional: The name of this protocol, also used to (by default) name the results produced by this protocol. If None, the class name will be used.

Returns

Protocol

run(data, memlimit=None, comm=None, checkpoint=None, checkpoint_path=None, disable_checkpointing=False, simulator: pygsti.forwardsims.ForwardSimulator.Castable | None = None)

Run this protocol on data.

Parameters

dataProtocolData

The input data.

memlimitint, optional (default None)

A rough per-processor memory limit in bytes.

commmpi4py.MPI.Comm, optional (default None)

When not None, an MPI communicator used to run this protocol in parallel.

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

ModelEstimateResults

class pygsti.protocols.gst.LinearGateSetTomography(target_model=None, gaugeopt_suite='stdgaugeopt', badfit_options=None, verbosity=2, name=None)

Bases: pygsti.protocols.protocol.Protocol

The linear gate set tomography protocol.

Parameters

target_modelModel, optional: The target (ideal) model.
gaugeopt_suiteGSTGaugeOptSuite, optional: Specifies which gauge optimizations to perform on each estimate. Can also be any object that can be cast to a GSTGaugeOptSuite object, such as a string or list of strings (see below) specifying built-in sets of gauge optimizations. This object also optionally stores an alternate target model for gauge optimization. This model is used as the “target” for gauge- optimization (only), and is useful when you want to gauge optimize toward something other than the ideal target gates.
badfit_optionsGSTBadFitOptions, optional: Options specifying what post-processing actions should be performed if the LGST fit is unsatisfactory. Can also be anything that can be cast to a GSTBadFitOptions object.
verbosityint, optional: The ‘verbosity’ option is an integer specifying the level of detail printed to stdout during the calculation.
namestr, optional: The name of this protocol, also used to (by default) name the results produced by this protocol. If None, the class name will be used.

Create a new Protocol object.

Parameters

namestr, optional: The name of this protocol, also used to (by default) name the results produced by this protocol. If None, the class name will be used.

Returns

Protocol

check_if_runnable(data)

Raises a ValueError if LGST cannot be run on data

Parameters

dataProtocolData: The experimental data to test for LGST-compatibility.

Returns

None

run(data, memlimit=None, comm=None)

Run this protocol on data.

Parameters

dataProtocolData: The input data.
memlimitint, optional: A rough per-processor memory limit in bytes.
commmpi4py.MPI.Comm, optional: When not None, an MPI communicator used to run this protocol in parallel.

Returns

ModelEstimateResults

class pygsti.protocols.gst.StandardGST(modes=('full TP', 'CPTPLND', 'Target'), gaugeopt_suite='stdgaugeopt', target_model=None, models_to_test=None, objfn_builders=None, optimizer=None, badfit_options=None, verbosity=2, name=None)

Bases: pygsti.protocols.protocol.Protocol

The standard-practice GST protocol.

Parameters

modesstr, optional

A comma-separated list of 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” : TP-constrained
“CPTPLND” : Lindbladian CPTP-constrained
“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_suiteGSTGaugeOptSuite, optional

Specifies which gauge optimizations to perform on each estimate. Can also be any object that can be cast to a GSTGaugeOptSuite object, such as a string or list of strings (see below) specifying built-in sets of gauge optimizations. This object also optionally stores an alternate target model for gauge optimization. This model is used as the “target” for gauge- optimization (only), and is useful when you want to gauge optimize toward something other than the ideal target gates.

target_modelModel, optional (default None)

If specified use this Model as the target model. Depending on other specified keyword arguments this model may be used as the target for the purposes of gauge optimization, report generation/analysis, and initial seeding for optimization. (For almost all of these it may be the case that other keyword argument values override this for certain tasks).

models_to_testdict, optional

A dictionary of Model objects representing (gate-set) 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.

objfn_buildersGSTObjFnBuilders, optional

The objective function(s) to optimize. Can also be anything that can be cast to a GSTObjFnBuilders object. Applies to all modes.

optimizerOptimizer, optional

The optimizer to use. Can also be anything that can be case to a Optimizer. Applies to all modes.

badfit_optionsGSTBadFitOptions, optional

Options specifying what post-processing actions should be performed if the GST fit is unsatisfactory. Can also be anything that can be cast to a GSTBadFitOptions object. Applies to all modes.

verbosityint, optional

The ‘verbosity’ option is an integer specifying the level of detail printed to stdout during the calculation.

namestr, optional

The name of this protocol, also used to (by default) name the results produced by this protocol. If None, the class name will be used.

Create a new Protocol object.

Parameters

namestr, optional: The name of this protocol, also used to (by default) name the results produced by this protocol. If None, the class name will be used.

Returns

Protocol

run(data, memlimit=None, comm=None, checkpoint=None, checkpoint_path=None, disable_checkpointing=False, simulator: pygsti.forwardsims.ForwardSimulator.Castable | None = None)

Run this protocol on data.

Parameters

dataProtocolData

The input data.

memlimitint, optional

A rough per-processor memory limit in bytes.

commmpi4py.MPI.Comm, optional

When not None, an MPI communicator used to run this protocol in parallel.

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

ProtocolResults

class pygsti.protocols.gst.ModelEstimateResults(data, protocol_instance, init_circuits=True)

Bases: pygsti.protocols.protocol.ProtocolResults

A results object that holds model estimates.

Parameters

dataProtocolData: The experimental data these results are generated from.
protocol_instanceProtocol: The protocol that generated these results.
init_circuitsbool, optional: Whether self.circuit_lists should be initialized or not. (In special cases, this can be disabled for speed.)

Attributes

datasetDataSet: The underlying data set.

Initialize an empty Results object.

property dataset: The underlying data set.

classmethod from_dir(dirname, name, preloaded_data=None, quick_load=False)

Initialize a new ModelEstimateResults object from dirname / results / name.

Parameters

dirnamestr: The root directory name (under which there is are ‘edesign’, ‘data’, and ‘results’ subdirectories).
namestr: The sub-directory name of the particular results object to load (there can be multiple under a given root dirname). This is the name of a subdirectory of dirname / results.
preloaded_dataProtocolData, optional: In the case that the ProtocolData object for dirname is already loaded, it can be passed in here. Otherwise leave this as None and it will be loaded.
quick_loadbool, optional: Setting this to True skips the loading of data and experiment-design components that may take a long time to load. This can be useful all the information of interest lies only within the results object.

Returns

ModelEstimateResults

to_nameddict(): Convert these results into nested NamedDict objects.

Returns

NamedDict

add_estimates(results, estimates_to_add=None)

Add some or all of the estimates from results to this Results object.

Parameters

resultsResults: The object to import estimates from. Note that this object must contain the same data set and gate sequence information as the importing object or an error is raised.
estimates_to_addlist, optional: A list of estimate keys to import from results. If None, then all the estimates contained in results are imported.

Returns

None

rename_estimate(old_name, new_name)

Rename an estimate in this Results object.

Ordering of estimates is not changed.

Parameters

old_namestr: The labels of the estimate to be renamed
new_namestr: The new name for the estimate.

Returns

None

add_estimate(estimate, estimate_key='default')

Add a set of Model estimates to this Results object.

Parameters

estimateEstimate: The estimate to add.
estimate_keystr, optional: The key or label used to identify this estimate.

Returns

None

add_model_test(target_model, themodel, estimate_key='test', gaugeopt_keys='auto', verbosity=2, simulator: pygsti.forwardsims.ForwardSimulator.Castable | None = None)

Add a new model-test (i.e. non-optimized) estimate to this Results object.

Parameters

target_modelModel

The target model used for comparison to the model.

themodelModel

The “model” model whose fit to the data and distance from target_model are assessed.

estimate_keystr, optional

The key or label used to identify this estimate.

gaugeopt_keyslist, optional

A list of gauge-optimization keys to add to the estimate. All of these keys will correspond to trivial gauge optimizations, as the model model is assumed to be fixed and to have no gauge degrees of freedom. The special value “auto” creates gauge-optimized estimates for all the gauge optimization labels currently in this Results object.

verbosityint, optional

Level of detail printed to stdout.

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

None

view(estimate_keys, gaugeopt_keys=None)

Creates a shallow copy of this Results object containing only the given estimate.

This function an also filter based on gauge-optimization keys, only keeping a subset of those available.

Parameters

estimate_keysstr or list: Either a single string-value estimate key or a list of such keys.
gaugeopt_keysstr or list, optional: Either a single string-value gauge-optimization key or a list of such keys. If None, then all gauge-optimization keys are retained.

Returns

Results

copy(): Creates a copy of this ModelEstimateResults object.

Returns

ModelEstimateResults

class pygsti.protocols.gst.GateSetTomographyCheckpoint(mdl_list=None, last_completed_iter=-1, last_completed_circuit_list=None, final_objfn=None, name=None, parent=None)

Bases: pygsti.protocols.protocol.ProtocolCheckpoint

A class for storing intermediate results associated with running a GateSetTomography protocol’s run method to allow for restarting that method partway through.

Parameters

mdl_listlist of models, optional (default None): Current list of models for each of the completed iterations of the protocol.
last_completed_iterint, optional (default -1): Index of the last iteration what was successfully completed.
last_completed_circuit_listlist of Circuit objects, CircuitList or equivalent, optional (default None): A list of Circuit objects corresponding to the last iteration successfully completed.
final_objfnModelDatasetCircuitStore, optional (Default None): A ModelDatasetCircuitStore object corresponding to the final evaluated objective function. Not currently serialized or used during the warmstarting, so purely informational and may not always be initialized.
namestr, optional (default None): An optional name for the checkpoint. Note this is not necessarily the name used in the automatic generation of filenames when written to disk.
parentProtocolCheckpoint, optional (default None): When specified this checkpoint object is treated as the child of another ProtocolCheckpoint object that acts as the parent. When present, the parent’s write method supersedes the child objects and is called when calling write on the child. Currently only used in the implementation of StandardGSTCheckpoint.

class pygsti.protocols.gst.StandardGSTCheckpoint(modes=None, children=None, name=None)

Bases: pygsti.protocols.protocol.ProtocolCheckpoint

A class for storing intermediate results associated with running a StandardGST protocol’s run method to allow for restarting that method partway through. This class acts as a container class for some set of child GateSetTomographyCheckpoint and ModelTestCheckpoint objects for each of the sub-protocols run in the course of the StandardGST protocol.

Parameters

modeslist of str, optional (default None): A list of strings corresponding to the mode labels being run in the StandardGST protocol object that generated this checkpoint.
childrendict, optional (default None): A dictionary whose keys correspond to modes (i.e. the same elements as the modes kwarg) and whose values are either GateSetTomographyCheckpoint or ModelTestCheckpoint objects, depending on whichever is appropriate for that mode.
namestr, optional (default None): An optional name for the checkpoint. Note this is not necessarily the name used in the automatic generation of filenames when written to disk.

property children

pygsti.protocols.gst.GSTDesign

pygsti.protocols.gst.GST

pygsti.protocols.gst.LGST

pygsti.protocols.gst

Module Contents

Classes

Attributes

Parameters

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Parameters

Returns

Parameters

Returns

Parameters

Attributes

Parameters

Returns

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Returns

Parameters

Parameters

`pygsti.protocols.gst`