Twirl

class trueq.Twirl(twirl=None, labels=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), "SU" (special 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 on. 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'})

If you specify a single-qubit twirling group, e.g. Pauli, 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'}),
 Twirl({(0,): 'P', (1,): 'P', (2,): 'P'}))

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'})

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): "SU", 4: "P"})
Twirl({(0, 1): 'C', (2, 3): 'SU', (4,): 'P'})

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

import trueq as tq

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

twirl1, twirl2
(Twirl({(0, 1): 'C', (2, 3): 'SU'}), Twirl({(0, 1): 'C', (2, 3): 'SU'}))
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 on. Specify this only if twirl is given a str.

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 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 this twirl is a subset of another twirl.

Parameters

other (Twirl) – Another Twirl instance.

Return type

bool

items()

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