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 tobatch()
.

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 tobatch()
.

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 tobatch()
.

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 tobatch()
.

class
trueq.sequencer.
TotalTime
(operation_times, max_size=None, load_time=0, n_shots=1)¶ A
CircuitRuler
that attempts to report the wallclock 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 mappingGate
s,Meas
s, orPrep
s 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 tobatch()
.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 wallclock time. This calculation is valid for allrandomly_compile()
like protocols such asmake_srb()
,make_irb()
,make_cb()
,make_sc()
,make_knr()
, andmake_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

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 nonoverlapping lists of these circuits, with no missing circuits. These lists are chosen so that none of the given
CircuitRuler
s 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 ofCircuit
s to batch.rulers (
list
) – A list ofCircuitRuler`s. 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 abatch
attribute added/updated in itskey
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
Circuit
s in aCircuitCollection
.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
andNRCRiffler
.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
CircuitSequencer
s 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