:py:mod:`pygsti.protocols.gst` ============================== .. py:module:: pygsti.protocols.gst .. autoapi-nested-parse:: GST Protocol objects Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: pygsti.protocols.gst.HasProcessorSpec pygsti.protocols.gst.GateSetTomographyDesign pygsti.protocols.gst.StandardGSTDesign pygsti.protocols.gst.GSTInitialModel pygsti.protocols.gst.GSTBadFitOptions pygsti.protocols.gst.GSTObjFnBuilders pygsti.protocols.gst.GSTGaugeOptSuite pygsti.protocols.gst.GateSetTomography pygsti.protocols.gst.LinearGateSetTomography pygsti.protocols.gst.StandardGST pygsti.protocols.gst.ModelEstimateResults pygsti.protocols.gst.GateSetTomographyCheckpoint pygsti.protocols.gst.StandardGSTCheckpoint Attributes ~~~~~~~~~~ .. autoapisummary:: pygsti.protocols.gst.ROBUST_SUFFIX_LIST pygsti.protocols.gst.DEFAULT_BAD_FIT_THRESHOLD pygsti.protocols.gst.GSTDesign pygsti.protocols.gst.GST pygsti.protocols.gst.LGST .. py:data:: ROBUST_SUFFIX_LIST :value: "['.robust', '.Robust', '.robust+', '.Robust+']" .. py:data:: DEFAULT_BAD_FIT_THRESHOLD :value: '2.0' .. py:class:: HasProcessorSpec(processorspec_filename_or_obj) Bases: :py:obj:`object` Adds to an experiment design a `processor_spec` attribute Parameters ---------- processorspec_filename_or_obj : QuditProcessorSpec or str The processor API used by this experiment design. .. py:attribute:: processor_spec .. py:method:: create_target_model(gate_type='auto', prep_type='auto', povm_type='auto') :abstractmethod: Deprecated function. .. py:class:: GateSetTomographyDesign(processorspec_filename_or_obj, circuit_lists, all_circuits_needing_data=None, qubit_labels=None, nested=False, remove_duplicates=True) Bases: :py:obj:`pygsti.protocols.protocol.CircuitListsDesign`, :py:obj:`HasProcessorSpec` Minimal experiment design needed for GST Parameters ---------- processorspec_filename_or_obj : QuditProcessorSpec or str The processor API used by this experiment design. circuit_lists : list or PlaquetteGridCircuitStructure A list whose elements are themselves lists of :class:`Circuit` objects, specifying the data that needs to be taken. Alternatively, a single :class:`PlaquetteGridCircuitStructure` object containing a sequence of circuits lists, each at a different "x" value (usually the maximum circuit depth). 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). Create a new CircuitListsDesign object. Parameters ---------- circuit_lists : list or PlaquetteGridCircuitStructure A list whose elements are themselves lists of :class:`Circuit` objects, specifying the data that needs to be taken. Alternatively, a single :class:`PlaquetteGridCircuitStructure` object containing a sequence of circuits lists, each at a different "x" value (usually the maximum circuit depth). all_circuits_needing_data : list, 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_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). Returns ------- CircuitListsDesign .. py:method:: map_qubit_labels(mapper) Creates a new experiment design whose circuits' qubit labels are updated according to a given mapping. Parameters ---------- mapper : dict 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 .. py:class:: 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: :py:obj:`GateSetTomographyDesign` Standard GST experiment design consisting of germ-powers sandwiched between fiducials. Parameters ---------- processorspec_filename_or_obj : QuditProcessorSpec 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` objects or the path to a filename containing them. meas_fiducial_list_or_filename : list or str A list of measurement fiducial :class:`Circuit` objects or the path to a filename containing them. germ_list_or_filename : list or str A list of germ :class:`Circuit` objects 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 :class:`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 :class:`DefaultRunner`. Create a new CircuitListsDesign object. Parameters ---------- circuit_lists : list or PlaquetteGridCircuitStructure A list whose elements are themselves lists of :class:`Circuit` objects, specifying the data that needs to be taken. Alternatively, a single :class:`PlaquetteGridCircuitStructure` object containing a sequence of circuits lists, each at a different "x" value (usually the maximum circuit depth). all_circuits_needing_data : list, 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_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). Returns ------- CircuitListsDesign .. py:attribute:: prep_fiducials :value: '[]' .. py:attribute:: meas_fiducials :value: '[]' .. py:attribute:: germs :value: '[]' .. py:attribute:: maxlengths .. py:attribute:: germ_length_limits :value: 'None' .. py:attribute:: include_lgst :value: 'True' .. py:attribute:: aliases :value: 'None' .. py:attribute:: circuit_rules :value: 'None' .. py:attribute:: truncation_method :value: "'whole germ powers'" .. py:attribute:: nested :value: 'True' .. py:attribute:: fiducial_pairs :value: 'None' .. py:attribute:: fpr_keep_fraction :value: '1' .. py:attribute:: fpr_keep_seed :value: 'None' .. py:method:: 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_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. Returns ------- StandardGSTDesign .. py:method:: map_qubit_labels(mapper) Creates a new experiment design whose circuits' qubit labels are updated according to a given mapping. Parameters ---------- mapper : dict 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 .. py:class:: 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: :py:obj:`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. .. py:attribute:: model :value: 'None' .. py:attribute:: target_model :value: 'None' .. py:attribute:: lgst_gaugeopt_tol :value: '1e-06' .. py:attribute:: contract_start_to_cptp :value: 'False' .. py:attribute:: depolarize_start :value: '0' .. py:attribute:: randomize_start :value: '0' .. py:method:: cast(obj) :classmethod: Cast `obj` to a :class:`GSTInitialModel` object. Parameters ---------- obj : object object to cast. Can be a `GSTInitialModel` (naturally) or a :class:`Model`. Returns ------- GSTInitialModel .. py:method:: retrieve_model(edesign, gaugeopt_target, dataset, comm) Retrieve the starting-point :class:`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 .. py:class:: 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: :py:obj:`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. 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_spam : bool, optional Include a SPAM budget within the wildcard budget used to process the `"wildcard"` action. wildcard_L1_weights : np.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 :class:`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"`, and `"cvxpy_noagg"`. 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. .. py:property:: wildcard1d_reference .. py:attribute:: threshold .. py:attribute:: actions :value: '()' .. py:attribute:: wildcard_budget_includes_spam :value: 'True' .. py:attribute:: wildcard_L1_weights :value: 'None' .. py:attribute:: wildcard_primitive_op_labels :value: 'None' .. py:attribute:: wildcard_initial_budget :value: 'None' .. py:attribute:: wildcard_methods :value: "('neldermead',)" .. py:attribute:: wildcard_inadmissable_action :value: "'print'" .. py:method:: cast(obj) :classmethod: Cast `obj` to a :class:`GSTBadFitOptions` object. Parameters ---------- obj : object Object to cast. Can be a `GSTBadFitOptions` (naturally) or a dictionary of constructor arguments. Returns ------- GSTBadFitOptions .. py:class:: GSTObjFnBuilders(iteration_builders, final_builders=()) Bases: :py:obj:`pygsti.baseobjs.nicelyserializable.NicelySerializable` Holds the objective-function builders needed for long-sequence GST. Parameters ---------- iteration_builders : list or tuple A list of :class:`ObjectiveFunctionBuilder` objects used (sequentially) on each GST iteration. final_builders : list or tuple, optional A list of :class:`ObjectiveFunctionBuilder` objects used (sequentially) on the final GST iteration. .. py:attribute:: iteration_builders .. py:attribute:: final_builders :value: '()' .. py:method:: cast(obj) :classmethod: Cast `obj` to a :class:`GSTObjFnBuilders` object. Parameters ---------- obj : object Object to cast. Can be a `GSTObjFnBuilders` (naturally), a dictionary of :meth:`create_from` arguments (or None), or a list or tuple of the `(iteration_builders, final_builders)` constructor arguments. Returns ------- GSTObjFnBuilders .. py:method:: create_from(objective='logl', freq_weighted_chi2=False, always_perform_mle=False, only_perform_mle=False) :classmethod: Creates a common :class:`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 .. py:class:: GSTGaugeOptSuite(gaugeopt_suite_names=None, gaugeopt_argument_dicts=None, gaugeopt_target=None) Bases: :py:obj:`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. 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_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 :func:`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. .. py:attribute:: STANDARD_SUITENAMES :value: "('stdgaugeopt', 'stdgaugeopt-unreliable2Q', 'stdgaugeopt-tt', 'stdgaugeopt-safe',..." .. py:attribute:: SPECIAL_SUITENAMES :value: "('varySpam', 'varySpamWt', 'varyValidSpamWt', 'toggleValidSpam', 'varySpam-unreliable2Q',..." .. py:attribute:: gaugeopt_target :value: 'None' .. py:method:: cast(obj) :classmethod: .. py:method:: 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 .. py:method:: 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 :meth:`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 :func:`gaugeopt_to_target` (or lists of such dictionaries for a multi-stage gauge optimization). .. py:class:: GateSetTomography(initial_model=None, gaugeopt_suite='stdgaugeopt', objfn_builders=None, optimizer=None, badfit_options=None, verbosity=2, name=None) Bases: :py:obj:`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 :class:`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 :class:`GSTObjFnBuilders` object. optimizer : Optimizer, optional The optimizer to use. Can also be anything that can be cast to a :class:`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 :class:`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. Create a new Protocol object. Parameters ---------- 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. Returns ------- Protocol .. py:attribute:: initial_model .. py:attribute:: gaugeopt_suite .. py:attribute:: badfit_options .. py:attribute:: verbosity :value: '2' .. py:attribute:: objfn_builders .. py:attribute:: profile :value: '1' .. py:attribute:: record_output :value: 'True' .. py:attribute:: distribute_method :value: "'default'" .. py:attribute:: oplabel_aliases :value: 'None' .. py:attribute:: circuit_weights :value: 'None' .. py:attribute:: unreliable_ops :value: "('Gcnot', 'Gcphase', 'Gms', 'Gcn', 'Gcx', 'Gcz')" .. py:method:: run(data, memlimit=None, comm=None, checkpoint=None, checkpoint_path=None, disable_checkpointing=False, simulator: Optional[pygsti.forwardsims.ForwardSimulator.Castable] = None) Run this protocol on `data`. Parameters ---------- data : ProtocolData The input data. memlimit : int, optional (default None) A rough per-processor memory limit in bytes. comm : mpi4py.MPI.Comm, optional (default None) When not ``None``, an MPI communicator used to run this protocol in parallel. checkpoint : GateSetTomographyCheckpoint, optional (default None) If specified use a previously generated checkpoint object to restart or warm start this run part way through. checkpoint_path : str, 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_checkpointing : bool, 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. simulator : ForwardSimulator.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 .. py:class:: LinearGateSetTomography(target_model=None, gaugeopt_suite='stdgaugeopt', badfit_options=None, verbosity=2, name=None) Bases: :py:obj:`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 :class:`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 :class:`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. Create a new Protocol object. Parameters ---------- 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. Returns ------- Protocol .. py:attribute:: target_model :value: 'None' .. py:attribute:: gaugeopt_suite .. py:attribute:: badfit_options .. py:attribute:: verbosity :value: '2' .. py:attribute:: profile :value: '1' .. py:attribute:: record_output :value: 'True' .. py:attribute:: oplabels :value: "'default'" .. py:attribute:: oplabel_aliases :value: 'None' .. py:attribute:: unreliable_ops :value: "('Gcnot', 'Gcphase', 'Gms', 'Gcn', 'Gcx', 'Gcz')" .. py:method:: check_if_runnable(data) Raises a ValueError if LGST cannot be run on data Parameters ---------- data : ProtocolData The experimental data to test for LGST-compatibility. Returns ------- None .. py:method:: run(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 .. py:class:: 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: :py:obj:`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 - "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 - : 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 :class:`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_model : Model, 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_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 :class:`GSTObjFnBuilders` object. Applies to all modes. optimizer : Optimizer, optional The optimizer to use. Can also be anything that can be case to a :class:`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 :class:`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. Create a new Protocol object. Parameters ---------- 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. Returns ------- Protocol .. py:attribute:: models_to_test :value: 'None' .. py:attribute:: target_model :value: 'None' .. py:attribute:: gaugeopt_suite .. py:attribute:: objfn_builders .. py:attribute:: optimizer .. py:attribute:: badfit_options .. py:attribute:: verbosity :value: '2' .. py:attribute:: starting_point .. py:method:: run(data, memlimit=None, comm=None, checkpoint=None, checkpoint_path=None, disable_checkpointing=False, simulator: Optional[pygsti.forwardsims.ForwardSimulator.Castable] = 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. checkpoint : StandardGSTCheckpoint, optional (default None) If specified use a previously generated checkpoint object to restart or warm start this run part way through. checkpoint_path : str, 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_checkpointing : bool, 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. simulator : ForwardSimulator.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 .. py:class:: ModelEstimateResults(data, protocol_instance, init_circuits=True) Bases: :py:obj:`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.) Attributes ---------- dataset : DataSet The underlying data set. Initialize an empty Results object. .. py:property:: dataset The underlying data set. .. py:attribute:: estimates .. py:attribute:: circuit_lists .. py:method:: from_dir(dirname, name, preloaded_data=None, quick_load=False) :classmethod: 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 :class:`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 .. py:method:: to_nameddict() Convert these results into nested :class:`NamedDict` objects. Returns ------- NamedDict .. py:method:: add_estimates(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 .. py:method:: rename_estimate(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 .. py:method:: add_estimate(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 .. py:method:: add_model_test(target_model, themodel, estimate_key='test', gaugeopt_keys='auto', verbosity=2, simulator: Optional[pygsti.forwardsims.ForwardSimulator.Castable] = None) 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. verbosity : int, optional Level of detail printed to stdout. simulator : ForwardSimulator.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 .. py:method:: 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_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 .. py:method:: copy() Creates a copy of this :class:`ModelEstimateResults` object. Returns ------- ModelEstimateResults .. py:class:: GateSetTomographyCheckpoint(mdl_list=None, last_completed_iter=-1, last_completed_circuit_list=None, final_objfn=None, name=None, parent=None) Bases: :py:obj:`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_list : list of models, optional (default None) Current list of models for each of the completed iterations of the protocol. last_completed_iter : int, optional (default -1) Index of the last iteration what was successfully completed. last_completed_circuit_list : list of Circuit objects, CircuitList or equivalent, optional (default None) A list of Circuit objects corresponding to the last iteration successfully completed. final_objfn : ModelDatasetCircuitStore, 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. name : str, 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. parent : ProtocolCheckpoint, 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. .. py:attribute:: mdl_list :value: 'None' .. py:attribute:: last_completed_iter :value: '-1' .. py:attribute:: last_completed_circuit_list :value: 'None' .. py:attribute:: final_objfn :value: 'None' .. py:class:: StandardGSTCheckpoint(modes=None, children=None, name=None) Bases: :py:obj:`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 ---------- modes : list 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. children : dict, 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. name : str, 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. .. py:property:: children .. py:attribute:: modes :value: 'None' .. py:data:: GSTDesign .. py:data:: GST .. py:data:: LGST