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 sub-circuits 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 inner-loop 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 repeated-then-truncated 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 sub-circuits 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 standard-text-format.
- line_labels“auto” or tuple, optional
The line labels to use when creating Circuit objects from non-Circuit elements of list_of_op_label_tuples_or_strings. If “auto” then the line labels are determined automatically based on the line-labels 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) 2-tuples 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 line-labels 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) 2-tuples 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 line-labels 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 state-space labels are not entirely in sslbls_to_keep. If a gates label’s state-space labels (its .sslbls) is None, then the label is retained in the returned string.
Furthermore, by specifying new_sslbls one can map the state-space labels in sslbls_to_keep to new labels (useful for “re-basing” 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 non-empty 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 state-space labels are not entirely in sslbls_to_keep. If a gates label’s state-space labels (its .sslbls) is None, then the label is retained in the returned string.
Furthermore, by specifying new_sslbls one can map the state-space labels in sslbls_to_keep to new labels (useful for “re-basing” 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