pygsti.circuits.circuitconstruction
Utility functions for creating and acting on lists of circuits.
Module Contents
Functions

Create a list of circuits using a nested loop. 

Repeat x num_times times. 

The maximum number of times x can be repeated such that its length is <= max_length. 

Repeat the x an integer number of times such that the result has length <= max_length. 

Repeat and truncate x to yield a sequence with exactly length n. 

List all the circuits in a given length range. 

Iterative version of 

List all the circuits of a given length. 

Iterative version of 

List all distinct aperiodic circuits up to a maximum length. 

Create a list of random circuits of a given length. 

List the partial subcircuits of circuit. 

List the circuits required for running LGST. 

Compute the circuits that LGST is able to estimate from dataset and sets of fiducials. 

Converts a list of operation label tuples or strings to a list of 

Translates circuit according to the aliases in alias_dict. 

Applies 

Manipulates a Circuit object according to rules. 

Applies 

Applies 

Filters circuit by keeping only a subset of its "lines" (i.e. state space labels, often qubits). 
 pygsti.circuits.circuitconstruction.create_circuits(*args, **kwargs)
Create a list of circuits using a nested loop.
Positional arguments specify evaluation strings, which are evaluated within the innerloop for a nested loop over all list or tuple type keyword arguments.
Parameters
 argslist of strings
Positional arguments are strings that python can evaluate into either a tuple of operation labels or a Circuit instance. If evaluation raises an AssertionError (an assert statement fails) then that inner loop evaluation is skipped and list construction proceeds.
 kwargsdict
keys specify variable names that can be used in positional argument strings.
Returns
list of Circuit
Examples
>>> from pygsti.circuits import create_circuits >>> As = [('a1',), ('a2',)] >>> Bs = [('b1',), ('b2',)] >>> list1 = create_circuits('a', 'a+b', a=As, b=Bs) >>> print(list(map(str, list1))) ['a1', 'a2', 'a1b1', 'a1b2', 'a2b1', 'a2b2']
You can change the order in which the different iterables are advanced.
>>> list2 = create_circuits('a+b', a=As, b=Bs, order=['a', 'b']) >>> print(list(map(str, list2))) ['a1b1', 'a1b2', 'a2b1', 'a2b2'] >>> list3 = create_circuits('a+b', a=As, b=Bs, order=['b', 'a']) >>> print(list(map(str, list3))) ['a1b1', 'a2b1', 'a1b2', 'a2b2']
 pygsti.circuits.circuitconstruction.repeat(x, num_times, assert_at_least_one_rep=False)
Repeat x num_times times.
Parameters
 xtuple or Circuit
the operation sequence to repeat
 num_timesint
the number of times to repeat x
 assert_at_least_one_repbool, optional
if True, assert that num_times > 0. This can be useful when used within a create_circuits inner loop to build a operation sequence lists where a string must be repeated at least once to be added to the list.
Returns
tuple or Circuit (whichever x was)
 pygsti.circuits.circuitconstruction.repeat_count_with_max_length(x, max_length, assert_at_least_one_rep=False)
The maximum number of times x can be repeated such that its length is <= max_length.
Parameters
 xtuple or Circuit
the operation sequence to repeat
 max_lengthint
the maximum length
 assert_at_least_one_repbool, optional
if True, assert that number of repetitions is > 0. This can be useful when used within a create_circuits inner loop to build a operation sequence lists where a string must be repeated at least once to be added to the list.
Returns
 int
the number of repetitions.
 pygsti.circuits.circuitconstruction.repeat_with_max_length(x, max_length, assert_at_least_one_rep=False)
Repeat the x an integer number of times such that the result has length <= max_length.
Parameters
 xtuple or Circuit
the operation sequence to repeat.
 max_lengthint
the maximum length.
 assert_at_least_one_repbool, optional
if True, assert that number of repetitions is > 0. This can be useful when used within a create_circuits inner loop to build a operation sequence lists where a string must be repeated at least once to be added to the list.
Returns
 tuple or Circuit (whichever x was)
the repeated operation sequence
 pygsti.circuits.circuitconstruction.repeat_and_truncate(x, n, assert_at_least_one_rep=False)
Repeat and truncate x to yield a sequence with exactly length n.
Repeats x so the result has length greater than n, then truncates it to have exactly length n.
Parameters
 xtuple or Circuit
the operation sequence to repeat & truncate.
 nint
the truncation length.
 assert_at_least_one_repbool, optional
if True, assert that number of repetitions is > 0. This is always the case when x has length > 0.
Returns
 tuple or Circuit (whichever x was)
the repeatedthentruncated operation sequence
 pygsti.circuits.circuitconstruction.list_all_circuits(op_labels, minlength, maxlength)
