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. 

Returns the portion truncated by :function:`repeat_and_truncate`. 

Simplify a string representation of a circuit. 

List all the circuits in a given length range. 

Iterative version of :function:`list_all_circuits` 

List all the circuits of a given length. 

Iterative version of :function:`list_all_circuits_onelen` 

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 :function:`translate_circuit` to each element of circuits. 

Composes two alias dicts. 

Manipulates a Circuit object according to rules. 

Applies :function:`manipulate_circuit` to each element of circuits. 

Applies :function:`filter_circuit` to each element of circuits. 

Filters circuit by keeping only a subset of its "lines" (i.e. state space labels, often qubits). 
 pygsti.circuits.circuitconstruction._run_expression(str_expression, my_locals)¶
 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
args (list 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.
kwargs (dict) – 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
x (tuple or Circuit) – the operation sequence to repeat
num_times (int) – the number of times to repeat x
assert_at_least_one_rep (bool, 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
x (tuple or Circuit) – the operation sequence to repeat
max_length (int) – the maximum length
assert_at_least_one_rep (bool, 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
x (tuple or Circuit) – the operation sequence to repeat.
max_length (int) – the maximum length.
assert_at_least_one_rep (bool, 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
x (tuple or Circuit) – the operation sequence to repeat & truncate.
n (int) – the truncation length.
assert_at_least_one_rep (bool, 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._repeat_remainder_for_truncation(x, n, assert_at_least_one_rep=False)¶
Returns the portion truncated by :function:`repeat_and_truncate`.
Repeat the operation sequence x the fewest number of times such that the repeated sequence has length greater than or equal to n. Return the portion of this repeated string from the nth position to the end. Note that this corresponds to what is truncated in a call to repeate_and_truncate(x,n,assert_at_least_one_rep).
 Parameters
x (tuple or Circuit) – the operation sequence to operate on.
n (int) – the truncation length.
assert_at_least_one_rep (bool, 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 remainder operation sequence
 pygsti.circuits.circuitconstruction._simplify_circuit_string(circuit_str)¶
Simplify a string representation of a circuit.
The simplified string should evaluate to the same operation label tuple as the original.
 Parameters
circuit_str (string) – the string representation of a circuit to be simplified. (e.g. “Gx{}”, “Gy^1Gx”)
 Returns
string – the simplified string representation.
 pygsti.circuits.circuitconstruction.list_all_circuits(op_labels, minlength, maxlength)¶
List all the circuits in a given length range.
 Parameters
op_labels (tuple) – tuple of operation labels to include in circuits.
minlength (int) – the minimum circuit length to return
maxlength (int) – 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 :function:`list_all_circuits`
 Parameters
op_labels (tuple) – tuple of operation labels to include in circuits.
minlength (int) – the minimum circuit length to return
maxlength (int) – 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_labels (tuple) – tuple of operation labels to include in circuits.
length (int) – the circuit length
 Returns
list – A list of Circuit objects.
 pygsti.circuits.circuitconstruction.iter_all_circuits_onelen(op_labels, length)¶
Iterative version of :function:`list_all_circuits_onelen`
 Parameters
op_labels (tuple) – tuple of operation labels to include in circuits.
length (int) – 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_labels (list) – A list of the operation (gate) labels to form circuits from.
max_length (int) – 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_labels (tuple) – tuple of operation labels to include in circuits.
length (int) – the circuit length.
count (int) – the number of random strings to create.
seed (int, 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
circuit (tuple 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_fiducials (list of Circuits) – The preparation fiducial circuits, used to construct an informationally complete effective preparation.
meas_fiducials (list of Circuits) – The measurement fiducial circuits, used to construct an informationally complete effective measurement.
op_label_src (tuple 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
dataset (DataSet) – The data used to generate the LGST estimates
prep_fiducials (list of Circuits) – The preparation fiducial circuits, used to construct an informationally complete effective preparation.
meas_fiducials (list 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_strings (list) – 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
circuit (Circuit) – The circuit to use as the base for find & replace operations.
alias_dict (dict) – 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 :function:`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
circuits (list of Circuits) – The list of circuits to use as the base for find & replace operations.
alias_dict (dict) – 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._compose_alias_dicts(alias_dict_1, alias_dict_2)¶
Composes two alias dicts.
Assumes alias_dict_1 maps “A” labels to “B” labels and alias_dict_2 maps “B” labels to “C” labels. The returned dictionary then maps “A” labels directly to “C” labels, and satisfies:
returned[A_label] = alias_dict_2[ alias_dict_1[ A_label ] ]
 Parameters
alias_dict_1 (dict) – The first alias dictionary to compose.
alias_dict_2 (dict) – The second alias dictionary to compose.
 Returns
dict
 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
circuit (Circuit or tuple) – The circuit to manipulate.
rules (list) – 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 :function:`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
circuits (list of Circuits) – The list of circuits to use as the base for find & replace operations.
rules (list) – 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 :function:`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
circuits (list) – A list of circuits to act on.
sslbls_to_keep (list) – A list of state space labels specifying which operation labels should be retained.
new_sslbls (list, 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.
drop (bool, 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.
idle (string 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
circuit (Circuit) – The circuit to act on.
sslbls_to_keep (list) – A list of state space labels specifying which operation labels should be retained.
new_sslbls (list, 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.
idle (string or Label, optional) – The operation label to be used when there are no kept components of a “layer” (element) of circuit.
 Returns
Circuit