pygsti.circuits.gstcircuits

Circuit list creation functions using repeated-germs limited by a max-length.

Module Contents

Functions

_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 max-lengths.

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.

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).

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).

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

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).

_get_trunc_function(trunc_scheme)

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 max-lengths.

Constructs a series (a list) of circuit lists used by long-sequence 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 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.

  • 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 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.

  • 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 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.

  • 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).

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 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 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) 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.

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

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 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.

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

pygsti.circuits.gstcircuits._get_trunc_function(trunc_scheme)