pygsti.circuits.circuitconstruction

Utility functions for creating and acting on lists of circuits.

Module Contents

Functions

create_circuits(*args, **kwargs)

Create a list of circuits using a nested loop.

repeat(x, num_times[, assert_at_least_one_rep])

Repeat x num_times times.

repeat_count_with_max_length(x, max_length[, ...])

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

repeat_with_max_length(x, max_length[, ...])

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

repeat_and_truncate(x, n[, assert_at_least_one_rep])

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

list_all_circuits(op_labels, minlength, maxlength)

List all the circuits in a given length range.

iter_all_circuits(op_labels, minlength, maxlength)

Iterative version of list_all_circuits()

list_all_circuits_onelen(op_labels, length)

List all the circuits of a given length.

iter_all_circuits_onelen(op_labels, length)

Iterative version of list_all_circuits_onelen()

list_all_circuits_without_powers_and_cycles(op_labels, ...)

List all distinct aperiodic circuits up to a maximum length.

list_random_circuits_onelen(op_labels, length, count)

Create a list of random circuits of a given length.

list_partial_circuits(circuit)

List the partial sub-circuits of circuit.

create_lgst_circuits(prep_fiducials, meas_fiducials, ...)

List the circuits required for running LGST.

list_circuits_lgst_can_estimate(dataset, ...)

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

to_circuits(list_of_op_label_tuples_or_strings[, ...])

Converts a list of operation label tuples or strings to a list of Circuit objects.

translate_circuit(circuit, alias_dict)

Translates circuit according to the aliases in alias_dict.

translate_circuits(circuits, alias_dict)

Applies translate_circuit() to each element of circuits.

manipulate_circuit(circuit, rules[, line_labels])

Manipulates a Circuit object according to rules.

manipulate_circuits(circuits, rules[, line_labels])

Applies manipulate_circuit() to each element of circuits.

filter_circuits(circuits, sslbls_to_keep[, ...])

Applies filter_circuit() to each element of circuits.

filter_circuit(circuit, sslbls_to_keep[, new_sslbls, idle])

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