# Circuit Batching and Sequencing¶

class trueq.sequencer.CircuitRuler(max_size=None)

Abstract base class whose child classes implement various ways of measuring the size of a Circuit.

Parameters

max_size (numbers.Real) – The maximum desired size of a collection of circuits under this metric, relevant to batch().

property max_size

The maximum desired size of a collection of circuits under this metric, relevant to batch().

Type

numbers.Real

class trueq.sequencer.NCircuits(max_size=None)

A CircuitRuler that reports a size of 1 to any circuit.

circuit = tq.Circuit([{0: tq.Gate.id}, {0: tq.Gate.x, 1 tq.Gate.h}])
NCircuits()(circuit)
# 1

Parameters

max_size (int) – The maximum desired size of a collection of circuits under this metric, relevant to batch().

property max_size

The maximum desired size of a collection of circuits under this metric, relevant to batch().

Type

numbers.Real

class trueq.sequencer.NCycles(max_size=None)

A CircuitRuler that reports the number of cycles in a given circuit.

circuit = tq.Circuit([{0: tq.Gate.id}, {0: tq.Gate.x, 1 tq.Gate.h}])
NCircuits()(circuit)
# 2

Parameters

max_size (int) – The maximum desired size of a collection of circuits under this metric, relevant to batch().

property max_size

The maximum desired size of a collection of circuits under this metric, relevant to batch().

Type

numbers.Real

class trueq.sequencer.NGates(max_size=None)

A CircuitRuler that reports the total number of gates in a given circuit.

circuit = tq.Circuit([{0: tq.Gate.id}, {0: tq.Gate.x, 1 tq.Gate.h}])
NCircuits()(circuit)
# 3

Parameters

max_size (int) – The maximum desired size of a collection of circuits under this metric, relevant to batch().

property max_size

The maximum desired size of a collection of circuits under this metric, relevant to batch().

Type

numbers.Real

class trueq.sequencer.TotalTime(operation_times, max_size=None, load_time=0, n_shots=1)

A CircuitRuler that attempts to report the wall-clock time that a given circuit will take to run. This is done by:

• Specifying the length of each gate in time units.

• Specifying the length of each measurement and preparation in time units.

• Specifying the time it takes to load a new circuit into the device.

• Specifying the number of times a fixed circuit is to be repeated (i.e. the number of shots).

The length of a single shot is the sum of the maximum operation time of each cycle. This sum is multiplied by the number of shots, and then the load time constant is added.

circuit = tq.Circuit([{0: tq.Gate.id}, {(0, 1): tq.Gate.cnot, 1: tq.Gate.h}])
op_times = {tq.Gate.x: 0.03, tq.Gate.cnot: 0.45, 1: 0.05}
TotalTime(op_times)(circuit)
# 0.5

Parameters
• operation_times (dict) – A dictionary mapping Gates, Meass, or Preps to numbers specifying their time length. If an integer is is given instead of a gate, this becomes the default length of gates acting on that number of qubits.

• max_size (numbers.Real) – The maximum desired size of a collection of circuits under this metric, relevant to batch().

• load_time (numbers.Real) – An additive offset cost for the whole circuit.

• n_shots (int) – The number of shots this circuit will be sampled at.

optimal_n_shots(circuit)

The approximate optimal number of shots to draw of the given circuit in a randomly_compile()-like setting (See [1], Figure 1c), assuming that this ruler is a good method for determining experiment wall-clock time. This calculation is valid for all randomly_compile()-like protocols such as make_srb(), make_irb(), make_cb(), make_sc(), make_knr(), and make_tnr(). The notable exception from this list is XRB, for which this function does not apply.

To reduce the variance of the parameter of interest, increase the number of random circuits, but use this method to determine the number of shots to draw on each random circuit. This will maximize the amount of information gain per unit time.

Parameters

circuit (Circuit) – The circuit to compute the optimal number of shots for.

Return type

int

property max_size

The maximum desired size of a collection of circuits under this metric, relevant to batch().

Type

numbers.Real

class trueq.sequencer.Batcher(circuits, rulers, start_idx=0, extra_circuits=None)

An instance of this class takes an iterable of circuits and breaks it into non-overlapping lists of these circuits, with no missing circuits. These lists are chosen so that none of the given CircuitRulers exceed their maximum allowed size on any batch. Flattening these lists results in the original circuit list; no reordering is performed.

Parameters
• circuits (Iterable) – An iterable of Circuits to batch.

• rulers (list) – A list of CircuitRulers. A new batch is started whenever adding the next circuit to the current batch would result in some ruler exceeding its :py:attr:CircuitRuler.max_size property.

• start_idx (int) – The first batch index. Each subsequent batch index increments by one. Each circuit has a batch attribute added/updated in its key batch index that it falls under.

• extra_circuits (Iterable) – An iterable of circuits to be added to the start of each batch. Circuit copies are made; instances in each batch will be different.

property extra_copies

All of the copies of extra circuits that were made while batching. After this batcher has been iterated through, these copies will exist in the batches, but will not exist in the original iterable of circuits.

Type

list

class trueq.sequencer.CircuitSequencer

Base class for objects that choose how to sequence Circuits in a CircuitCollection.

Note

CircuitCollection uses a sequencer internally for yielding circuits in many of its methods.

In the example below, we use two concrete circuit sequencers, Consecutive and NRCRiffler.

import trueq as tq
import trueq.assessments as tqa
from trueq.sequencer import Consecutive, NRCRiffler
sequencer = Consecutive(NRCRiffler(protocol="SRB"), NRCRiffler(protocol="XRB"))
circuits = tqa.make_crosstalk_diagnostics([0, 1, 2], [4, 50])

# loop through circuits according to our sequencer
for circuit in sequencer(circuits):
print(circuit)

# loop through circuits with only seqeunce length 4 according to our sequencer
for circuit in sequencer(circuits, n_random_cycles=4):
print(circuit)

class trueq.sequencer.Consecutive(*sequences, append_unused=True)

Runs a bunch of other CircuitSequencers consecutively.

Parameters
• sequences – A sequence of CircuitSequencer objects.

• append_unused (bool) – Whether or not to append all circuits that match the filter but were not used in any of the given circuits.

class trueq.sequencer.NRCRiffler(**filter)

Riffles together circuits that differ only in their n_random_cycles attribute.

Parameters

filter – Specifies a subset of circuits to filter to; the filter given to this sequencer’s caller is