:py:mod:`pygsti.circuits.gstcircuits` ===================================== .. py:module:: pygsti.circuits.gstcircuits .. autoapi-nested-parse:: Circuit list creation functions using repeated-germs limited by a max-length. Module Contents --------------- Functions ~~~~~~~~~ .. autoapisummary:: pygsti.circuits.gstcircuits.make_lsgst_structs pygsti.circuits.gstcircuits.create_lsgst_circuit_lists pygsti.circuits.gstcircuits.create_lsgst_circuits pygsti.circuits.gstcircuits.create_elgst_lists pygsti.circuits.gstcircuits.create_elgst_experiment_list Attributes ~~~~~~~~~~ .. autoapisummary:: pygsti.circuits.gstcircuits.ordereddict .. py:data:: ordereddict .. py:function:: make_lsgst_structs(op_label_src, prep_strs, effect_strs, germ_list, max_length_list, fid_pairs=None, trunc_scheme='whole germ powers', nest=True, keep_fraction=1, keep_seed=None, include_lgst=True, op_label_aliases=None, sequence_rules=None, dscheck=None, action_if_missing='raise', germ_length_limits=None, verbosity=0) Deprecated function. .. py:function:: create_lsgst_circuit_lists(op_label_src, prep_fiducials, meas_fiducials, germs, max_lengths, fid_pairs=None, trunc_scheme='whole germ powers', nest=True, keep_fraction=1, keep_seed=None, include_lgst=True, op_label_aliases=None, circuit_rules=None, dscheck=None, action_if_missing='raise', germ_length_limits=None, verbosity=0) Create a set of long-sequence GST circuit lists (including structure). Constructs a series (a list) of circuit structures used by long-sequence GST (LSGST) algorithms. If `include_lgst == True` then the starting structure contains the LGST strings, otherwise the starting structure is empty. For each nonzero element of max_length_list, call it L, a set of circuits is created with the form: Case: trunc_scheme == 'whole germ powers': prep_fiducial + pygsti.circuits.repeat_with_max_length(germ,L) + meas_fiducial Case: trunc_scheme == 'truncated germ powers': prep_fiducial + pygsti.circuits.repeat_and_truncate(germ,L) + meas_fiducial Case: trunc_scheme == 'length as exponent': prep_fiducial + germ^L + meas_fiducial If nest == True, the above set is iteratively *added* (w/duplicates removed) to the current circuit structure to form a final structure for the given L. This results in successively larger structures, each of which contains all the elements of previous-L structures. If nest == False then the above set *is* the final structure for the given L. Parameters ---------- op_label_src : list or Model List of operation labels to determine needed LGST circuits. If a Model, then the model's gate and instrument labels are used. Only relevant when `include_lgst == True`. prep_fiducials : list of Circuits List of the preparation fiducial circuits, which follow state preparation. effect_fiducials : list of Circuits List of the measurement fiducial circuits, which precede measurement. germs : list of Circuits List of the germ circuits. max_lengths : list of ints List of maximum lengths. A zero value in this list has special meaning, and corresponds to the LGST circuits. fid_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) or tuples of germs and length values and values are lists of 2-tuples specifying the pairs to use for that germ. trunc_scheme : str, optional Truncation scheme used to interpret what the list of maximum lengths means. If unsure, leave as default. Allowed values are: - 'whole germ powers' -- germs are repeated an integer number of times such that the length is less than or equal to the max. - 'truncated germ powers' -- repeated germ string is truncated to be exactly equal to the max (partial germ at end is ok). - 'length as exponent' -- max. length is instead interpreted as the germ exponent (the number of germ repetitions). nest : boolean, optional If True, the returned 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 string list for maximum length == L contains *only* those circuits specified in the description above, and *not* those for previous values of L. 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 circuits will be included in all the lists. 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') circuit_rules : list, optional A list of `(find,replace)` 2-tuples which specify string replacement rules. Both `find` and `replace` are tuples of operation labels (or `Circuit` objects). dscheck : DataSet, optional A data set which is checked for each of the generated circuits. When a generated 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 generated circuit is missing from `dscheck` (only relevant when `dscheck` is not None). "raise" causes a ValueError to be raised; "drop" causes the missing circuits to be dropped from the returned set. germ_length_limits : dict, optional A dictionary limiting the max-length values used for specific germs. Keys are germ circuits 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`). verbosity : int, optional The level of output to print to stdout. Returns ------- list of PlaquetteGridCircuitStructure objects The i-th object corresponds to a circuit list containing repeated germs limited to length max_length_list[i]. If nest == True, then repeated germs limited to previous max-lengths are also included. Note that a "0" maximum-length corresponds to the LGST strings. .. py:function:: create_lsgst_circuits(op_label_src, prep_strs, effect_strs, germ_list, max_length_list, fid_pairs=None, trunc_scheme='whole germ powers', keep_fraction=1, keep_seed=None, include_lgst=True) List all the circuits (i.e. experiments) required for long-sequence GST (LSGST). Returns a single list containing, without duplicates, all the gate strings required throughout all the iterations of LSGST given by max_length_list. Thus, the returned list is equivalently the list of the experiments required to run LSGST using the supplied parameters, and so commonly used when construting data set templates or simulated data sets. The breakdown of which circuits are used for which iteration(s) of LSGST is given by create_lsgst_circuit_lists(...). Parameters ---------- op_label_src : list or Model List of operation labels to determine needed LGST strings. If a Model, then the model's gate and instrument labels are used. Only relevant when `include_lgst == True`. prep_strs : list of Circuits List of the preparation fiducial circuits, which follow state preparation. effect_strs : list of Circuits List of the measurement fiducial circuits, which precede measurement. germ_list : list of Circuits List of the germ circuits. max_length_list : list of ints List of maximum lengths. fid_pairs : list of 2-tuples, 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. trunc_scheme : str, optional Truncation scheme used to interpret what the list of maximum lengths means. If unsure, leave as default. Allowed values are: - 'whole germ powers' -- germs are repeated an integer number of times such that the length is less than or equal to the max. - 'truncated germ powers' -- repeated germ string is truncated to be exactly equal to the max (partial germ at end is ok). - 'length as exponent' -- max. length is instead interpreted as the germ exponent (the number of germ repetitions). 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* fiduicial 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 ensure that LGST sequences are included in the returned list. Returns ------- PlaquetteGridCircuitStructure .. py:function:: create_elgst_lists(op_label_src, germ_list, max_length_list, trunc_scheme='whole germ powers', nest=True, include_lgst=True) Create a set of circuit lists for eLGST based on germs and max-lengths Constructs a series (a list) of circuit lists used by the extended LGST (eLGST) algorithm. If `include_lgst == True` then the starting list is the list of length-1 operation label strings, otherwise the starting list is empty. For each nonzero element of max_length_list, call it L, a list of circuits is created with the form: Case: trunc_scheme == 'whole germ powers': pygsti.circuits.repeat_with_max_length(germ,L) Case: trunc_scheme == 'truncated germ powers': pygsti.circuits.repeat_and_truncate(germ,L) Case: trunc_scheme == 'length as exponent': germ^L If nest == True, the above list is iteratively *added* (w/duplicates removed) to the current list of circuits to form a final list for the given L. This results in successively larger lists, each of which contains all the elements of previous-L lists. If nest == False then the above list *is* the final list for the given L. Parameters ---------- op_label_src : list or Model List of operation labels to determine needed LGST strings. If a Model, then the model's gate and instrument labels are used. Only relevant when `include_lgst == True`. germ_list : list of Circuits List of the germ circuits. max_length_list : list of ints List of maximum lengths. A zero value in this list has special meaning, and corresponds to the length-1 operation label strings. trunc_scheme : str, optional Truncation scheme used to interpret what the list of maximum lengths means. If unsure, leave as default. Allowed values are: - 'whole germ powers' -- germs are repeated an integer number of times such that the length is less than or equal to the max. - 'truncated germ powers' -- repeated germ string is truncated to be exactly equal to the max (partial germ at end is ok). - 'length as exponent' -- max. length is instead interpreted as the germ exponent (the number of germ repetitions). nest : boolean, optional If True, the returned 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 string list for maximum length == L contains *only* those circuits specified in the description above, and *not* those for previous values of L. include_lgst : boolean, optional If true, then the starting list (only applicable when `nest == True`) is the list of length-1 operation label strings rather than the empty list. This means that when `nest == True`, the length-1 sequences will be included in all the lists. Returns ------- list of (lists of Circuits) The i-th list corresponds to a circuit list containing repeated germs limited to length max_length_list[i]. If nest == True, then repeated germs limited to previous max-lengths are also included. Note that a "0" maximum-length corresponds to the gate label strings. .. py:function:: create_elgst_experiment_list(op_label_src, germ_list, max_length_list, trunc_scheme='whole germ powers', include_lgst=True) List of all the circuits (i.e. experiments) required for extended LGST (eLGST). Returns a single list containing, without duplicates, all the gate strings required throughout all the iterations of eLGST given by max_length_list. Thus, the returned list is equivalently the list of the experiments required to run eLGST using the supplied parameters, and so commonly used when construting data set templates or simulated data sets. The breakdown of which circuits are used for which iteration(s) of eLGST is given by create_elgst_lists(...). Parameters ---------- op_label_src : list or Model List of operation labels to determine needed LGST strings. If a Model, then the model's gate and instrument labels are used. Only relevant when `include_lgst == True`. germ_list : list of Circuits List of the germ circuits. max_length_list : list of ints List of maximum lengths. A zero value in this list has special meaning, and corresponds to the length-1 operation label strings. trunc_scheme : str, optional Truncation scheme used to interpret what the list of maximum lengths means. If unsure, leave as default. Allowed values are: - 'whole germ powers' -- germs are repeated an integer number of times such that the length is less than or equal to the max. - 'truncated germ powers' -- repeated germ string is truncated to be exactly equal to the max (partial germ at end is ok). - 'length as exponent' -- max. length is instead interpreted as the germ exponent (the number of germ repetitions). include_lgst : boolean, optional If true, then ensure that length-1 sequences are included in the returned list. Returns ------- list of Circuits