pygsti.circuits.gstcircuits.create_lsgst_circuit_lists

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 conjunction 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:

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.

Return type:

list of PlaquetteGridCircuitStructure objects