Sequencer

`trueq.sequencer.Batcher`	An instance of this class takes an iterable of circuits and breaks it into non-overlapping lists of these circuits, with no missing circuits.
`trueq.sequencer.CircuitRuler`	Abstract base class whose child classes implement various ways of measuring the size of a `Circuit`.
`trueq.sequencer.CircuitSequencer`	Base class for objects that choose how to sequence `Circuit`s in a `CircuitCollection`.
`trueq.sequencer.Consecutive`	Runs multiple `CircuitSequencer`s consecutively.
`trueq.sequencer.NCircuits`	A `CircuitRuler` that reports a size of 1 to any circuit.
`trueq.sequencer.NCycles`	A `CircuitRuler` that reports the number of cycles in a given circuit.
`trueq.sequencer.NGates`	A `CircuitRuler` that reports the total number of gates in a given circuit.
`trueq.sequencer.NRCRiffler`	Riffles together circuits that differ only in their `n_random_cycles` attribute.
`trueq.sequencer.RIFFLER`	Runs multiple `CircuitSequencer`s consecutively.
`trueq.sequencer.TotalTime`	A `CircuitRuler` that attempts to report the wall-clock time that a given circuit will take to run.

Batcher

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

Circuit Ruler

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

Circuit Sequencer

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
from trueq.sequencer import Consecutive, NRCRiffler

sequencer = Consecutive(NRCRiffler(protocol="SRB"), NRCRiffler(protocol="XRB"))
circuits = tq.make_crosstalk_diagnostics([0, 1, 2], [4, 50])

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

# loop through circuits with only protocol="XRB"
for circuit in sequencer(circuits, protocol="XRB"):
    pass

Consecutive

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

Runs multiple CircuitSequencers consecutively.

Parameters:

*sequences – One or more 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.

N Circuits

class trueq.sequencer.NCircuits(max_size=None)

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

import trueq as tq

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

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

N Cycles

class trueq.sequencer.NCycles(max_size=None)

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

import trueq as tq

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

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

N Gates

class trueq.sequencer.NGates(max_size=None)

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

import trueq as tq

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

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

NRC Riffler

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 every time this sequencer is called; see subset().
Raises:: ValueError – If a filter is provided that contains n_random_cycles as a key.

RIFFLER

sequencer.RIFFLER = Consecutive(NRCRiffler('protocol':'SRB'), NRCRiffler('protocol':'XRB'), NRCRiffler('protocol':'IRB'), NRCRiffler('protocol':'CB'), NRCRiffler('protocol':'SC'), NRCRiffler('protocol':'KNR'))

Total Time

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.

import trueq as tq

circuit = tq.Circuit([{0: tq.Gate.id}, {(0, 1): tq.Gate.cnot, 2: tq.Gate.h}])
op_times = {tq.Gate.x: 0.03, tq.Gate.cnot: 0.45, 1: 0.05}
tq.sequencer.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 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)

Returns the approximate optimal number of shots to draw of the given circuit in a randomly_compile()-like setting (See [19], 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(), and make_knr(). 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