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