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.

Functions

_load_pspec(processorspec_filename_or_obj)

_load_model(model_filename_or_obj)

_load_pspec_or_model(processorspec_or_model_filename_or_obj)

_load_fiducials_and_germs(prep_fiducial_list_or_filename, meas_fiducial_list_or_filename, germ_list_or_filename)

_load_dataset(data_filename_or_set, comm, verbosity)

Loads a DataSet from the data_filename_or_set argument of functions in this module.

_add_gaugeopt_and_badfit(results, estlbl, target_model, gaugeopt_suite, unreliable_ops, badfit_options, optimizer, resource_alloc, printer)

_add_gauge_opt(results, base_est_label, gaugeopt_suite, starting_model, unreliable_ops, comm=None, verbosity=0)

Add a gauge optimization to an estimate.

_add_badfit_estimates(results, base_estimate_label, badfit_options, optimizer=None, resource_alloc=None, verbosity=0)

Add any and all "bad fit" estimates to results.

_compute_robust_scaling(scale_typ, objfn_cache, mdc_objfn)

Get the per-circuit data scaling ("weights") for a given type of robust-data-scaling.

_compute_wildcard_budget(objfn_cache, mdc_objfn, parameters, badfit_options, verbosity)

Create a wildcard budget for a model estimate.

_reoptimize_with_weights(mdc_objfn, circuit_weights_dict, optimizer, verbosity)

Re-optimize a model after data counts have been scaled by circuit weights.

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_obj (QubitProcessorSpec or str) – The processor API used by this experiment design.

create_target_model(self, gate_type='auto', prep_type='auto', povm_type='auto')

Create a target model for this experiment design.

An explicit model is created based on the processor spec. If a different type of model is needed, consider creating the model manually via the construction functions in the pygsti.models.modelconstruction module using this experiment design’s .processor_spec attribute.

Parameters
  • gate_type (str, optional) – The type of gate objects to create. Currently “auto” is the same as “static”.

  • prep_type (str, optional) – The type of state preparation objects to create. “auto” selects a type based on the value of gate_type.

  • povm_type (str, optional) – The type of POVM objects to create. “auto” selects a type based on the value of gate_type.

Returns

