pygsti.circuits.circuitconstruction

Utility functions for creating and acting on lists of circuits.

Module Contents

Functions

_run_expression(str_expression, my_locals)

create_circuits(*args, **kwargs)

Create a list of circuits using a nested loop.

repeat(x, num_times, assert_at_least_one_rep=False)

Repeat x num_times times.

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.

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.

repeat_and_truncate(x, n, assert_at_least_one_rep=False)

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

_repeat_remainder_for_truncation(x, n, assert_at_least_one_rep=False)

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

_simplify_circuit_string(circuit_str)

Simplify a string representation of a circuit.

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 :function:`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 :function:`list_all_circuits_onelen`

list_all_circuits_without_powers_and_cycles(op_labels, max_length)

List all distinct aperiodic circuits up to a maximum length.

list_random_circuits_onelen(op_labels, length, count, seed=None)

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, op_label_src)

List the circuits required for running LGST.

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.

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.

translate_circuit(circuit, alias_dict)

Translates circuit according to the aliases in alias_dict.

translate_circuits(circuits, alias_dict)

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

_compose_alias_dicts(alias_dict_1, alias_dict_2)

Composes two alias dicts.

manipulate_circuit(circuit, rules, line_labels='auto')

Manipulates a Circuit object according to rules.

manipulate_circuits(circuits, rules, line_labels='auto')

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

filter_circuits(circuits, sslbls_to_keep, new_sslbls=None, drop=False, idle=())

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

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

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 inner-loop 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 repeated-then-truncated 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 n-th 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 sub-circuits 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 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
  • 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) 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 :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) 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 :function:`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
  • 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 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.

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