Protocols

trueq.make_cb

Generates a CircuitCollection to estimate the process fidelity of one or more cycles using cycle benchmarking (CB).

trueq.make_crosstalk_diagnostics

Generates a CircuitCollection to measure the discrepancy between gate quality while applying gates simultaneously versus while applying gates in an isolated way to each individual system.

trueq.make_irb

Generates a CircuitCollection to estimate the process fidelity of specific gates using (simultaneous) interleaved randomized benchmarking (IRB).

trueq.make_knr

Generates a CircuitCollection to estimate the probabilities of all errors acting on all sets of subsystems targeted by a combination of k gates using k-body noise reconstruction (KNR).

trueq.make_nox

Generates a CircuitCollection to perform Noiseless Output Extrapolation (NOX) and estimate the correct outputs of the input circuit.

trueq.make_qcap

Generates a CircuitCollection to measure the quantum capacity (QCAP) bound of any circuit whose marked cycles are contained in cycles.

trueq.make_rcal

Generates a CircuitCollection to measure the readout errors on the provided system labels.

trueq.make_sc

Generates a CircuitCollection to optimize the fidelity of one or more cycles using stochastic calibration (SC).

trueq.make_srb

Generates a CircuitCollection to estimate the process fidelity of random gates from a group using (simultaneous) streamlined randomized benchmarking (SRB).

trueq.make_xrb

Generates a CircuitCollection to study how coherent the errors in random gates are using (simultaneous) extended randomized benchmarking (XRB).

trueq.qcap_bound

Computes the quantum capacity (QCAP) bound of the given circuit.

trueq.randomly_compile

Randomly compiles the given circuit into many new random circuits which implement the same algorithm.

Make CB

trueq.make_cb(cycles, n_random_cycles, n_circuits=30, n_decays=20, targeted_errors=None, twirl=None, propagate_correction=False, compiled_pauli=True)

Generates a CircuitCollection to estimate the process fidelity of one or more cycles using cycle benchmarking (CB). See the CB guide for more information.

import trueq as tq

# generate a circuit collection to run CB on the 0th qubit, with 30 circuits,
# for each length in [4, 20] and each with 3 randomly chosen Pauli decay strings
circuits = tq.make_cb({0: tq.Gate.x}, [4, 20], 30, 3)