Model

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_obj (QubitProcessorSpec or str) – The processor API used by this experiment design.

  • circuit_lists (list) – Per-GST-iteration circuit lists, giving the circuits to run at each GST iteration (typically these correspond to different maximum-lengths).

  • all_circuits_needing_data (list, optional) – A list of all the circuits in circuit_lists typically with duplicates removed.

  • qubit_labels (tuple, optional) – The qubits that this experiment design applies to. If None, the line labels of the first circuit is used.

  • nested (bool, 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_duplicates (bool, 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).

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_obj (QubitProcessorSpec or str) – The processor API used by this experiment design.

  • prep_fiducial_list_or_filename (list or str) – A list of preparation fiducial :class:`Circuit`s or the path to a filename containing them.

  • meas_fiducial_list_or_filename (list or str) – A list of measurement fiducial :class:`Circuit`s or the path to a filename containing them.

  • germ_list_or_filename (list or str) – A list of germ :class:`Circuit`s or the path to a filename containing them.

  • max_lengths (list) – 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_limits (dict, 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_pairs (list 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_fraction (float, 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_seed (int, optional) – The seed used for random fiducial pair selection (only relevant when keep_fraction < 1).

  • include_lgst (boolean, 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.

  • nest (boolean, 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_rules (list, 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_aliases (dictionary, 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’)

  • dscheck (DataSet, 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_labels (tuple, optional) – The qubits that this experiment design applies to. If None, the line labels of the first circuit is used.

  • verbosity (int, optional) – The level of output to print to stdout.

  • add_default_protocol (bool, 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.

copy_with_maxlengths(self, 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_keep (list) – A list of the maximum lengths that should be present in the returned experiment design.

  • germ_length_limits (dict, 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.

  • dscheck (DataSet, 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.

  • -------

  • 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
  • model (Model, 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_start (float, optional) – Amount to depolarize the starting model just prior to running GST.

  • randomize_start (float, optional) – Amount to randomly kick the starting model just prior to running GST.

  • lgst_gaugeopt_tol (float, 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_cptp (bool, optional) – Whether the Model should be forced (“contracted”) to being CPTP just prior to running GST.

classmethod cast(cls, obj)

Cast obj to a GSTInitialModel object.

Parameters

obj (object) – object to cast. Can be a GSTInitialModel (naturally) or a Model.

Returns

GSTInitialModel

retrieve_model(self, edesign, gaugeopt_target, dataset, comm)

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

Parameters
  • edesign (ExperimentDesign) – 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_target (Model) – The gauge-optimization target, i.e. distance to this model is the objective function within the post-LGST gauge-optimization step.

  • dataset (DataSet) – Data used to execute LGST when needed.

  • comm (mpi4py.MPI.Comm) – A MPI communicator to divide workload amoung multiple processors.

Returns

Model

_to_nice_serialization(self)
classmethod _from_nice_serialization(cls, state)
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')

Bases: pygsti.baseobjs.nicelyserializable.NicelySerializable

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

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

  • actions (tuple, optional) – Actions to take when a GST fit is unsatisfactory.

  • wildcard_budget_includes_spam (bool, optional) – Include a SPAM budget within the wildcard budget used to process the “wildcard” action.

classmethod cast(cls, obj)

Cast obj to a GSTBadFitOptions object.

Parameters

obj (object) – Object to cast. Can be a GSTBadFitOptions (naturally) or a dictionary of constructor arguments.

Returns

GSTBadFitOptions

_to_nice_serialization(self)
classmethod _from_nice_serialization(cls, state)
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_builders (list or tuple) – A list of ObjectiveFunctionBuilder objects used (sequentially) on each GST iteration.

  • final_builders (list or tuple, optional) – A list of ObjectiveFunctionBuilder objects used (sequentially) on the final GST iteration.

classmethod cast(cls, obj)

Cast obj to a GSTObjFnBuilders object.

Parameters

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

Returns

GSTObjFnBuilders

classmethod create_from(cls, 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_chi2 (bool, optional) – Whether chi-squared objectives use frequency-weighting. If you’re not sure what this is, leave it as False.

  • always_perform_mle (bool, optional) – Perform a ML-GST step on each iteration (usually this is only done for the final iteration).

  • only_perform_mle (bool, 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

_to_nice_serialization(self)
classmethod _from_nice_serialization(cls, state)
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_names (str 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.

  • gaugeopt_argument_dicts (dict, 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_target (Model, 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(cls, obj)
is_empty(self)

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(self, 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 :method:`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
  • model (Model) – 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_ops (tuple, optional) – A tuple of gate (or circuit-layer) labels that count as “unreliable operations”. Typically these are the multi-qubit (2-qubit) gates.

  • verbosity (int) – 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).

_update_gaugeopt_dict_from_suitename(self, gaugeopt_suite_dict, root_lbl, suite_name, model, unreliable_ops, printer)
__getstate__(self)
_to_nice_serialization(self)
classmethod _from_nice_serialization(cls, state)
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_model (Model or GSTInitialModel, optional) – The starting-point Model.

  • gaugeopt_suite (GSTGaugeOptSuite, 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_builders (GSTObjFnBuilders, optional) – The objective function(s) to optimize. Can also be anything that can be cast to a GSTObjFnBuilders object.

  • optimizer (Optimizer, optional) – The optimizer to use. Can also be anything that can be cast to a Optimizer.

  • badfit_options (GSTBadFitOptions, 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.

  • verbosity (int, optional) – The ‘verbosity’ option is an integer specifying the level of detail printed to stdout during the calculation.

  • name (str, 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.

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

Run this protocol on data.

Parameters
  • data (ProtocolData) – The input data.

  • memlimit (int, optional) – A rough per-processor memory limit in bytes.

  • comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator used to run this protocol in parallel.

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_model (Model, optional) – The target (ideal) model.

  • gaugeopt_suite (GSTGaugeOptSuite, 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_options (GSTBadFitOptions, 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.

  • verbosity (int, optional) – The ‘verbosity’ option is an integer specifying the level of detail printed to stdout during the calculation.

  • name (str, 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.

check_if_runnable(self, data)

Raises a ValueError if LGST cannot be run on data

Parameters

data (ProtocolData) – The experimental data to test for LGST-compatibility.

Returns

None

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

Run this protocol on data.

Parameters
  • data (ProtocolData) – The input data.

  • memlimit (int, optional) – A rough per-processor memory limit in bytes.

  • comm (mpi4py.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,CPTP,Target', gaugeopt_suite='stdgaugeopt', 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
  • modes (str, 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

    • ”CPTP” : 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_suite (GSTGaugeOptSuite, 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.

  • models_to_test (dict, 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_builders (GSTObjFnBuilders, optional) – The objective function(s) to optimize. Can also be anything that can be cast to a GSTObjFnBuilders object. Applies to all modes.

  • optimizer (Optimizer, optional) – The optimizer to use. Can also be anything that can be case to a Optimizer. Applies to all modes.

  • badfit_options (GSTBadFitOptions, 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.

  • verbosity (int, optional) – The ‘verbosity’ option is an integer specifying the level of detail printed to stdout during the calculation.

  • name (str, 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.

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

Run this protocol on data.

Parameters
  • data (ProtocolData) – The input data.

  • memlimit (int, optional) – A rough per-processor memory limit in bytes.

  • comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator used to run this protocol in parallel.

Returns

ProtocolResults

pygsti.protocols.gst._load_pspec(processorspec_filename_or_obj)
pygsti.protocols.gst._load_model(model_filename_or_obj)
pygsti.protocols.gst._load_pspec_or_model(processorspec_or_model_filename_or_obj)
pygsti.protocols.gst._load_fiducials_and_germs(prep_fiducial_list_or_filename, meas_fiducial_list_or_filename, germ_list_or_filename)
pygsti.protocols.gst._load_dataset(data_filename_or_set, comm, verbosity)

Loads a DataSet from the data_filename_or_set argument of functions in this module.

pygsti.protocols.gst._add_gaugeopt_and_badfit(results, estlbl, target_model, gaugeopt_suite, unreliable_ops, badfit_options, optimizer, resource_alloc, printer)
pygsti.protocols.gst._add_gauge_opt(results, base_est_label, gaugeopt_suite, starting_model, unreliable_ops, comm=None, verbosity=0)

Add a gauge optimization to an estimate.

Parameters
  • results (ModelEstimateResults) – The parent results of the estimate to add a gauge optimization to. The estimate is specified via results and base_est_label rather than just passing an Estimate directly so that related (e.g. bad-fit) estimates can also be updated.

  • base_est_label (str) – The key within results.estimates of the primary Estimate to update.

  • gaugeopt_suite (GSTGaugeOptSuite, 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 specifies the ideal gates and the default gauge group to optimize over (this should be set prior to calling this function).

  • starting_model (Model) – The starting model of the GST or GST-like protocol. This communicates the parameterization that is available to gauge optimize over, and helps interpret gauge-optimization-suite names (e.g. “stdgaugeopt” produces different steps based on the parameterization of starting_model).

  • unreliable_ops (tuple, optional) – A tuple of gate (or circuit-layer) labels that count as “unreliable operations”. Typically these are the multi-qubit (2-qubit) gates.

  • comm (mpi4py.MPI.Comm, optional) – When not None, an MPI communicator used to run computations in parallel.

  • verbosity (int, optional) – The level of detail printed to stdout.

Returns

None

pygsti.protocols.gst._add_badfit_estimates(results, base_estimate_label, badfit_options, optimizer=None, resource_alloc=None, verbosity=0)

Add any and all “bad fit” estimates to results.

Parameters
  • results (ModelEstimateResults) – The results to add bad-fit estimates to.

  • base_estimate_label (str) – The primary estimate label to base bad-fit additions off of.

  • badfit_options (GSTBadFitOptions) – The options specifing what constitutes a “bad fit” and what actions to take when one occurs.

  • optimizer (Optimizer) – The optimizer to perform re-optimization, if any is needed.

  • resource_alloc (ResourceAllocation, optional) – What resources are available and how they should be distributed.

  • verbosity (int, optional) – Level of detail printed to stdout.

Returns

None

pygsti.protocols.gst._compute_robust_scaling(scale_typ, objfn_cache, mdc_objfn)

Get the per-circuit data scaling (“weights”) for a given type of robust-data-scaling. TODO: update docstring

Parameters
  • scale_typ ({'robust', 'robust+', 'Robust', 'Robust+'}) – The type of robust scaling. Captial vs. lowercase “R” doesn’t matter to this function (it indicates whether a post-scaling re-optimization is performed elsewhere). The “+” postfix distinguishes a “version 1” scaling (no “+”), where we drastically scale down weights of especially bad sequences, from a “version 2” scaling (“+”), where we additionaly rescale all the circuit data to achieve the desired chi2 distribution of per-circuit goodness-of-fit values without reordering these values.

  • model (Model) – The final model fit.

  • ds (DataSet) – The data set to compare to the model predictions.

  • circuit_list (list) – A list of the :class:`Circuit`s whose data should be compared.

  • parameters (dict) – Various parameters of the estimate at hand.

  • comm (mpi4py.MPI.Comm, optional) – An MPI communicator used to run this computation in parallel.

  • mem_limit (int, optional) – A rough per-processor memory limit in bytes.

Returns

dict – A dictionary of circuit weights. Keys are cirrcuits and values are scaling factors that should be applied to the data counts for that circuit. Omitted circuits should not be scaled.

pygsti.protocols.gst._compute_wildcard_budget(objfn_cache, mdc_objfn, parameters, badfit_options, verbosity)

Create a wildcard budget for a model estimate. TODO: update docstring

Parameters
  • model (Model) – The model to add a wildcard budget to.

  • ds (DataSet) – The data the model predictions are being compared with.

  • circuits_to_use (list) – The circuits whose data are compared.

  • parameters (dict) – Various parameters of the estimate at hand.

  • badfit_options (GSTBadFitOptions, optional) – Options specifying what post-processing actions should be performed when a fit is unsatisfactory. Contains detailed parameters for wildcard budget creation.

  • comm (mpi4py.MPI.Comm, optional) – An MPI communicator used to run this computation in parallel.

  • mem_limit (int, optional) – A rough per-processor memory limit in bytes.

  • verbosity (int, optional) – Level of detail printed to stdout.

Returns

PrimitiveOpsWildcardBudget

pygsti.protocols.gst._reoptimize_with_weights(mdc_objfn, circuit_weights_dict, optimizer, verbosity)

Re-optimize a model after data counts have been scaled by circuit weights. TODO: update docstring

Parameters
  • model (Model) – The model to re-optimize.

  • ds (DataSet) – The data set to compare againts.

  • circuit_list (list) – The circuits for which data and predictions should be compared.

  • circuit_weights_dict (dict) – A dictionary of circuit weights, such as that returned by :function:`_compute_robust_scaling`, giving the data-count scaling factors.

  • objfn_builder (ObjectiveFunctionBuilder) – The objective function (builder) that represents the final stage of optimization. This defines what objective function is minimized in this re-optimization.

  • optimizer (Optimizer) – The optimizer to use.

  • resource_alloc (ResourceAllocation, optional) – What resources are available and how they should be distributed.

  • verbosity (int, optional) – Level of detail printed to stdout.

Returns

Model – The re-optimized model, potentially the same object as model.

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

Bases: pygsti.protocols.protocol.ProtocolResults

A results object that holds model estimates.

Parameters
  • data (ProtocolData) – The experimental data these results are generated from.

  • protocol_instance (Protocol) – The protocol that generated these results.

  • init_circuits (bool, optional) – Whether self.circuit_lists should be initialized or not. (In special cases, this can be disabled for speed.)

dataset

The underlying data set.

Type

DataSet

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

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

Parameters
  • dirname (str) – The root directory name (under which there is are ‘edesign’, ‘data’, and ‘results’ subdirectories).

  • name (str) – 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_data (ProtocolData, 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_load (bool, 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

_create_circuit_lists(self, edesign)
property dataset(self)

The underlying data set.

to_nameddict(self)

Convert these results into nested NamedDict objects.

Returns

NamedDict

add_estimates(self, results, estimates_to_add=None)

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

Parameters
  • results (Results) – 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_add (list, 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(self, old_name, new_name)

Rename an estimate in this Results object.

Ordering of estimates is not changed.

Parameters
  • old_name (str) – The labels of the estimate to be renamed

  • new_name (str) – The new name for the estimate.

Returns

None

add_estimate(self, estimate, estimate_key='default')

Add a set of Model estimates to this Results object.

Parameters
  • estimate (Estimate) – The estimate to add.

  • estimate_key (str, optional) – The key or label used to identify this estimate.

Returns

None

add_model_test(self, target_model, themodel, estimate_key='test', gaugeopt_keys='auto')

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

Parameters
  • target_model (Model) – The target model used for comparison to the model.

  • themodel (Model) – The “model” model whose fit to the data and distance from target_model are assessed.

  • estimate_key (str, optional) – The key or label used to identify this estimate.

  • gaugeopt_keys (list, 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.

Returns

None

view(self, 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_keys (str or list) – Either a single string-value estimate key or a list of such keys.

  • gaugeopt_keys (str 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(self)

Creates a copy of this ModelEstimateResults object.

Returns

ModelEstimateResults

__setstate__(self, state_dict)
__str__(self)

Return str(self).

pygsti.protocols.gst.GSTDesign
pygsti.protocols.gst.GST
pygsti.protocols.gst.LGST