List all the circuits in a given length range.
Parameters
 op_labelstuple
tuple of operation labels to include in circuits.
 minlengthint
the minimum circuit length to return
 maxlengthint
the maximum circuit length to return
Returns
 list
A list of Circuit objects.
 pygsti.circuits.circuitconstruction.iter_all_circuits(op_labels, minlength, maxlength)
Iterative version of
list_all_circuits()
Parameters
 op_labelstuple
tuple of operation labels to include in circuits.
 minlengthint
the minimum circuit length to return
 maxlengthint
the maximum circuit length to return
 pygsti.circuits.circuitconstruction.list_all_circuits_onelen(op_labels, length)
List all the circuits of a given length.
Parameters
 op_labelstuple
tuple of operation labels to include in circuits.
 lengthint
the circuit length
Returns
 list
A list of Circuit objects.
 pygsti.circuits.circuitconstruction.iter_all_circuits_onelen(op_labels, length)
Iterative version of
list_all_circuits_onelen()
Parameters
 op_labelstuple
tuple of operation labels to include in circuits.
 lengthint
the circuit length
 pygsti.circuits.circuitconstruction.list_all_circuits_without_powers_and_cycles(op_labels, max_length)
List all distinct aperiodic circuits up to a maximum length.
That is, list all sequences that are not a shorter gate sequence raised to a power, and are also distinct up to cycling (e.g. (‘Gx’,’Gy’,’Gy’) and (‘Gy’,’Gy’,’Gx’) are considered equivalent and only one would be included in the returned list).
Parameters
 op_labelslist
A list of the operation (gate) labels to form circuits from.
 max_lengthint
The maximum length strings to return. Circuits from length 1 to max_length will be returned.
Returns
 list
Of
Circuit
objects.
 pygsti.circuits.circuitconstruction.list_random_circuits_onelen(op_labels, length, count, seed=None)
Create a list of random circuits of a given length.
Parameters
 op_labelstuple
tuple of operation labels to include in circuits.
 lengthint
the circuit length.
 countint
the number of random strings to create.
 seedint, optional
If not None, a seed for numpy’s random number generator.
Returns
 list of Circuits
A list of random circuits as Circuit objects.
 pygsti.circuits.circuitconstruction.list_partial_circuits(circuit)
List the partial subcircuits of circuit.
The “parital circuits” are defined as the slices circuit[0:n] for 0 <= n <= len(circuit).
Parameters
 circuittuple of operation labels or Circuit
The circuit to act upon.
Returns
 list of Circuit objects.
The parial circuits.
 pygsti.circuits.circuitconstruction.create_lgst_circuits(prep_fiducials, meas_fiducials, op_label_src)
List the circuits required for running LGST.
Parameters
 prep_fiducialslist of Circuits
The preparation fiducial circuits, used to construct an informationally complete effective preparation.
 meas_fiducialslist of Circuits
The measurement fiducial circuits, used to construct an informationally complete effective measurement.
 op_label_srctuple or Model
List/tuple of operation labels OR a Model whose gate and instrument labels should be used.
Returns
 list of Circuit objects
The list of required circuits, without duplicates.
 pygsti.circuits.circuitconstruction.list_circuits_lgst_can_estimate(dataset, prep_fiducials, meas_fiducials)
Compute the circuits that LGST is able to estimate from dataset and sets of fiducials.
Here “estimate a circuit” means that LGST can estimate the process matrix associated with that circuit.
Parameters
 datasetDataSet
The data used to generate the LGST estimates
 prep_fiducialslist of Circuits
The preparation fiducial circuits, used to construct an informationally complete effective preparation.
 meas_fiducialslist of Circuits
The measurement fiducial circuits, used to construct an informationally complete effective measurement.
Returns
 list of lists of tuples
each list of tuples specifyies a circuit that LGST can estimate.
 pygsti.circuits.circuitconstruction.to_circuits(list_of_op_label_tuples_or_strings, line_labels='auto')
Converts a list of operation label tuples or strings to a list of
Circuit
objects.Parameters
 list_of_op_label_tuples_or_stringslist
List which may contain a mix of Circuit objects, tuples of gate labels, and strings in standardtextformat.
 line_labels“auto” or tuple, optional
The line labels to use when creating Circuit objects from nonCircuit elements of list_of_op_label_tuples_or_strings. If “auto” then the line labels are determined automatically based on the linelabels which are present in the layer labels.
Returns
 list of Circuit objects
Each item of list_of_op_label_tuples_or_strings converted to a Circuit.
 pygsti.circuits.circuitconstruction.translate_circuit(circuit, alias_dict)