# draw the first circuit
circuits[0].draw()
0 Key: twirl: Paulis on [0] cycles: (Cycle((0,): Gate.x),) protocol: CB analyze_decays: X_Z_I compiled_pauli: X n_random_cycles: 4 measurement_basis: X Labels: (0,) Name: Gate.h Aliases: Gate.h Gate.f Gate.cliff12 Generators: Z: -127.28 X: -127.28 0.71 0.71 0.71 -0.71 H 1 Labels: (0,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (0,) Name: Gate.z Aliases: Gate.z Gate.cliff3 Generators: Z: 180.00 1.00 -1.00 Z 2 Labels: (0,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (0,) Name: Gate.y Aliases: Gate.y Gate.cliff2 Generators: Y: -180.00 1.00 -1.00 Y 3 Labels: (0,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (0,) Name: Gate.id Aliases: Gate.id Gate.i Gate.cliff0 Locally Equivalent: Identity Generators: I: 0.00 1.00 1.00 ID 4 Labels: (0,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (0,) Name: Gate.h Aliases: Gate.h Gate.f Gate.cliff12 Generators: Z: -127.28 X: -127.28 0.71 0.71 0.71 -0.71 H 5 Labels: (0,) Name: Meas M
Parameters

  • cycles (Iterable | Cycle | dict) – The cycles which specify the subcircuit to benchmark.

  • n_random_cycles (Iterable) – A list of positive integers specifying how many random cycles will be generated during the protocol, e.g. [4, 20].

  • n_circuits (int) – The number of circuits for each number of random cycles.

  • n_decays (int) – An integer specifying the total number of randomly chosen Pauli decay strings used to measure the process infidelity or the probability of each error. Warning: Setting this value lower than min(20, 4 ** n_qubits - 1) may result in a biased estimate of the process fidelity, and setting this value lower than min(40, 4 ** n_qubits - 1) may result in a biased estimate of the probability for non-identity errors.

  • targeted_errors (NoneType | Weyls | Iterable | str) – A Weyls instance, where each row specifies an error to measure. The identity Pauli will always be added to the list of errors (or be the sole target if None is the argument), which corresponds to measuring the process fidelity of the cycle. For convenience, a list of strings can be given, e.g. ["XII", "ZZY"], which will be used to instantiate a Weyls object.

  • twirl (Twirl | str) – The Twirl to use in this protocol. You can also specify a twirling group (default is "P") that will be used to automatically instantiate a twirl based on the labels in the given cycles.

  • propagate_correction (bool) – Whether to propagate correction gates to the end of the circuit or compile them into neighbouring cycles. Warning: this can result in arbitrary multi-qubit gates at the end of the circuit!

  • compiled_pauli (bool | str | Weyls) – Controls whether or not to compile a random Pauli gate onto each qubit in the cycle preceding a measurement operation (default is True). Also accepts a specific Weyls instance (or, for convenience, its string constructor argument) to compile into every circuit. In any case, every returned circuit will store a Weyls instance in the keyattribute specifying which Pauli was compiled into the circuit.

Returns

A collection of CB circuits.

Return type

CircuitCollection

Crosstalk Diagnostics

trueq.make_crosstalk_diagnostics(labels, n_random_cycles, n_circuits=30, subsets=None, include_xrb=True)

Generates a CircuitCollection to measure the discrepancy between gate quality while applying gates simultaneously versus while applying gates in an isolated way to each individual system. See the CTD guide for more information.

This discrepancy is assessed by running SRB simultaneously on the specified systems, as well as running it on each system in turn. Optionally, and True by default, the coherence of crosstalk errors is assessed using XRB. Therefore, this function is equivalent to concatenating the circuits from multiple calls to make_srb() (and optionally make_xrb()) with different label configurations.

import trueq as tq

# generate a circuit collection to run crosstalk diagnostics in single qubit
# mode for qubits 5, 6, 7, and 8
circuits = tq.make_crosstalk_diagnostics([5, 6, 7, 8], [4, 100])

# reduce the number of circuits to perform by excluding XRB circuits
# this means we cannot distinguish between coherent errors (due to static
# crosstalk) and incoherent errors (due to fluctuating crosstalk)
circuits = tq.make_crosstalk_diagnostics(
    [5, 6, 7, 8], [4, 100], include_xrb=False
)

# we can also twirl some pairs of systems using entangling gates
circuits = tq.make_crosstalk_diagnostics(
    [5, [6, 7], 8], [4, 100], include_xrb=False
)

# using the subsets option, we can customize exactly which subsets of the full
# simultaneous twirl are performed in isolation. Here, the default value would
# have resulted in subsets [[5],[6],[[7, 8]]]
circuits = tq.make_crosstalk_diagnostics(
    [5, 6, [7, 8]], [4, 100], include_xrb=False, subsets=[[5], [5, 6], [[7, 8]]]
)
Parameters

  • labels (Iterable | Twirl) – A list specifying sets of system labels to be twirled simultaneously by Clifford gates in each circuit, e.g. [3, [1, 2], 4] for mixed single and two-qubit twirling. By default (see subsets), each set of these system labels is also twirled in isolation. For advanced usage, this argument can also be a Twirl instance.

  • n_random_cycles (Iterable) – A list of positive integers specifying how many random cycles will be generated during the protocol, e.g. [6, 20].

  • n_circuits (int) – The number of circuits for at each n_random_cycles for each protocol.

  • subsets (Iterable) – A list of subsets of the given labels (or labels of the twirl) to be used. The default value of None results in each subset being a member of the given labels. See the last example above.

  • include_xrb (bool) – Whether to include XRB circuits in the output.

Returns

A collection of circuits to diagnose crosstalk.

Return type

CircuitCollection

Make IRB

trueq.make_irb(cycles, n_random_cycles, n_circuits=30, twirl=None, propagate_correction=False, compiled_pauli=True)

Generates a CircuitCollection to estimate the process fidelity of specific gates using (simultaneous) interleaved randomized benchmarking (IRB). See the IRB guide for more information.

import trueq as tq

# generate a circuit collection to run single qubit IRB on an X gate acting on
# qubit 0, with 30 random circuits for each circuit length in [5, 40, 60, 100]
circuits = tq.make_irb({0: tq.Gate.x}, [5, 40, 60, 100], 30)

# next, generate circuits to run IRB on a cycle with an X gate acting on qubit 0
# and a CZ gate on qubits (2, 3), with 20 random circuits at each circuit length
circuits = tq.make_irb({0: tq.Gate.x, (2, 3): tq.Gate.cz}, [2, 100], 20)

# finding the Pauli matrix compiled into the first circuit
print(circuits[0].key.compiled_pauli)

# draw the first circuit
circuits[0].draw()

IXZ
0 2 3 Key: twirl: Cliffords on [0, (2, 3)] cycles: (Cycle((0,): Gate.x, (2, 3): Gate.cz),) protocol: IRB compiled_pauli: IXZ n_random_cycles: 2 measurement_basis: ZZZ Labels: (0,) Name: Gate.cliff21 Aliases: Gate.cliff21 Generators: Y: -69.28 X: 69.28 Z: 69.28 0.71 0.71 -0.71j 0.71j 21 Labels: (2, 3) Name: Gate Locally Equivalent: CNOT Generators: XY: -69.28 XZ: -69.28 IX: -69.28 0.50 0.50j 0.50j 0.50 0.50j 0.50 -0.50 -0.50j 0.50j 0.50 0.50 0.50j -0.50 -0.50j 0.50j 0.50 1 Labels: (0,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (2, 3) Name: Gate.cz Aliases: Gate.cz Locally Equivalent: CNOT Generators: ZZ: -90.00 ZI: 90.00 IZ: 90.00 1.00 1.00 1.00 -1.00 CZ CZ Labels: (0,) Name: Gate.cliff8 Aliases: Gate.cliff8 Generators: Z: 270.00 -1.00j -1.00 8 Labels: (2, 3) Name: Gate Locally Equivalent: CNOT Generators: ZX: 127.28 YI: 127.28 0.50 -0.50j -0.50 -0.50j 0.50 -0.50j -0.50 -0.50j 0.50 0.50j -0.50 0.50j 0.50 0.50j -0.50 0.50j 2 Labels: (0,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (2, 3) Name: Gate.cz Aliases: Gate.cz Locally Equivalent: CNOT Generators: ZZ: -90.00 ZI: 90.00 IZ: 90.00 1.00 1.00 1.00 -1.00 CZ CZ Labels: (0,) Name: Gate.h Aliases: Gate.h Gate.f Gate.cliff12 Generators: X: 127.28 Z: 127.28 -0.71 -0.71 -0.71 0.71 H Labels: (2, 3) Name: Gate Locally Equivalent: CNOT Generators: ZX: 180.00 YY: -63.64 IX: 63.64 ZI: -63.64 XZ: 63.64 XY: 45.00 YZ: -45.00 -0.50 -0.50j -0.50j 0.50 -0.50j -0.50 -0.50 0.50j 0.50 0.50j -0.50j 0.50 -0.50j -0.50 0.50 -0.50j 3 Labels: (0,) Name: Meas M Labels: (2,) Name: Meas M Labels: (3,) Name: Meas M

Note

We invert each random sequence up to an independent random Pauli matrix (accessible as shown in the example above) to diagnose errors to that are missed by always returning to the initial state [1].

Warning

The estimate of the process fidelity obtained by taking the ratio of the process fidelities from IRB and SRB is subject to a large systematic uncertainty that is typically not reported. This systematic uncertainty arises because of the many ways in which the noise in the twirling group can combine with the noise in the interleaved gates. Both the standard interleaved estimate and the systematic uncertainty are automatically computed by fit if the circuit collection contains SRB circuits. The systematic uncertainty can be reduced if the circuit collection also contains XRB circuits.

Parameters

  • cycles (Iterable | Cycle | dict) – The cycles which specify the subcircuit to benchmark.

  • n_random_cycles (Iterable) – A list of positive integers specifying how many random cycles will be generated during the protocol, e.g. [6, 20].

  • n_circuits (int) – The number of circuits for each number of random cycles.

  • twirl (Twirl | str) – The Twirl to use in this protocol. You can also specify a twirling group (default is "C") that will be used to automatically instantiate a twirl based on the labels in the given cycles.

  • propagate_correction (bool) – Whether to propagate correction gates to the end of the circuit or compile them into neighbouring cycles. Warning: this can result in arbitrary multi-qubit gates at the end of the circuit!

  • compiled_pauli (bool | str | Weyls) – Controls whether or not to compile a random Pauli gate onto each qubit in the cycle preceding a measurement operation (default is True). Also accepts a specific Weyls instance (or, for convenience, its string constructor argument) to compile into every circuit. In any case, every returned circuit will store a Weyls instance in the keyattribute specifying which Pauli was compiled into the circuit.

Returns

A collection of IRB circuits.

Return type

CircuitCollection

Make KNR

trueq.make_knr(cycles, n_random_cycles, n_circuits=30, subsystems=1, twirl=None, propagate_correction=False, compiled_pauli=True)

Generates a CircuitCollection to estimate the probabilities of all errors acting on all sets of subsystems targeted by a combination of k gates using k-body noise reconstruction (KNR). See the KNR guide for more information.

For example, if the input cycle is {0: tq.Gate.id, (1, 3): tq.Gate.cnot, 2: tq.Gate.x} and subsystems=2, then data will be present to reconstruct any Pauli error rate on the subsystems [0, 1, 3], [0, 2], [1, 2, 3] (and any subsystems thereof, e.g. [1, 2] but not [0, 1, 2]).

import trueq as tq

# generate a circuit collection to reconsturct two-body marginal
# error distributions
# on a 4-qubit device using 30 circuits for each length in [6, 20]
# and for each Pauli subspace in a set of log2(4) subspaces
circuits = tq.make_knr({j: tq.Gate.x for j in range(4)}, [6, 20], 30)

# draw the first circuit
circuits[0].draw()
0 1 2 3 Key: twirl: Paulis on [0, 1, 2, 3] cycles: (Cycle((0,): Gate.x, (1,): Gate.x, (2,): Gate.x, (3,): Gate.x),) protocol: KNR subsystems: ((0,), (1,), (2,), (3,)) compiled_pauli: XXYX n_random_cycles: 6 measurement_basis: XXZZ Labels: (0,) Name: Gate.cliff6 Aliases: Gate.cliff6 Generators: Y: -90.00 0.71 0.71 -0.71 0.71 6 Labels: (1,) Name: Gate.sy Aliases: Gate.sy Gate.cliff7 Generators: Y: 90.00 0.71 -0.71 0.71 0.71 SY Labels: (2,) Name: Gate.id Aliases: Gate.id Gate.i Gate.cliff0 Locally Equivalent: Identity Generators: I: 0.00 1.00 1.00 ID Labels: (3,) Name: Gate.y Aliases: Gate.y Gate.cliff2 Generators: Y: -180.00 1.00 -1.00 Y 1 Labels: (0,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (1,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (2,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (3,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (0,) Name: Gate.y Aliases: Gate.y Gate.cliff2 Generators: Y: -180.00 1.00 -1.00 Y Labels: (1,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (2,) Name: Gate.id Aliases: Gate.id Gate.i Gate.cliff0 Locally Equivalent: Identity Generators: I: 0.00 1.00 1.00 ID Labels: (3,) Name: Gate.id Aliases: Gate.id Gate.i Gate.cliff0 Locally Equivalent: Identity Generators: I: 0.00 1.00 1.00 ID 2 Labels: (0,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (1,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (2,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (3,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (0,) Name: Gate.y Aliases: Gate.y Gate.cliff2 Generators: Y: -180.00 1.00 -1.00 Y Labels: (1,) Name: Gate.y Aliases: Gate.y Gate.cliff2 Generators: Y: -180.00 1.00 -1.00 Y Labels: (2,) Name: Gate.y Aliases: Gate.y Gate.cliff2 Generators: Y: -180.00 1.00 -1.00 Y Labels: (3,) Name: Gate.id Aliases: Gate.id Gate.i Gate.cliff0 Locally Equivalent: Identity Generators: I: 0.00 1.00 1.00 ID 3 Labels: (0,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (1,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (2,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (3,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (0,) Name: Gate.y Aliases: Gate.y Gate.cliff2 Generators: Y: -180.00 1.00 -1.00 Y Labels: (1,) Name: Gate.z Aliases: Gate.z Gate.cliff3 Generators: Z: 180.00 -1.00 1.00 Z Labels: (2,) Name: Gate.id Aliases: Gate.id Gate.i Gate.cliff0 Locally Equivalent: Identity Generators: I: 0.00 1.00 1.00 ID Labels: (3,) Name: Gate.id Aliases: Gate.id Gate.i Gate.cliff0 Locally Equivalent: Identity Generators: I: 0.00 1.00 1.00 ID 4 Labels: (0,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (1,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (2,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (3,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (0,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (1,) Name: Gate.id Aliases: Gate.id Gate.i Gate.cliff0 Locally Equivalent: Identity Generators: I: 0.00 1.00 1.00 ID Labels: (2,) Name: Gate.id Aliases: Gate.id Gate.i Gate.cliff0 Locally Equivalent: Identity Generators: I: 0.00 1.00 1.00 ID Labels: (3,) Name: Gate.id Aliases: Gate.id Gate.i Gate.cliff0 Locally Equivalent: Identity Generators: I: 0.00 1.00 1.00 ID 5 Labels: (0,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (1,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (2,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (3,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (0,) Name: Gate.y Aliases: Gate.y Gate.cliff2 Generators: Y: -180.00 1.00 -1.00 Y Labels: (1,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (2,) Name: Gate.y Aliases: Gate.y Gate.cliff2 Generators: Y: -180.00 1.00 -1.00 Y Labels: (3,) Name: Gate.z Aliases: Gate.z Gate.cliff3 Generators: Z: 180.00 -1.00 1.00 Z 6 Labels: (0,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (1,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (2,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (3,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (0,) Name: Gate.sy Aliases: Gate.sy Gate.cliff7 Generators: Y: 90.00 0.71 -0.71 0.71 0.71 SY Labels: (1,) Name: Gate.cliff6 Aliases: Gate.cliff6 Generators: Y: -90.00 0.71 0.71 -0.71 0.71 6 Labels: (2,) Name: Gate.y Aliases: Gate.y Gate.cliff2 Generators: Y: -180.00 1.00 -1.00 Y Labels: (3,) Name: Gate.id Aliases: Gate.id Gate.i Gate.cliff0 Locally Equivalent: Identity Generators: I: 0.00 1.00 1.00 ID 7 Labels: (0,) Name: Meas M Labels: (1,) Name: Meas M Labels: (2,) Name: Meas M Labels: (3,) Name: Meas M

Note

The number of returned circuits scales mildly with the number of total systems but exponentially with the value of subsystems.

Note

Currently, this function can only benchmark a single cycle.

Parameters

  • cycles (Iterable | Cycle | dict) – The cycles which specify the subcircuit to benchmark.

  • n_random_cycles (Iterable) – A list of positive integers specifying how many random cycles will be generated during the protocol, e.g. [6, 20].

  • n_circuits (int) – The number of circuits for each number of random cycles.

  • subsystems (Iterable | :py:class`~trueq.Subsystems` | int) – A list of labels of combinations of gate-bodies to reconstruct the marginal probabilities for, which can be specified using a Subsystems object. Also accepts a positive integer to instantiate all combinations of gate bodies with up to and including that many elements.

  • twirl (Twirl | str) – The Twirl to use in this protocol. You can also specify a twirling group (default is "P") that will be used to automatically instantiate a twirl based on the labels in the given cycles.

  • propagate_correction (bool) – Whether to propagate correction gates to the end of the circuit or compile them into neighbouring cycles. Warning: this can result in arbitrary multi-qubit gates at the end of the circuit!

  • compiled_pauli (bool | str | Weyls) – Controls whether or not to compile a random Pauli gate onto each qubit in the cycle preceding a measurement operation (default is True). Also accepts a specific Weyls instance (or, for convenience, its string constructor argument) to compile into every circuit. In any case, every returned circuit will store a Weyls instance in the keyattribute specifying which Pauli was compiled into the circuit.

Returns

A collection of KNR circuits.

Return type

CircuitCollection

Make NOX

trueq.make_nox(circuit, n_identities=1, n_marked=None, max_rep=2, n_compilations=30, twirl='P')

Generates a CircuitCollection to perform Noiseless Output Extrapolation (NOX) and estimate the correct outputs of the input circuit. See the NOX guide for more information.

If circuit contains marked Cycles, it uses identity insertion to amplify the noise afflicting these marked Cycles; otherwise, it marks every Cycle containing multi-qubit or multi-qudit gates, then it amplifies their noise with identity insertion. If a marked Cycle \(U\) has order \(d < \textrm{max_rep}\), identity insertion is performed via repetition, meaning that \(U\) is replaced by \(U^{dN_\textrm{id}+1}\), where \(N_\textrm{id}\) is the input n_identities; otherwise, it is performed via inversion by replacing \(U\) with \(U(U^{-1}U)^{N_\textrm{id}}\). Setting \(\textrm{max_rep}=0\) ensures that identity insertion is always performed via inversion; conversely, setting \(\textrm{max_rep}\) value higher than the order of all the marked cycles ensures that it is always performed via repetition.

import trueq as tq

circuit = tq.Circuit()
circuit += tq.Cycle({(0): tq.Gate.h})
circuit += tq.Cycle({(0, 1): tq.Gate.cx, (2): tq.Gate.h}, marker=1)
circuit += tq.Cycle({(1, 2): tq.Gate.cz}, marker=2)
circuit += tq.Cycle({(0): tq.Gate.x})
circuit += tq.Cycle({(1): tq.Gate.s})
circuit += tq.Cycle({(0, 3): tq.Gate.iswap, (2): tq.Gate.h}, marker=3)
circuit.measure_all()

circuits = tq.make_nox(circuit, n_identities=1, max_rep=2)

# bare circuit (no identity is inserted)
example_circ0 = circuits.subset(amplification=())[0]

# circuit that amplifies the noise afflicting the first marked cycle
# since cx and h have order 2, identity insertion is performed via repetition
example_circ1 = circuits.subset(amplification=((1, 3),))[0]

# circuit that amplifies the noise afflicting the second marked cycle
# since cz has order 2, identity insertion is performed via repetition
example_circ2 = circuits.subset(amplification=((2, 3),))[0]

# circuit that amplifies the noise afflicting the third marked cycle
# since iswap has order 4, identity insertion is performed via inversion
example_circ3 = circuits.subset(amplification=((3, 3),))[0]
example_circ3.draw()
0 1 2 3 Key: twirl: Paulis on [0, 1, 2, 3] n_marked: 3 protocol: RC seq_label: 899990566 mitigation: ('NOX',) amplification: ((3, 3),) measurement_basis: ZZZZ Labels: (0,) Name: Gate.sy Aliases: Gate.sy Gate.cliff7 Generators: Y: 90.00 0.71 -0.71 0.71 0.71 SY Labels: (1,) Name: Gate.z Aliases: Gate.z Gate.cliff3 Generators: Z: 180.00 1.00 -1.00 Z Labels: (2,) Name: Gate.id Aliases: Gate.id Gate.i Gate.cliff0 Locally Equivalent: Identity Generators: I: 0.00 1.00 1.00 ID Labels: (3,) Name: Gate.z Aliases: Gate.z Gate.cliff3 Generators: Z: 180.00 1.00 -1.00 Z 1 Labels: (0, 1) Name: Gate.cx Aliases: Gate.cx Gate.cnot Locally Equivalent: CNOT Generators: ZX: -90.00 IX: 90.00 ZI: 90.00 1.00 1.00 1.00 1.00 CX CX Labels: (2,) Name: Gate.h Aliases: Gate.h Gate.f Gate.cliff12 Generators: Z: 127.28 X: 127.28 0.71 0.71 0.71 -0.71 H Labels: (0,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (1,) Name: Gate.y Aliases: Gate.y Gate.cliff2 Generators: Y: -180.00 1.00 -1.00 Y Labels: (2,) Name: Gate.y Aliases: Gate.y Gate.cliff2 Generators: Y: -180.00 1.00 -1.00 Y Labels: (3,) Name: Gate.y Aliases: Gate.y Gate.cliff2 Generators: Y: -180.00 1.00 -1.00 Y 2 Labels: (1, 2) Name: Gate.cz Aliases: Gate.cz Locally Equivalent: CNOT Generators: ZZ: -90.00 ZI: 90.00 IZ: 90.00 1.00 1.00 1.00 -1.00 CZ CZ Labels: (0,) Name: Gate.y Aliases: Gate.y Gate.cliff2 Generators: Y: -180.00 1.00 -1.00 Y Labels: (1,) Name: Gate.cliff10 Aliases: Gate.cliff10 Generators: Y: 127.28 X: 127.28 -1.00j 1.00 10 Labels: (2,) Name: Gate.z Aliases: Gate.z Gate.cliff3 Generators: Z: 180.00 1.00 -1.00 Z Labels: (3,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X 3 Labels: (0, 3) Name: Gate.iswap Aliases: Gate.iswap Locally Equivalent: iSWAP Generators: YY: -90.00 XX: -90.00 1.00 1.00j 1.00j 1.00 IS IS Labels: (2,) Name: Gate.h Aliases: Gate.h Gate.f Gate.cliff12 Generators: Z: 127.28 X: 127.28 0.71 0.71 0.71 -0.71 H Labels: (0,) Name: Gate.y Aliases: Gate.y Gate.cliff2 Generators: Y: -180.00 1.00 -1.00 Y Labels: (1,) Name: Gate.y Aliases: Gate.y Gate.cliff2 Generators: Y: -180.00 1.00 -1.00 Y Labels: (2,) Name: Gate.y Aliases: Gate.y Gate.cliff2 Generators: Y: -180.00 1.00 -1.00 Y Labels: (3,) Name: Gate.z Aliases: Gate.z Gate.cliff3 Generators: Z: 180.00 1.00 -1.00 Z 4 Labels: (0, 3) Name: Gate Locally Equivalent: iSWAP Generators: YY: 90.00 XX: 90.00 1.00 -1.00j -1.00j 1.00 Labels: (2,) Name: Gate.h Aliases: Gate.h Gate.f Gate.cliff12 Generators: Z: 127.28 X: 127.28 0.71 0.71 0.71 -0.71 H Labels: (0,) Name: Gate.y Aliases: Gate.y Gate.cliff2 Generators: Y: -180.00 1.00 -1.00 Y Labels: (1,) Name: Gate.y Aliases: Gate.y Gate.cliff2 Generators: Y: -180.00 1.00 -1.00 Y Labels: (2,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (3,) Name: Gate.z Aliases: Gate.z Gate.cliff3 Generators: Z: 180.00 1.00 -1.00 Z 5 Labels: (0, 3) Name: Gate.iswap Aliases: Gate.iswap Locally Equivalent: iSWAP Generators: YY: -90.00 XX: -90.00 1.00 1.00j 1.00j 1.00 IS IS Labels: (2,) Name: Gate.h Aliases: Gate.h Gate.f Gate.cliff12 Generators: Z: 127.28 X: 127.28 0.71 0.71 0.71 -0.71 H Labels: (0,) Name: Gate.y Aliases: Gate.y Gate.cliff2 Generators: Y: -180.00 1.00 -1.00 Y Labels: (1,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (2,) Name: Gate.y Aliases: Gate.y Gate.cliff2 Generators: Y: -180.00 1.00 -1.00 Y Labels: (3,) Name: Gate.y Aliases: Gate.y Gate.cliff2 Generators: Y: -180.00 1.00 -1.00 Y 6 Labels: (0,) Name: Meas M Labels: (1,) Name: Meas M Labels: (2,) Name: Meas M Labels: (3,) Name: Meas M

Note

To achieve the best performance, we recommend performing identity insertion via repetition. We also recommend targeting circuits that contain multi-qubit and multi-qudit gates whose order is small, such as CX and CZ gates for qubits (order 2) and qutrits (order 3).

Parameters

  • circuit (Circuit) – The target circuit.

  • n_identities (int) – The number of identities appended with identity insertion.

  • n_marked (int | NoneType) – The number of marked cycles whose noise is amplified via identity insertion. The cycles are chosen by sampling at random without repetition, and their noise is amplified separately in different circuits. Default is None and leads to exhaustive sampling.

  • max_rep (int) – The highest number of repetitions allowed for identity insertion. If a hard cycle has order \(d < \textrm{max_rep}\), identity insertion is performed via repetition; otherwise, it is performed via inversion. Default is 2.

  • n_compilations (int) – The number of random compilations applied to each circuit via randomly_compile(). Each instance will appear as a new circuit in the returned circuit collection. If n_compilations=0, the circuits in the returned collection do not contain random gates. Default is 30.

  • twirl (Twirl | str) – The Twirl to use in this protocol when n_compilations>0. Specifying a twirling group will automatically initialize a twirl based on the labels in the given cycles. Default is "P".

Returns

A collection of NOX circuits.

Return type

CircuitCollection

Make RCAL

trueq.make_rcal(labels, batch=None, dim=None)

Generates a CircuitCollection to measure the readout errors on the provided system labels. These circuits contain \(I\) and \(X\) gates. See RCAL guide for more information.

Parameters

  • labels (Iterable) – A list of the system labels whose readout errors are to be estimated.

  • batch (NoneType | int) – A unique identifier for these calibration circuits. Other circuits which are to be calibrated based on these circuits’ results in particular should set their trueq.Circuit.key batch attribute to the same value.

  • dim (int | NoneType) – The dimension of the individual subsystems. The default value None results in the output of get_dim().

Returns

A circuit collection to measure the readout errors on the provided system labels.

Return type

trueq.CircuitCollection

Make SC

trueq.make_sc(cycles, n_random_cycles, n_circuits=30, pauli_decays=None, twirl=None, propagate_correction=False, compiled_pauli=True)

Generates a CircuitCollection to optimize the fidelity of one or more cycles using stochastic calibration (SC). See the SC guide for more information.

import trueq as tq

# generate a circuit collection to run SC on the 0th qubit, with 30 circuits,
# for each length in [4, 20] and each with a Pauli decay string "Z"
circuits = tq.make_sc({0: tq.Gate.x}, [4, 20], 30, "Z")

# draw the first circuit
circuits[0].draw()
0 Key: twirl: Paulis on [0] cycles: (Cycle((0,): Gate.x),) protocol: SC analyze_decays: Z compiled_pauli: Z n_random_cycles: 4 measurement_basis: Z Labels: (0,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X 1 Labels: (0,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (0,) Name: Gate.z Aliases: Gate.z Gate.cliff3 Generators: Z: 180.00 1.00 -1.00 Z 2 Labels: (0,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (0,) Name: Gate.y Aliases: Gate.y Gate.cliff2 Generators: Y: -180.00 1.00 -1.00 Y 3 Labels: (0,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (0,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X 4 Labels: (0,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (0,) Name: Gate.y Aliases: Gate.y Gate.cliff2 Generators: Y: -180.00 1.00 -1.00 Y 5 Labels: (0,) Name: Meas M
Parameters

  • cycles (Iterable | Cycle | dict) – The cycles which specify the subcircuit to benchmark.

  • n_random_cycles (Iterable) – A list of positive integers specifying how many random cycles will be generated during the protocol, e.g. [6, 20].

  • n_circuits (int) – The number of circuits for each number of random cycles.

  • pauli_decays (Weyls | Iterable) – A Weyls instance, where the rows specify which elements of the diagonalized error channel should be estimated. These should be chosen to anticommute with the Hamiltonian terms of a known noise source to be optimized. As a convenience, a list of strings can be given, e.g. ["XII", "ZZY"], which will be used to instantiate a Weyls object.

  • twirl (Twirl | str) – The Twirl to use in this protocol. You can also specify a twirling group (default is "P") that will be used to automatically instantiate a twirl based on the labels in the given cycles.

  • propagate_correction (bool) – Whether to propagate correction gates to the end of the circuit or compile them into neighbouring cycles. Warning: this can result in arbitrary multi-qubit gates at the end of the circuit!

  • compiled_pauli (bool | str | Weyls) – Controls whether or not to compile a random Pauli gate onto each qubit in the cycle preceding a measurement operation (default is True). Also accepts a specific Weyls instance (or, for convenience, its string constructor argument) to compile into every circuit. In any case, every returned circuit will store a Weyls instance in the keyattribute specifying which Pauli was compiled into the circuit.

Returns

A collection of SC circuits.

Return type

CircuitCollection

Make SRB

trueq.make_srb(labels, n_random_cycles, n_circuits=30, compiled_pauli=True)

Generates a CircuitCollection to estimate the process fidelity of random gates from a group using (simultaneous) streamlined randomized benchmarking (SRB). See the SRB guide for more information.

import trueq as tq

# generate a circuit collection to run single qubit SRB on qubit 5
circuits = tq.make_srb([5], [4, 200], 30)

# generate a circuit collection to run simultaneous one-qubit SRB on qubits
# 2 and 7 and two-qubit SRB on the pairs [0, 1] and [4, 9]
circuits = tq.make_srb([[0, 1], 2, 7, [4, 9]], [4, 200], 30)

# finding the Pauli matrix compiled into the first circuit
print(circuits[0].key.compiled_pauli)

# draw the first circuit
circuits[0].draw()

XXZIYZ
0 1 2 4 7 9 Key: twirl: Cliffords on [(0, 1), 2, (4, 9), 7] protocol: SRB compiled_pauli: XXZIYZ n_random_cycles: 4 measurement_basis: ZZZZZZ 1 Labels: (0, 1) Name: Gate Locally Equivalent: CNOT Generators: XY: 60.00 IY: -60.00 YI: 60.00 YX: -60.00 XI: -60.00 IX: -60.00 IZ: -34.64 ... 0.50 -0.50j 0.50j -0.50 0.50 -0.50j -0.50j 0.50 0.50 0.50j 0.50j 0.50 -0.50 -0.50j 0.50j 0.50 Labels: (2,) Name: Gate.y Aliases: Gate.y Gate.cliff2 Generators: Y: -180.00 1.00 -1.00 Y Labels: (4, 9) Name: Gate Locally Equivalent: CNOT Generators: YI: 90.00 YX: -63.64 YY: -63.64 IY: 63.64 IX: 63.64 IZ: -45.00 YZ: -45.00 0.50 -0.50j -0.50j 0.50 0.50 -0.50j 0.50j -0.50 0.50j -0.50 0.50 -0.50j -0.50j 0.50 0.50 -0.50j Labels: (7,) Name: Gate.cliff16 Aliases: Gate.cliff16 Generators: X: -69.28 Z: -69.28 Y: -69.28 0.71 0.71 0.71j -0.71j 16 2 Labels: (0, 1) Name: Gate Locally Equivalent: iSWAP Generators: YY: -61.25 IY: 61.25 ZX: 61.25 YZ: -61.25 ZY: -61.25 IX: -37.85 ZZ: 37.85 ... 0.71 0.71 0.71j -0.71j -0.71 -0.71 -0.71j 0.71j Labels: (2,) Name: Gate.sy Aliases: Gate.sy Gate.cliff7 Generators: Y: 90.00 0.71 -0.71 0.71 0.71 SY Labels: (4, 9) Name: Gate Locally Equivalent: CNOT Generators: YY: -73.48 ZZ: 73.48 YZ: 73.48 YI: -73.48 ZY: -73.48 ZI: 73.48 XY: 34.64 ... 0.50 -0.50j 0.50 0.50j -0.50 0.50j 0.50 0.50j -0.50 0.50j -0.50 -0.50j 0.50 -0.50j -0.50 -0.50j Labels: (7,) Name: Gate.s Aliases: Gate.s Gate.sz Gate.cliff9 Generators: Z: 90.00 1.00 1.00j S 3 Labels: (0, 1) Name: Gate Locally Equivalent: iSWAP Generators: XZ: -69.28 XI: -69.28 ZY: -69.28 XX: -69.28 YY: -69.28 IY: 69.28 0.35 0.35j -0.35 -0.35j -0.35 0.35j 0.35 -0.35j -0.35 -0.35j 0.35 0.35j -0.35 0.35j 0.35 -0.35j -0.35 0.35j -0.35 0.35j -0.35 -0.35j -0.35 -0.35j -0.35 0.35j -0.35 0.35j 0.35 0.35j 0.35 0.35j Labels: (2,) Name: Gate.sy Aliases: Gate.sy Gate.cliff7 Generators: Y: 90.00 0.71 -0.71 0.71 0.71 SY Labels: (4, 9) Name: Gate Locally Equivalent: CNOT Generators: IZ: -180.00 YZ: -69.28 XI: -69.28 ZZ: 69.28 0.50 0.50j -0.50 0.50j 0.50 -0.50j 0.50 0.50j -0.50 -0.50j -0.50 0.50j 0.50 -0.50j -0.50 -0.50j Labels: (7,) Name: Gate.cliff8 Aliases: Gate.cliff8 Generators: Z: -90.00 1.00 -1.00j 8 4 Labels: (0, 1) Name: Gate Locally Equivalent: iSWAP Generators: ZI: 73.48 XY: 73.48 XI: 73.48 IX: 73.48 YZ: 73.48 ZY: -73.48 ZZ: 34.64 ... -0.35 -0.35j 0.35 -0.35j -0.35 -0.35j -0.35 0.35j -0.35 -0.35j 0.35 -0.35j 0.35 0.35j 0.35 -0.35j 0.35 -0.35j -0.35 -0.35j -0.35 0.35j -0.35 -0.35j 0.35 -0.35j -0.35 -0.35j 0.35 -0.35j 0.35 0.35j Labels: (2,) Name: Gate.cliff14 Aliases: Gate.cliff14 Generators: Z: 127.28 Y: 127.28 0.71 -0.71j 0.71j -0.71 14 Labels: (4, 9) Name: Gate Locally Equivalent: CNOT Generators: XY: 103.92 XZ: -103.92 ZI: 103.92 YZ: 34.64 YY: 34.64 IX: -34.64 0.35 -0.35j 0.35 0.35j -0.35 0.35j -0.35 -0.35j 0.35 0.35j 0.35 -0.35j 0.35 0.35j 0.35 -0.35j -0.35 0.35j -0.35 -0.35j -0.35 0.35j -0.35 -0.35j 0.35 0.35j 0.35 -0.35j -0.35 -0.35j -0.35 0.35j Labels: (7,) Name: Gate.sx Aliases: Gate.sx Gate.cliff5 Generators: X: 90.00 0.71 -0.71j -0.71j 0.71 SX 5 Labels: (0, 1) Name: Gate Locally Equivalent: iSWAP Generators: XI: 63.64 IX: -63.64 ZZ: -63.64 YX: 63.64 XZ: -63.64 YY: 63.64 IY: 63.64 ... 0.71j 0.71j 0.71 -0.71 -0.71j -0.71j -0.71 0.71 Labels: (2,) Name: Gate.sx Aliases: Gate.sx Gate.cliff5 Generators: X: 90.00 0.71 -0.71j -0.71j 0.71 SX Labels: (4, 9) Name: Gate Locally Equivalent: iSWAP Generators: ZX: 127.28 XI: 127.28 IX: -69.28 XY: 69.28 XZ: -69.28 0.71 -0.71j -0.71j 0.71 0.71 0.71j -0.71j -0.71 Labels: (7,) Name: Gate.cliff10 Aliases: Gate.cliff10 Generators: X: 127.28 Y: 127.28 -1.00j 1.00 10 6 Labels: (0,) Name: Meas M Labels: (1,) Name: Meas M Labels: (2,) Name: Meas M Labels: (4,) Name: Meas M Labels: (7,) Name: Meas M Labels: (9,) Name: Meas M

Note

We invert each random sequence up to an independent random Pauli matrix (accessible as shown in the example above) to diagnose errors to that are missed by always returning to the initial state [1].

Parameters

  • labels (Iterable | Twirl) – A list specifying sets of system labels to be twirled together by Clifford gates in each circuit, e.g. [3, [1, 2], 4] for mixed single and two-qubit twirling. Or, for advanced usage, a Twirl instance.

  • n_random_cycles (Iterable) – A list of positive integers specifying how many random cycles will be generated during the protocol, e.g. [6, 20].

  • n_circuits (int) – The number of circuits for each number of random cycles.

  • compiled_pauli (bool | str | Weyls) – Controls whether or not to compile a random Pauli gate onto each qubit in the cycle preceding a measurement operation (default is True). Also accepts a specific Weyls instance (or, for convenience, its string constructor argument) to compile into every circuit. In any case, every returned circuit will store a Weyls instance in the keyattribute specifying which Pauli was compiled into the circuit.

Returns

A collection of SRB circuits.

Return type

CircuitCollection

Make XRB

trueq.make_xrb(labels, n_random_cycles, n_circuits=30)

Generates a CircuitCollection to study how coherent the errors in random gates are using (simultaneous) extended randomized benchmarking (XRB). See the XRB guide for more information.

import trueq as tq

# generate circuit collections to run XRB on a single qubit (qubit 0), with
# 30 random circuits for each length in [4, 50, 500]
circuits = tq.make_xrb([0], [4, 50, 500], 30)

# generate circuit collections to run two-qubit XRB on qubit pair [5, 6], with
# 50 random circuits for each length in [3, 150]
circuits = tq.make_xrb([[5, 6]], [3, 150], 50)

# generate a circuit collection to run simultaneous one-qubit XRB on [5, 6, 7]
# with 30 random circuits for each length in [5, 10, 100]
circuits = tq.make_xrb([5, 6, 7], [5, 10, 100], 30)

# generate a circuit collection to run simultaneous one-qubit XRB on qubit 5,
# and two-qubit XRB on qubits [1, 2], with 15 random circuits for each circuit
# length in [4, 30]
circuits = tq.make_xrb([[1, 2], 5], [4, 30], 15)

# draw the first circuit
circuits[0].draw()
1 2 5 Key: twirl: Cliffords on [(1, 2), 5] protocol: XRB seq_label: 2267 n_random_cycles: 4 measurement_basis: XYZ 1 Labels: (1, 2) Name: Gate Locally Equivalent: iSWAP Generators: YY: -73.48 YZ: 73.48 ZX: -73.48 IZ: -73.48 IY: -73.48 XI: 73.48 IX: 34.64 ... 0.50 0.50 -0.50 -0.50 0.50j -0.50j 0.50j -0.50j -0.50j 0.50j 0.50j -0.50j -0.50 -0.50 -0.50 -0.50 Labels: (5,) Name: Gate.cliff8 Aliases: Gate.cliff8 Generators: Z: -90.00 1.00 -1.00j 8 2 Labels: (1, 2) Name: Gate Locally Equivalent: CNOT Generators: XX: -61.25 ZZ: -61.25 XI: -61.25 IY: 61.25 ZI: 61.25 YZ: -37.85 XZ: 37.85 ... 0.50 -0.50 0.50 -0.50 -0.50j -0.50j 0.50j 0.50j -0.50 0.50 0.50 -0.50 0.50j 0.50j 0.50j 0.50j Labels: (5,) Name: Gate.cliff14 Aliases: Gate.cliff14 Generators: Z: 127.28 Y: 127.28 0.71 -0.71j 0.71j -0.71 14 3 Labels: (1, 2) Name: Gate Locally Equivalent: iSWAP Generators: XZ: -61.25 YX: -61.25 ZX: 61.25 YZ: -61.25 YI: -61.25 XX: 37.85 ZI: 37.85 ... -0.71 0.71 -0.71j -0.71j 0.71j 0.71j -0.71 0.71 Labels: (5,) Name: Gate.id Aliases: Gate.id Gate.i Gate.cliff0 Locally Equivalent: Identity Generators: I: 0.00 1.00 1.00 ID 4 Labels: (1, 2) Name: Gate Locally Equivalent: CNOT Generators: XZ: 69.28 IX: -69.28 XY: -69.28 0.50 0.50j -0.50j 0.50 0.50j 0.50 -0.50 0.50j -0.50j 0.50 0.50 0.50j -0.50 0.50j 0.50j 0.50 Labels: (5,) Name: Gate.z Aliases: Gate.z Gate.cliff3 Generators: Z: 180.00 1.00 -1.00 Z 5 Labels: (1,) Name: Meas M Labels: (2,) Name: Meas M Labels: (5,) Name: Meas M

Note

If the circuit collection also contains SRB circuits with the same twirl group, then calling fit will also return an estimate e_U of how much the process fidelity of the twirling groups can be improved by correcting static calibration errors.

Parameters

  • labels (Iterable | Twirl) – A list specifying sets of system labels to be twirled together by Clifford gates in each circuit, e.g. [3, [1, 2], 4] for mixed single and two-qubit twirling. Or, for advanced usage, a Twirl instance.

  • n_random_cycles (Iterable) – A list of positive integers specifying how many random cycles will be generated during the protocol, e.g. [6, 20].

  • n_circuits (int) – The number of circuits for each number of random cycles.

Returns

A collection of XRB circuits.

Return type

CircuitCollection

QCAP (Quantum Capacity)

trueq.make_qcap(cycles, n_random_cycles, n_circuits=30, n_decays=20)

Generates a CircuitCollection to measure the quantum capacity (QCAP) bound of any circuit whose marked cycles are contained in cycles. See the QCAP guide for more information.

The bound can be obtained by calling qcap_bound() on the QCAP circuits once they have been performed and their results have been populated. Note that this function outputs cycle benchmarking circuits, and fit() will report the individual infidelities of the given cycles.

import trueq as tq

# make a circuit to assess
circuit = tq.Circuit(
    [
        {0: tq.Gate.y},
        {(0, 1): tq.Gate.cnot},
        {0: tq.Gate.h, 1: tq.Gate.h},
        {(1, 2): tq.Gate.cnot, (3, 4): tq.Gate.cnot},
        {0: tq.Gate.h, 1: tq.Gate.h},
        {(1, 2): tq.Gate.cnot, (3, 4): tq.Gate.cnot},
        {0: tq.Gate.h, 1: tq.Gate.h},
        {(1, 3): tq.Gate.cnot},
    ]
)

# generate a circuit collection to measure the QCAP
circuits = tq.make_qcap(circuit, [0, 16])

# run the circuits on your hardware or simulator
tq.Simulator().add_overrotation(0.05).run(circuits)

# generate the QCAP bound
tq.qcap_bound(circuit, circuits)
True-Q formatting will not be loaded without trusting this notebook or rerunning the affected cells. Notebooks can be marked as trusted by clicking "File -> Trust Notebook".
QCAP
Quantum Capacity
 Paulis
(0, 1, 2, 3, 4)
Key:
  • labels: (0, 1, 2, 3, 4)
  • protocol: QCAP
  • twirl: Paulis on [0, 1, 2, 3, 4]
${e}_{IU}$
The inferred upper bound on the process infidelity of a circuit if it were run under RC.
1.1e-01 (3.0e-03)
0.10990217135723479, 0.0030473542582217595

Note

This function is a convenience wrapper of make_cb(). If, for example, different values of n_random_cycles are desired for each cycle, call make_cb() manually for each cycle placing all generated circuits in the same collection. However, it is important to set the twirl option to tq.Twirl("P", labels) where labels are all the qubit labels involved in the circuit(s) of interest.

Parameters

  • cycles (Iterable | Circuit) – An iterable of Cycles (note that a Circuit is an iterable of cycles). Only the non-zero marked cycles will be considered, and duplicate cycles will be ignored.

  • n_random_cycles (Iterable) – A list of positive integers specifying how many random cycles will be generated during the protocol, e.g. [6, 20].

  • n_circuits (int) – The number of circuits for each random cycle.

  • n_decays (int) – An integer specifying the total number of randomly chosen pauli decay strings used to measure the process infidelity. Warning: Setting this value lower than min(20, 4 ** n_qubits - 1) may result in a biased estimate.

Returns

A collection of QCAP circuits.

Return type

CircuitCollection

trueq.qcap_bound(circuit, fit_or_circuits)

Computes the quantum capacity (QCAP) bound of the given circuit. This scalar quantity is a bound on the circuit performance when the circuit is executed using randomly_compile(). See the QCAP guide for more information.

Parameters

  • circuit (Circuit) – The circuit you wish to know the QCAP bound of. This will usually be the original circuit that was given to make_qcap(), but can be any circuit whose marked cycles are a subset of the marked cycles present in the CB circuits or fits of fit_or_circuits.

  • fit_or_circuits – A circuit collection output by make_qcap() populated with results, or an estimate collection that resulted from calling fit() on such a circuit collection. For efficiency, use the latter format if computing a bound on multiple circuits.

Returns

A bound on the circut performance.

Return type

NormalEstimate

Randomly Compile

trueq.randomly_compile(circuit, n_compilations=30, twirl='P', compile_paulis=False, entangler=None)

Randomly compiles the given circuit into many new random circuits which implement the same algorithm. Random gates are inserted adjacent to gates in the provided circuit, chosen from the specified twirling group (the Pauli group is used by default). See the RC guide for more information.

Cycles with a marker of 0 in the input circuit will not be changed, while other cycles may have random gates compiled around them.

If all cycles in the input circuit have markers of 0, then all cycles containing multi-qubit gates have unique markers assigned automatically. If any cycles have non-zero markers in the circuit, then only those cycles are randomly compiled.

import trueq as tq

# Define a circuit which applies a non-Clifford t gate on the 0th qubit, a
# controlled-Z gate on qubits 0 and 1 with an rx(15) on 2, then another t gate
# on the 0th qubit.
cycle1 = tq.Cycle({0: tq.Gate.t})
cycle2 = tq.Cycle({(0, 1): tq.Gate.cz, 2: tq.Gate.rx(15)})
circuit = tq.Circuit((cycle1, cycle2, cycle1))
circuit.measure_all()

# run randomized compiling on the circuit
compiled_circuit = tq.randomly_compile(circuit)

# draw the first circuit
compiled_circuit[0].draw()
0 1 2 Key: twirl: Paulis on [0, 1, 2] protocol: RC Labels: (0,) Name: Gate Generators: Z: -135.00 1.00 -0.71 -0.71j Labels: (1,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (2,) Name: Gate.y Aliases: Gate.y Gate.cliff2 Generators: Y: -180.00 1.00 -1.00 Y 2 Labels: (0, 1) Name: Gate.cz Aliases: Gate.cz Locally Equivalent: CNOT Generators: ZZ: -90.00 ZI: 90.00 IZ: 90.00 1.00 1.00 1.00 -1.00 CZ CZ Labels: (2,) Name: Gate Generators: X: 15.00 0.99 -0.13j -0.13j 0.99 Labels: (0,) Name: Gate.t Aliases: Gate.t Generators: Z: 45.00 1.00 0.71 0.71j T Labels: (1,) Name: Gate.x Aliases: Gate.x Gate.cliff1 Generators: X: 180.00 1.00 1.00 X Labels: (2,) Name: Gate Generators: Y: 173.87 Z: 46.59 -0.26j -0.97 0.97 0.26j 1 Labels: (0,) Name: Meas M Labels: (1,) Name: Meas M Labels: (2,) Name: Meas M

By default randomly_compile() only adds twirling gates around marked cycles when the entangling gates present in the cycles are Clifford (single qubit gates may be arbitrary). If non-Clifford multi-qubit gates are encountered in the marked cycles, errors will be raised. However, if the target circuit contains non-Clifford entangling gates, and the hardware gateset includes Clifford operations such as CNOT, then these errors can be avoided by compiling the two qubit gates of the target circuit into the hardware gateset by specifying the entangler argument, as in the following example:

import trueq as tq

# Define a circuit which applies an X gate on the 0th qubit, a ZZ(45) Pauli
# gate on qubits 0 and 1, and another X gate on the 0th qubit.
cycle1 = tq.Cycle({0: tq.Gate.x})
cycle2 = tq.Cycle({(0, 1): tq.Gate.rp("ZZ", 45)})
circuit = tq.Circuit((cycle1, cycle2, cycle1))
circuit.measure_all()

# ZZ(45) is not Clifford, but the hardware can perform CNOT gates
# we run randomized compiling on the circuit, specifying a CNOT entangler
compiled_circuit = tq.randomly_compile(circuit, entangler=tq.Gate.cx)

# draw the first circuit
compiled_circuit[0].draw()
0 1 Key: twirl: Paulis on [0, 1] protocol: RC Labels: (0,) Name: Gate.cliff18 Aliases: Gate.cliff18 Generators: Y: 69.28 X: -69.28 Z: -69.28 0.50 0.50j -0.50 0.50j 0.50 0.50j 0.50 -0.50j 18 Labels: (1,) Name: Gate.cliff18 Aliases: Gate.cliff18 Generators: Y: 69.28 X: -69.28 Z: -69.28 0.50 0.50j -0.50 0.50j 0.50 0.50j 0.50 -0.50j 18 2 Labels: (0, 1) Name: cx Aliases: Gate.cx Gate.cnot Parameters: Locally Equivalent: CNOT Generators: ZX: -90.00 IX: 90.00 ZI: 90.00 1.00 1.00 1.00 1.00 CX CX Labels: (0,) Name: Gate Generators: Y: 100.84 X: 100.84 Z: 41.77 -0.27 -0.27j -0.65 0.65j -0.65 -0.65j 0.27 -0.27j Labels: (1,) Name: Gate.cliff15 Aliases: Gate.cliff15 Generators: Y: -127.28 Z: 127.28 -0.71j 0.71 -0.71 0.71j 15 3 Labels: (0, 1) Name: cx Aliases: Gate.cx Gate.cnot Parameters: Locally Equivalent: CNOT Generators: ZX: -90.00 IX: 90.00 ZI: 90.00 1.00 1.00 1.00 1.00 CX CX Labels: (0,) Name: Gate.cliff4 Aliases: Gate.cliff4 Generators: X: -90.00 -0.71j 0.71 0.71 -0.71j 4 Labels: (1,) Name: Gate.cliff13 Aliases: Gate.cliff13 Generators: X: -127.28 Z: 127.28 0.71 -0.71 -0.71 -0.71 13 1 Labels: (0,) Name: Meas M Labels: (1,) Name: Meas M

Note

Running randomly_compile() on a circuit several times is likely to return different compiled circuits due to the random nature of the algorithm. The circuit returned will always contain the same number of cycles as the input circuit, and will be logically equivalent, up to a global phase.

Warning

Running randomly_compile() on circuits containing gates acting on multiple systems with a non-Clifford gate will typically result in an error because twirling operations cannot be corrected locally.

Parameters

  • circuit (Circuit) – A circuit to randomly compile.

  • n_compilations (int) – The number of random compilations of the input circuit. Each instance will appear as a new circuit in the returned circuit collection.

  • twirl (Twirl | str) – The Twirl to use in this protocol. You can also specify a twirling group (default is "P") that will be used to automatically instantiate a twirl based on the labels in the given circuit. This is for advanced use and in typical use cases should not be changed.

  • compile_paulis (bool) – Whether or not to compile a random Pauli gate onto a qubit in the cycle preceding a measurement operation for each Meas operation encountered in the circuit. These additional Pauli operations have the effect of removing readout bias, but the final bit strings then need to be flipped as appropriate for each Pauli introduced. The Paulis that were compiled in are stored as Weyls instance in the key, where the order is first defined by cycle index, and then by sorted labels of each cycle. See decompiled_results() for details on how to undo the addition of these Paulis to the results. (default is False)

  • entangler (NoneType | Gate) – All two-qubit gates in the given circuit will be transpiled into this entangling gate before randomized compiling takes place. No transpiling occurs if the default value None is given.

Returns

A circuit collection containing randomly compiled versions of the circuit.

Return type

py:class:~trueq.CircuitCollection