Twirl¶

class trueq.Twirl(twirl=None, labels=None, dim=None)¶

A dictionary-like container mapping qubit labels to the corresponding twirling groups. Twirls are used in benchmarking protocols, e.g. cycle benchmarking (CB) and k-body noise reconstruction (KNR), or in randomized compiling (RC) to generate random twirling gates from specific groups in order to create dressed cycles.

Currently supported twirling groups are: "P" (Pauli), "C" (Clifford), "U" (unitary), or "I" (identity). Warning: "I" is provided as a convenience method for expert users to identify coherent errors and/or crosstalk even though an exponential decay is not expected.

The easiest way to initialize a twirl is to specify a twirling group and the labels on which this group will act. This will result in a “homogenous” twirl, i.e. one that contains a single twirling group acting on all labels:

import trueq as tq

tq.Twirl("C", (0, (1, 2)))

Twirl({(0,): 'C', (1, 2): 'C'}, dim=2)

If you specify a single-qubit twirling group, see SINGLE_QUDIT_GROUPS, any multi-qubit labels passed to the constructor will be automatically broken up into single-qubit labels:

import trueq as tq

twirl1 = tq.Twirl("P", (0, (1, 2)))
twirl2 = tq.Twirl("P", (0, 1, 2))

twirl1, twirl2

(Twirl({(0,): 'P', (1,): 'P', (2,): 'P'}, dim=2),
 Twirl({(0,): 'P', (1,): 'P', (2,): 'P'}, dim=2))

If you want to initialize a twirl with single-qubit Cliffords, regardless whether or not your cycle or labels contain multi-qubit gates, you can use the shorthand "C1" twirling group for convenience:

import trueq as tq

tq.Twirl("C1", (0, (1, 2)))

Twirl({(0,): 'C', (1,): 'C', (2,): 'C'}, dim=2)

The dimension of each subsystem in the twirling group can be specified, otherwise a default value will be used:

import trueq as tq

tq.Twirl("C", (0, (1, 2)), dim=3)

# the default dim can be specified for many trueq objects with set_dim()
tq.settings.set_dim(3)
assert tq.Twirl("C", 0).dim == 3
tq.settings.set_dim(2)

A more explicit way of initializing a twirl is to pass it a dictionary mapping qubit labels to the corresponding twirling groups:

import trueq as tq

tq.Twirl({0: "C", (1, 2): "C"})

Twirl({(0,): 'C', (1, 2): 'C'}, dim=2)

Initializing a twirl with a dictionary allows you to specify “mixed” twirls, i.e. ones that contain multiple twirling groups acting on distinct labels:

import trueq as tq

tq.Twirl({(0, 1): "C", (2, 3): "U", 4: "P"})

Twirl({(0, 1): 'C', (2, 3): 'U', (4,): 'P'}, dim=2)

If you specify a permutation invariant twirling group, e.g. Clifford or U, the subsystem labels will be automatically sorted upon construction:

import trueq as tq

twirl1 = tq.Twirl({(0, 1): "C", (2, 3): "U"})
twirl2 = tq.Twirl({(1, 0): "C", (3, 2): "U"})

twirl1, twirl2

(Twirl({(0, 1): 'C', (2, 3): 'U'}, dim=2),
 Twirl({(0, 1): 'C', (2, 3): 'U'}, dim=2))

Parameters

twirl (dict | str) – Either a dictionary mapping qubit labels to the corresponding twirling groups or a string representing a single twirling group acting on all labels. If twirl and labels are None, then an empty twirl is instantiated.
labels (Iterable) – The labels on which the twirling group is acting. Specify this only if twirl is given a str.
dim – The dimension of the individual subsystems to twirl over. The default value None results in the output of get_dim().
dim – int | NoneType

INVARIANT_GROUPS = {'C', 'I', 'P', 'U'}¶: The set of group strings that are permutation invariant, i.e. the group strings for which qubit label orders do not matter.

SINGLE_QUDIT_GROUPS = {'I', 'P'}¶: The set of group strings that always result in tensor products of single-qudit groups.

static from_dict(dic)¶

Returns a Twirl constructed from a dictionary representation.

Parameters: dic (dict) – A dictionary used to construct a new twirl.
Return type: Twirl

property dim¶

The dimension of the individual subsystems to twirl over.

Type: int

property groups¶

The set of all twirling groups in this twirl.

Type: set

property is_mixed¶

Whether or not this twirl is mixed, i.e. True if there is only one unique twirling group present (length of groups is greater than one) or False otherwise.

Type: bool

issubset(other)¶

Checks if this twirl has the same dimension and is a subset of another twirl.

Parameters: other (Twirl) – Another Twirl instance.
Return type: bool

items()¶

Returns the key-value pairs of this twirl.

Return type: generator

property labels¶

The sorted union of all system labels in this twirl.

Type: tuple

labels_intersect(other)¶

Checks if any system labels in this twirl intersect with the labels of another twirl.

Parameters: other (Twirl) – Another Twirl instance.
Return type: bool

pretty(max_chars=50)¶

Converts this twirl into a pretty string representation.

Parameters: max_chars (int) – The maximum length of the output.
Return type: str

property n_sys¶

The number of qubits in this twirl.

Type: int

to_dict()¶

Returns a dictionary representation of this twirl.

Return type: dict

union(other)¶

Returns a new Twirl instance which is the union of this twirl and another twirl.

Parameters

other (Twirl) – Another Twirl instance.

Return type

Twirl

Raises

ValueError – If this twirl has any intersecting labels with another twirl.
ValueError – If the twirls have different dimensions.