Translates circuit according to the aliases in alias_dict.
Creates a new
Circuit
object from an existing one by replacing operation labels in circuit by (possibly multiple) new labels according to alias_dict.Parameters
 circuitCircuit
The circuit to use as the base for find & replace operations.
 alias_dictdict
A dictionary whose keys are single operation labels and whose values are lists or tuples of the new operation labels that should replace that key. If alias_dict is None then circuit is returned.
Returns
Circuit
 pygsti.circuits.circuitconstruction.translate_circuits(circuits, alias_dict)
Applies
translate_circuit()
to each element of circuits.Creates a new list of Circuit objects from an existing one by replacing operation labels in circuits by (possibly multiple) new labels according to alias_dict.
Parameters
 circuitslist of Circuits
The list of circuits to use as the base for find & replace operations.
 alias_dictdict
A dictionary whose keys are single operation labels and whose values are lists or tuples of the new operation labels that should replace that key. If alias_dict is None then circuits is returned.
Returns
list of Circuits
 pygsti.circuits.circuitconstruction.manipulate_circuit(circuit, rules, line_labels='auto')
Manipulates a Circuit object according to rules.
Each element of rules is of the form (find,replace), and specifies a replacement rule. For example, (‘A’,), (‘B’,’C’) simply replaces each A with B,C. (‘A’, ‘B’), (‘A’, ‘B2’)) replaces B with B2 when it follows A. (‘B’, ‘A’), (‘B2’, ‘A’)) replaces B with B2 when it precedes A.
Parameters
 circuitCircuit or tuple
The circuit to manipulate.
 ruleslist
A list of (find,replace) 2tuples which specify the replacement rules. Both find and replace are tuples of operation labels (or Circuit objects). If rules is None then circuit is returned.
 line_labels“auto” or tuple, optional
The line labels to use when creating a the output Circuit objects. If “auto” then the line labels are determined automatically based on the linelabels which are present in the corresponding layer labels.
Returns
list of Circuits
 pygsti.circuits.circuitconstruction.manipulate_circuits(circuits, rules, line_labels='auto')
Applies
manipulate_circuit()
to each element of circuits.This creates a new list of Circuit objects from an existing one by performing replacements according to rules (see
manipulate_circuit()
).Parameters
 circuitslist of Circuits
The list of circuits to use as the base for find & replace operations.
 ruleslist
A list of (find,replace) 2tuples which specify the replacement rules. Both find and replace are tuples of operation labels (or Circuit objects). If rules is None then circuits is returned.
 line_labels“auto” or tuple, optional
The line labels to use when creating output Circuit objects. If “auto” then the line labels are determined automatically based on the linelabels which are present in the corresponding layer labels.
Returns
list of Circuits
 pygsti.circuits.circuitconstruction.filter_circuits(circuits, sslbls_to_keep, new_sslbls=None, drop=False, idle=())
Applies
filter_circuit()
to each element of circuits.Removes any labels from circuits whose statespace labels are not entirely in sslbls_to_keep. If a gates label’s statespace labels (its .sslbls) is None, then the label is retained in the returned string.
Furthermore, by specifying new_sslbls one can map the statespace labels in sslbls_to_keep to new labels (useful for “rebasing” a set of qubit strings.
Parameters
 circuitslist
A list of circuits to act on.
 sslbls_to_keeplist
A list of state space labels specifying which operation labels should be retained.
 new_sslblslist, optional
If not None, a list of the same length as sslbls_to_keep specifying a new set of state space labels to replace those in sslbls_to_keep.
 dropbool, optional
If True, then nonempty circuits which become empty after filtering are not included in (i.e. dropped from) the returned list. If False, then the returned list is always the same length as the input list.
 idlestring or Label, optional
The operation label to be used when there are no kept components of a “layer” (element) of a circuit.
Returns
 list
A list of Circuits
 pygsti.circuits.circuitconstruction.filter_circuit(circuit, sslbls_to_keep, new_sslbls=None, idle=())
Filters circuit by keeping only a subset of its “lines” (i.e. state space labels, often qubits).
Removes any labels from circuit whose statespace labels are not entirely in sslbls_to_keep. If a gates label’s statespace labels (its .sslbls) is None, then the label is retained in the returned string.
Furthermore, by specifying new_sslbls one can map the statespace labels in sslbls_to_keep to new labels (useful for “rebasing” a set of qubit strings.
Parameters
 circuitCircuit
The circuit to act on.
 sslbls_to_keeplist
A list of state space labels specifying which operation labels should be retained.
 new_sslblslist, optional
If not None, a list of the same length as sslbls_to_keep specifying a new set of state space labels to replace those in sslbls_to_keep.
 idlestring or Label, optional
The operation label to be used when there are no kept components of a “layer” (element) of circuit.
Returns
Circuit