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. Iftwirl
andlabels
areNone
, then an empty twirl is instantiated.labels (
Iterable
) – The labels on which the twirling group is acting. Specify this only iftwirl
is given astr
.dim (
int
|NoneType
) – The dimension of the individual subsystems to twirl over, which must be one ofSMALL_PRIMES
. The default value ofNone
will result in the default dimension obtained fromget_dim()
.
- 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:
- 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 ofgroups
is greater than one) orFalse
otherwise.- Type:
bool
- issubset(other)
Checks if this twirl has the same dimension and is a subset of another twirl.
- 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.
- 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, enforce_disjoint=True)
Returns a new
Twirl
instance which is the union of this twirl and another twirl.- Parameters:
- Return type:
- Raises:
ValueError – If
enforce_disjoint=True
and there are any overlapping labels between the two twirls.ValueError – If
enforce_disjoint=False
and there are items in the other twirl not contained in this twirl, but which overlaps the labels of this twirl.ValueError – If the twirls have different dimensions.