pygsti.circuits.gstcircuits
¶
Circuit list creation functions using repeatedgerms limited by a maxlength.
Module Contents¶
Functions¶

Create a set of circuit lists for LSGST based on germs and maxlengths. 

Deprecated function. 

Create a set of longsequence GST circuit lists (including structure). 

List all the circuits (i.e. experiments) required for longsequence GST (LSGST). 

Create a set of circuit lists for eLGST based on germs and maxlengths 

List of all the circuits (i.e. experiments) required for extended LGST (eLGST). 

 pygsti.circuits.gstcircuits._create_raw_lsgst_lists(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, germ_length_limits=None)¶
Create a set of circuit lists for LSGST based on germs and maxlengths.
Constructs a series (a list) of circuit lists used by longsequence GST (LSGST) algorithms. If include_lgst == True then the starting list is the list of LGST 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’:
prepStr + pygsti.circuits.repeat_with_max_length(germ,L) + effectStr
 Case: trunc_scheme == ‘truncated germ powers’:
prepStr + pygsti.circuits.repeat_and_truncate(germ,L) + effectStr
 Case: trunc_scheme == ‘length as exponent’:
prepStr + germ^L + effectStr
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 previousL 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.
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. A zero value in this list has special meaning, and corresponds to the LGST sequences.
fid_pairs (list of 2tuples 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) 2tuple 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 2tuples 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 circuits 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.
keep_fraction (float, optional) – The fraction of fiducial pairs selected for each germpower base string. The default includes all fiducial pairs. Note that for each germpower the selected pairs are different random sets of all possible pairs (unlike fid_pairs, which specifies the same fiducial pairs for all samegerm 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.
germ_length_limits (dict, optional) – A dictionary limiting the maxlength 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 maxlengths of 1, 2, and 4 (whereas other germs use all the values in max_length_list).
 Returns
list of (lists of Circuits) – The ith 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 maxlengths are also included. Note that a “0” maximumlength corresponds to the LGST strings.
 pygsti.circuits.gstcircuits.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.
 pygsti.circuits.gstcircuits.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 longsequence GST circuit lists (including structure).
Constructs a series (a list) of circuit structures used by longsequence 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 previousL 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 2tuples 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) 2tuple 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 2tuples 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 germpower base string. The default includes all fiducial pairs. Note that for each germpower the selected pairs are different random sets of all possible pairs (unlike fid_pairs, which specifies the same fiducial pairs for all samegerm 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) 2tuples 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 maxlength 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 maxlengths 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 ith 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 maxlengths are also included. Note that a “0” maximumlength corresponds to the LGST strings.
 pygsti.circuits.gstcircuits.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 longsequence 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 2tuples, 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) 2tuple 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 2tuples 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 germpower base string. The default includes all fiducial pairs. Note that for each germpower the selected pairs are different random sets of all possible pairs (unlike fid_pairs, which specifies the same fiduicial pairs for all samegerm 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
 pygsti.circuits.gstcircuits.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 maxlengths
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 length1 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 previousL 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 length1 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 length1 operation label strings rather than the empty list. This means that when nest == True, the length1 sequences will be included in all the lists.
 Returns
list of (lists of Circuits) – The ith 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 maxlengths are also included. Note that a “0” maximumlength corresponds to the gate label strings.
 pygsti.circuits.gstcircuits.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 length1 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 length1 sequences are included in the returned list.
 Returns
list of Circuits
 pygsti.circuits.gstcircuits._get_trunc_function(trunc_scheme)¶