Estimate

`trueq.estimate.base.Estimate`	Base class for all estimate types, which store fit information returned from data analysis.
`trueq.estimate.base.EstimateTuple`	A namedtuple container for storing a single estimate name, value, and standard deviation.
`trueq.estimate.base.EstimatesTuple`	A namedtuple container for storing a 1-D array of values and standard deviations for a particular parameter name.
`trueq.estimate.EstimateCollection`	An iterable container of `Estimate`s with several convenience functions which make it easier to select specific estimates.
`trueq.estimate.ArrayAxis`	Contains a name and indices for a single axis of an `EstimateArray`.
`trueq.estimate.EstimateArray`	Stores a multi-dimensional array of estimate values (and corresponding standard deviations in a separate array) for a specified parameter name.
`trueq.estimate.NormalEstimate`	Stores a joint estimate of a collection of system parameters.
`trueq.estimate.RCalEstimate`	Stores estimates for the confusion matrices associated with readout errors.
`trueq.estimate.comp_table.CompTable`	Organizes `NormalEstimate`s into a parent-children structure based on twirling groups in a way that makes it easier to compare values.
`trueq.estimate.knr.KnrBodyEstimate`	Represents a Pauli probability distribution for some subset of qubits of a cycle of interest, as measured by KNR; see also `make_knr()`.
`trueq.estimate.knr.KnrDataTable`	Organizes KNR estimates into a table with columns grouped by cycle (and possibly other keywords, see `group_by`) and rows grouped by error modes.

Estimate (Parent Class)

class trueq.estimate.base.EstimateTuple(name, val, std)

A namedtuple container for storing a single estimate name, value, and standard deviation.

Parameters

name (str) – The name of the estimate.
val (float | complex) – The value of the estimate.
std (float) – The standard deviation of the estimate.

class trueq.estimate.base.Estimate(key, options=None)

Base class for all estimate types, which store fit information returned from data analysis.

This class is not expected to be used directly, and fitting results will return subclasses such as NormalEstimate or RCalEstimate.

Parameters

key (Key) – A hashable object used for record keeping in analysis. For example, Key(protocol='SRB', n_random_cycles=10).
options (NoneType | dict) – Options that were passed to fit() method.

to_dict()

Converts the estimate to a dictionary representation.

Note

The stored Key is also converted to a dictionary.

Return type: dict

static from_dict(dic)

Converts a dictionary representation into an estimate instance.

Note

See to_dict() for more details.

Parameters: dic (dict) – The dictionary representation of the estimate.
Returns: An Estimate or one of its subclasses depending on the dic that is provided.
Return type: Estimate-like

property key

The Key of this estimate, used for bookkeeping.

Type: Key

property options

The fit options that were used to create this estimate.

Type: dict

Estimate Collection

class trueq.estimate.base.EstimatesTuple(name, vals, stds, sweeps)

A namedtuple container for storing a 1-D array of values and standard deviations for a particular parameter name.

Parameters

name (str) – The name of the estimates.

vals (np.ndarray) – An array of estimates.

stds (np.ndarray) – The corresponding standard deviations of the estimates.

sweeps (dict) – A dictionary mapping keyword names to lists of keyword values, where each list has the same length as vals.
class trueq.estimate.EstimateCollection(estimates=None)
An iterable container of Estimates with several convenience functions which make it easier to select specific estimates.
import trueq as tq

circuits = tq.make_srb([[0], [1, 2]], [4, 32])
circuits += tq.make_xrb([[0], [1, 2]], [4, 32])
tq.Simulator().add_overrotation(0.04).run(circuits)

estimate_collection = circuits.fit()
estimate_collection
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".

SRB

Streamlined Randomized Benchmarking
Cliffords
(0,)

Key:

labels: (0,)

protocol: SRB

twirl: Cliffords on [0, (1, 2)]

Cliffords
(1, 2)

Key:

labels: (1, 2)

protocol: SRB

twirl: Cliffords on [0, (1, 2)]

${e}_{F}$

The probability of an error acting on the targeted systems during a random gate.
4.6e-03 (1.3e-03)
0.004557274014025614, 0.001315597590143854
0.0e+00 (0.0e+00)
0.0, 0.0

${p}$

Decay parameter of the exponential decay $Ap^m$.
9.9e-01 (1.8e-03)
0.9939236346479658, 0.0017541301201918055
1.0e+00 (0.0e+00)
1.0, 0.0

${A}$

SPAM parameter of the exponential decay $Ap^m$.
1.0e+00 (9.6e-03)
1.0014531565134703, 0.009648637443338279
1.0e+00 (0.0e+00)
1.0, 0.0

XRB

Extended Randomized Benchmarking
Cliffords
(0,)

Key:

labels: (0,)

protocol: XRB

twirl: Cliffords on [0, (1, 2)]

Cliffords
(1, 2)

Key:

labels: (1, 2)

protocol: XRB

twirl: Cliffords on [0, (1, 2)]

${e}_{U}$

The process infidelity of the coherent error acting on the specifed systems during a random gate.
4.2e-03 (1.4e-03)
0.0041633006726592425, 0.0013519355493582055
2.4e-04 (9.8e-05)
0.00024493506197176274, 9.811668611522744e-05

${e}_{S}$

The probability of a stochastic error acting on the specified systems during a random gate.
3.9e-04 (3.1e-04)
0.0003939733413663715, 0.0003113401844063125
-2.4e-04 (9.8e-05)
-0.00024493506197176274, 9.811668611522744e-05

${u}$

The unitarity of the noise, that is, the average decrease in the purity of an initial state.
1.0e+00 (8.3e-04)
0.9989496113763481, 0.0008299133991294943
1.0e+00 (2.1e-04)
1.0005225921249365, 0.0002093668657745526

${A}$

SPAM parameter of the exponential decay $Au^m$.
1.0e+00 (9.1e-03)
1.0264533464493306, 0.009055800567131357
1.1e+00 (4.5e-03)
1.0508505015629082, 0.0045097142572557425
Parameters

estimates (NoneType | Estimate-like | Iterable) – Either a single Estimate or an iterable of several estimates. If None is provided, the EstimateCollection will be empty.

append(estimate)

Appends a single Estimate or an iterable of several estimates to the collection.

Parameters

estimate (Estimate-like | Iterable) – Either a single Estimate or an iterable of several estimates.

Returns

This estimate collection.

Return type

EstimateCollection
keys(**filter)
Returns the set of all keys of this estimate collection matching the given filter.
import trueq as tq

circuits = tq.make_srb([[0], [1, 2]], [4, 32])
circuits += tq.make_xrb([[0], [1, 2]], [4, 32])
tq.Simulator().add_overrotation(0.04).run(circuits)

estimate_collection = circuits.fit()
estimate_collection.keys(protocol="SRB")
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".

KeySet

List of all the keys in the KeySet
protocol
The characterization protocol used to generate a circuit.
labels twirl
The twirling group used to generate a circuit.

Key

Key:

labels: (0,)

protocol: SRB

twirl: Cliffords on [0, (1, 2)]

SRB (0,) Cliffords on [0, (1, 2)]

Key

Key:

labels: (1, 2)

protocol: SRB

twirl: Cliffords on [0, (1, 2)]

SRB (1, 2) Cliffords on [0, (1, 2)]
Parameters

**filter – The filter on keys.

Return type

KeySet
subset(name_pattern=None, filter_fn=None, **filter)

Returns an EstimateCollection containing only the estimates in this collection that match the filter on keys, and whose parameter names match the given filter function or the pattern.

Parameters

name_pattern (string) – A regular expression that specifies a pattern for the names, for example "(p_ZZ.*)|(e_F)" to match any name that starts with p_ZZ or any name equal to e_F.

filter_fn (function) – A function which accepts an Estimate and returns either True or False.

**filter – The filter on keys.

Return type

EstimateCollection

one_or_none(filter_fn=None, **filter)

Returns a single estimate if it is the only estimate in this collection that matches the filter. Otherwise returns None.

Parameters

filter_fn (function) – A function which accepts an Estimate and returns either True or False

**filter – The filter on keys.

Return type

Estimate-like | NoneType

sorted(*names)

Returns an EstimateCollection sorted by the keys contained in the estimates, see trueq.KeySet.sorted() for more information.

Parameters

*names – One or more name strings that should take priority in sorting.

Return type

EstimateCollection
update_keys(*other, keep=None, remove=None, **kwargs)
Updates every estimate’s key in this collection with new keywords/values. If a given key does not have a given keyword, it is added. If it already exists, it is overwritten. See also trueq.Key.copy() which this method uses.
import trueq as tq

# generate an estimate collection by calling fit() on some circuits
circuits = tq.make_srb([[0], [1, 2]], [4, 32])
circuits += tq.make_xrb([[0], [1, 2]], [4, 32])
tq.Simulator().add_overrotation(0.04).run(circuits)
estimates = circuits.fit()

# give each circuit a new keyword 'banana' with value 10
estimates.update_keys(banana=10)

estimates.keys()
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".

KeySet

List of all the keys in the KeySet
protocol
The characterization protocol used to generate a circuit.
labels twirl
The twirling group used to generate a circuit.
banana

Key

Key:

banana: 10

labels: (0,)

protocol: SRB

twirl: Cliffords on [0, (1, 2)]

SRB (0,) Cliffords on [0, (1, 2)] 10

Key

Key:

banana: 10

labels: (1, 2)

protocol: SRB

twirl: Cliffords on [0, (1, 2)]

SRB (1, 2) Cliffords on [0, (1, 2)] 10

Key

Key:

banana: 10

labels: (0,)

protocol: XRB

twirl: Cliffords on [0, (1, 2)]

XRB (0,) Cliffords on [0, (1, 2)] 10

Key

Key:

banana: 10

labels: (1, 2)

protocol: XRB

twirl: Cliffords on [0, (1, 2)]

XRB (1, 2) Cliffords on [0, (1, 2)] 10
Parameters

*other – One or more dict-like objects (e.g. Key or dict) to update the keys with. Updating is applied in the given order. If a name specified in any of these objects already exists after the keep or remove process has taken place, it is updated.

keep (str | list) – A string or list of strings specifying the only names to keep during the updates. By default, all names are kept. Only one of the options keep or remove may be used.

remove (str | list) – A string or list of strings specifying names to remove during the updates. By default, no names are removed. Only one of the options keep or remove may be used.

**kwargs – Name-value items to update the keys with. If a name specified here already exists after the keep or remove process has taken place, it is updated.

Returns

This estimate collection.

Return type

EstimateCollection

Raises

ValueError – If the mutally exclusive keep and remove are both set to True.
array(name, *axes, name_axis=0)
Constructs a multi-dimensional array of estimate values for a specified parameter name. Each axis corresponds to a sweep over metadata values from a particular Key name from the estimates in this collection, or over parameter names themselves if name is provided as a pattern with more than one match.
import trueq as tq

circuits = tq.make_srb([0, 1, 2, 3, 4], [4, 32])
circuits += tq.make_xrb([0, 1, 2, 3, 4], [4, 32])
tq.Simulator().add_overrotation(0.04).run(circuits)
fit = circuits.fit()

# extract a 2-d array of 'p' estimates with first axis over qubit labels,
# and second axis over protocol
arr = fit.array("p", "labels", "protocol")

# we can look at the axes and value array directly
print(arr.axes)
print(arr.vals, "\n")

# we can also look at the html representation, which condenses all but the
# last axis into rows, and displays the last axis as columns
arr
(ArrayAxis('labels', ((0,), (1,), (2,), (3,), (4,))), ArrayAxis('protocol', ('SRB',)))
[[0.99795501]
 [0.99652513]
 [0.99510488]
 [0.99646229]
 [0.99804379]] 
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".

protocol SRB

labels

(0,) 9.98e-01 (6.59e-04)
val=0.997955
std=0.000659233

(1,) 9.97e-01 (6.87e-04)
val=0.996525
std=0.000686798

(2,) 9.95e-01 (9.26e-04)
val=0.995105
std=0.000926173

(3,) 9.96e-01 (6.65e-04)
val=0.996462
std=0.000664567

(4,) 9.98e-01 (6.26e-04)
val=0.998044
std=0.000625568
Note

The extracted array is always (hyper-)rectangular, whereas estimate collections are often ragged. When a particular value does not exist in the collection, np.nan is inserted as the array element.

Parameters

name (str | ArrayAxis) – The name of the parameter to extract, e.g. "e_F", a regular expression whose matched named are extracted, e.g. "e_F|p" or "e__[IXYZ]+", or an ArrayAxis whose values are parameter names.

*axes – A sequence of strings or ArrayAxis that are used to index axes of the array. Each axis (except possibly one defined by name, which is a special case) corresponds to metadata values from a specific keyword found in the keys() of this collection. For example, a string axis value of "protocol" will cause the corresponding axis to be over different protocols sorted by protocol name, or a string axis value of "labels" will be over sorted subsystem labels. For more fine-grained control, axes can be manually specified by ArrayAxis instances.

name_axis (int) – In the case where multple names are matched, either because name is a regular expression with multiple matching names or because name was given as an ArrayAxis with multiple values, which axis to put the names on. The default is the 0’th axis, and the remaining axes are ordered according to the order of the axes.

Return type

EstimateArray

Raises

ValueError – If no estimates with names matching name are found.

ValueError – If multiple estimates with the same name are found that do not differ on their axis values.
to_dict_list()

Returns a list of dictionary representations of the Estimate objects in this collection.

Return type

list

static from_dict_list(dict_list)

Creates a new estimate collection from a list of dictionary representations of Estimate objects.

Parameters

dict_list (list) – A list of dictionary representations of estimate objects.

Return type

EstimateCollection

property plot

An object that stores all plotting functions deemed relevant to this EstimateCollection. If one of these functions is called, the data from this estimate collection is analyzed and used.

Type

PlottingSuite

Estimate Array

class trueq.estimate.ArrayAxis(name, indices, is_name_axis=False)

Contains a name and indices for a single axis of an EstimateArray.

Parameters

name (str) – The name of the axis.
indices (Iterable) – The indexing values of the axis. These can be of any type. The length should match the dimension of the axis.
is_name_axis (bool) – Whether this axis is over parameter names; at most one such axis can exist for an EstimateArray.

property name

The name of this axis.

Type: str

property size

The size of this axis.

Type: int

property indices

The indexing values of this axis.

Type: tuple

property is_name_axis

Whether this axis is over parameter names.

bool

static from_keys(name, keys)

Constructs a new ArrayAxis by collecting all unique values of the given name from the keys and sorting them if possible.

Parameters

name (str) – The keyname to collect.
keys (KeySet) – Some keys to collect values from.

Return type

ArrayAxis

Raises

KeyError – If the name is not present in the keys.

class trueq.estimate.EstimateArray(vals, stds, axes)

Stores a multi-dimensional array of estimate values (and corresponding standard deviations in a separate array) for a specified parameter name. Each axis corresponds to a sweep over metadata values from a particular Key name from the estimates in an EstimateCollection, or over parameter names themselves. Instances of this class are typically constructed by array().

Parameters

vals (array_like) – An array of parameter values estimates.
stds (array_like) – The standard deviations of each member of vals, an array with the same shape as vals.
axes (Iterable) – A sequence of ArrayAxis instances whose sizes must match the shape of vals and stds.

property axes

A tuple of ArrayAxis instances which describe each axis of this array.

Type: tuple

property dtype

The data type of vals.

Type: type

property ndim

The number of axes owned by vals and stds.

int

property shape

The shape of vals and stds.

tuple

property stds

An array of parameter value standard deviations, with the same shape as vals. The axes are described by axes.

Type: array_like

property vals

An array of parameter values, with the same shape as vals. The axes are described by axes.

Type: array_like

nan_reason(idxs)

Returns a reason for why the array element at the given index is numpy.nan. If it is a number, then an empty string is returned.

Parameters: idxs (tuple) – The nd-index to address.
Return type: str

to_dataframe(include_vals=True, include_stds=True)

Converts this array to a dataframe.

If this array has two or more dimensions, the last dimension is used for the columns of the dataframe, and the first dimensions are flattened together to form the rows, and indexed with a pandas.MultiIndex. If this array has only one dimension, then the values are put into rows.

If both include_vals and include_stds are True, which is the default, then they appear in separate columns, where a pandas.MultiIndex is used along with the last dimension of this array if it has at least two dimensions in total.

Parameters

include_vals (bool) – Whether to include estimate values in the dataframe.
include_stds (bool) – Whether to include standard deviations in the dataframe.

Return type

pandas.DataFrame

Normal Estimates

class trueq.estimate.NormalEstimate(key, names, values, err=None, raw=None, options=None)

Stores a joint estimate of a collection of system parameters. Each parameter is described by a name and an estimated mean value. These mean values are assumed to be normally distributed, and their covariance matrix (or vector of standard deviations for uncorrelated estimates) is optionally present.

import trueq as tq

estimate = tq.NormalEstimate(
    tq.Key(), ["a", "b", "c"], [1, 2, 3], [0.2, 0.2, 0.2]
)

# get the estimated value of b
estimate.b

EstimateTuple(name='b', val=2, std=0.2)

Parameters

key (Key) – A key used for record keeping in analysis. For example, Key(protocol='SRB', n_random_cycles=10).
names (Iterable) – An iterable collection of strings which describe the parameters returned from fitting.
values (list | numpy.ndarray) – An iterable containing the estimated values associated with the provided names.
err (NoneType | numpy.ndarray | list) – Optional array or list containing either the covariance matrix or the standard deviation vector associated with the estimated values. If None is provided then this is set to a vector of zeros.
raw (NoneType | dict) – Optional, the data used to estimate the values. If not provided, this defaults to an empty dictionary.
options (NoneType | dict) – Options that were passed to fit() method.

Raises

ValueError – If the lengths of names and err (if provided) do not match the length of values.

property names

An iterable collection of strings which describe the parameters returned from fitting.

Type: Iterable

property values

An iterable containing the estimated values associated with the provided names.

Type: Iterable

property raw

The data used to estimate the values. The format of this dictionary may vary depending on who constructed it. Some examples of the format used by True-Q™ protocols are:

Protocols	Format
IRB, SRB, XRB	`{<sequence_length>: [<circuit expectation values>], ...}`
CB, KNR, SC	`{<measurement_basis>: {<sequence_length>: [<circuit expectation values>], ...}, ...}`

Type: dict

property err

Array containing either the covariance matrix or the standard deviation vector associated with the estimated values. If err=None was provided, this will be a vector of zeros.

Type: numpy.ndarray

property cov

The covariance matrix of this estimate.

If err=None was provided, this will be an array of zeros.

Type: numpy.ndarray

property std

A vector of standard deviations for every element of this estimate.

If err=None was provided, this will be a vector of zeros.

If a covariance matrix is present then this is the square root of diagonal terms.

Type: numpy.ndarray

subset(name_pattern)

Returns a new NormalEstimate that contains only the parameters whose name matches name_pattern.

Parameters: name_pattern (str) – A regular expression that specifies a pattern for the names.
Type: py:class:~trueq.estimate.NormalEstimate

Readout Estimates

class trueq.estimate.RCalEstimate(key, values, options=None)

Stores estimates for the confusion matrices associated with readout errors.

Parameters

key (Key) – A hashable object used for record keeping in analysis. For example, Key(protocol='SRB', n_random_cycles=10).
values (dict) – A dict where the keys of the dict are the single qubit labels, and the values are the associated confusion matrices for the probabilities of correctly labeling the qubit’s final state.
options (NoneType | dict) – Options that were passed to fit() method.

apply_correction(results, labels=None)

Applies this calibration as a correction to the given results. This is done by inverting each calibration matrix and contracting it onto the corresponding indices of the given results.

import trueq as tq

# make a test and RCAL circuits
rcal_circuits = tq.make_rcal(range(5))
circuit = tq.Circuit([{0: tq.Gate.x}, {range(5): tq.Meas()}])

# construct a simulator with readout error and run the circuits
sim = tq.Simulator().add_readout_error([0.1, 0.05])
sim.run(rcal_circuits, 10000)
sim.run(circuit)

# create an RCAL estimate
rcal_est = rcal_circuits.fit()[0]

# plot original and corrected bitstring distributions
circuit.results.plot()
rcal_est.apply_correction(circuit.results).plot()

Note

This method necessarily has exponential scaling in the number of qubits. Further, no clipping is performed, so that the output distribution may contain small negative values due to finite sampling effects.

Parameters

results (Results) – A results object to correct.
labels (Iterable | NoneType) – An optional labelling (iterable of unique non-negative integers) of the bitstrings in the given results object. These labels are used to decide which correction matrices to apply where. If None, the labels from the key of this estimate are assumed.

Returns

A new results object equal to the correction of the input.

Return type

Results

Raises

ValueError – If no labels are given and there are no labels in the key of this instance.
ValueError – If bitstring lengths are not compatible with the number of labels.

property values

A dict where the keys of the dict are the single qubit labels, and the values are the associated confusion matrices for the probabilities of correctly labeling the qubit’s final state.

Type: dict

Comparison Table

class trueq.estimate.comp_table.CompTable(fit_or_circuits)

Organizes NormalEstimates into a parent-children structure based on twirling groups in a way that makes it easier to compare values.

from itertools import chain, combinations
import trueq as tq

# generate CB circuits
circuits = tq.make_cb({range(3): tq.Gate.x}, [4, 32])
circuits += tq.make_cb({range(2): tq.Gate.x}, [4, 32])
circuits += tq.make_cb({1: tq.Gate.x}, [4, 32])

# use a different twirling group
circuits += tq.make_cb({range(2): tq.Gate.x}, [4, 32], twirl="C")
circuits += tq.make_cb({0: tq.Gate.x}, [4, 32], twirl="C")
circuits += tq.make_cb({1: tq.Gate.x}, [4, 32], twirl="C")

# add a different qubit
circuits += tq.make_cb({range(3): tq.Gate.x}, [4, 32])

# run the circuits on a noisy simulator
tq.Simulator().add_overrotation(0.04).run(circuits)


def powerset(iterable):
    # powerset([1,2,3]) -> () (1,) (2,) (3,) (1, 2) (1, 3) (2, 3) (1, 2, 3)
    s = list(iterable)
    return chain.from_iterable(combinations(s, r) for r in range(len(s) + 1))


# get infidelity on every possible combination of labels
fit = circuits.fit(set(chain(powerset(range(3)), powerset((0, 5, 2)))))

# this plotter visualizes CompTable; every subplot is a Family, and every trace
# is a Member
fit.plot.compare_twirl("e_F")

Parameters: fit_or_circuits (CircuitCollection | EstimateCollection) – An estimate collection or set of circuits to create the data table for.

class Family(parent, title, labels, names, members, protocols)

labels: Alias for field number 2

members: Alias for field number 4

names: Alias for field number 3

parent: Alias for field number 0

protocols: Alias for field number 5

title: Alias for field number 1

class Member(title, twirls, data, protocol)

data: Alias for field number 2

protocol: Alias for field number 3

title: Alias for field number 0

twirls: Alias for field number 1

table(names=None)

Returns all data in a structure.

import trueq as tq

circuits = tq.make_crosstalk_diagnostics([0, 1, 2], [4, 32])
tq.Simulator().add_overrotation(0.05).run(circuits)
data = tq.estimate.comp_table.CompTable(circuits)

for family in data.table(["p", "r"]):
    print(family.title)
    print(family.labels)
    for member in family.members:
        print(member.title)
        print(member.data)
    print("")

Cliffords on [0, 1, 2]
[(0,), (1,), (2,)]
Simultaneous
{'p': {(0,): EstimateTuple(name='p', val=0.9931589956523043, std=0.0015251217232681255), (1,): EstimateTuple(name='p', val=0.9953593157735444, std=0.0007948198763681393), (2,): EstimateTuple(name='p', val=0.9968031429247345, std=0.0009333277578500513)}}
Isolated
{'p': {(0,): EstimateTuple(name='p', val=0.9942352606872364, std=0.001395387851888512), (1,): EstimateTuple(name='p', val=0.9943217276011254, std=0.0014993358573904506), (2,): EstimateTuple(name='p', val=0.9944934340904953, std=0.0014539938128627773)}}

Parameters: names (str | Iterable | None) – An estimate parameter of names or list thereof to include in the output. All names are included by default.
Return type: list

KNR Specializations

class trueq.estimate.knr.KnrBodyEstimate(key, names, values, err=None, raw=None, options=None)

Represents a Pauli probability distribution for some subset of qubits of a cycle of interest, as measured by KNR; see also make_knr(). The key stores all relevant metadata, including:

key.cycle is the cycle of interest.
key.twirl is the twirling group, which may include a superset of the qubits referenced by the cycle.
key.labels are the sorted qubit labels defining the subsystem for which this estimate is a distribution over.
key.subsystems are the combinations of labels for which marginal distributions are constructed.

property subcycle

A subcycle of this estimate’s cycle of interest containing only the gate(s) that this estimate describes. Any idling qubits (i.e. qubits which are twirled by the protocol but absent from the cycle of interest) that this estimate describes are added as single qubit identity gates.

Type: Cycle

class trueq.estimate.knr.KnrDataTable(fit_or_circuits, group_by=('name', 'cycles', 'twirl'))

Organizes KNR estimates into a table with columns grouped by cycle (and possibly other keywords, see group_by) and rows grouped by error modes.

Parameters

fit_or_circuits (CircuitCollection | EstimateCollection) – An estimate collection or set of circuits to create the data table for.
group_by (Iterable) – Which keywords to group columns by. For example, if the estimate collection contains data for the same cycle for multiple chips, and this information is distinguished by a “chip” keyword, then this value could be (“cycles”, “chip”, “twirl”). The keywords “cycles” and “twirl” should appear in this list.

class Cell(mean, std, subcycles)

Storage type for the contents of a single cell in the table

mean: Alias for field number 0

std: Alias for field number 1

subcycles: Alias for field number 2

class Row(sort_key, degens, param_names, latex)

Storage type for row descriptions, which index Cell rows.

degens: Alias for field number 1

latex: Alias for field number 3

param_names: Alias for field number 2

sort_key: Alias for field number 0

set_truncation(cutoff, relative_to_max=True, cl=None)

Sets the cutoff at which rows are hidden. If every probability in a subrow falls below the cutoff across an entire row of cells, then these subrows are removed when get_cell() and row_info are called.

Parameters

cutoff (float) – The cutoff value to use.
relative_to_max (bool) – Whether the cutoff is relative to the maximum probability in the whole table (in which case the cutoff used is cutoff * max_val). Otherwise, the cutoff is absolute.
cl (float | NoneType) – The confidence level at which to cutoff, or None to use the current default accessed by get_cl().

property n_cell_rows

The number of cell rows in this table.

Note

This value may change after set_truncation() is called.

Type: int

property n_cell_cols

The number of cell columns in this table.

Type: int

property row_info

A list of Row instances which describe the contents of each cell row of the table.

Note

This value may change after set_truncation() is called.

Type: list

get_cell(idx_cell_row, idx_cell_col)

Gets a single cell by index. This cell contains a matrix of probabilities, a matrix of their standard deviations, and label information for each column in the matrix. Note that row information is found in the corresponding element of row_info, and a header for the whole cell is found in the corresponding element of col_info.

Note

Cell row indices may change when set_truncation() is called.

Parameters

idx_cell_row (int) – An index below n_cell_rows.
idx_cell_col (int) – An index below n_cell_cols.

Return type

Cell

property col_info

A list of Col instances which describe the contents of each cell row of the table.

Type: list

row_max(idx_cell_row)

Returns the maximum error probability of the given row and the corresponding standard deviation.

Parameters: idx_cell_row (int) – An index below n_cell_rows.
Return type: tuple

property max

The maximum error probability in the entire table and its corresponding standard deviation.

Type: float

property heights

A list of heights of each cell row.

Type: list

property widths

A list of the maximum widths of each cell column.

Type: list

SRB Streamlined Randomized Benchmarking	Cliffords (0,) Key: labels: (0,) protocol: SRB twirl: Cliffords on [0, (1, 2)]	Cliffords (1, 2) Key: labels: (1, 2) protocol: SRB twirl: Cliffords on [0, (1, 2)]
${e}_{F}$ The probability of an error acting on the targeted systems during a random gate.	4.6e-03 (1.3e-03) 0.004557274014025614, 0.001315597590143854	0.0e+00 (0.0e+00) 0.0, 0.0
${p}$ Decay parameter of the exponential decay $Ap^m$.	9.9e-01 (1.8e-03) 0.9939236346479658, 0.0017541301201918055	1.0e+00 (0.0e+00) 1.0, 0.0
${A}$ SPAM parameter of the exponential decay $Ap^m$.	1.0e+00 (9.6e-03) 1.0014531565134703, 0.009648637443338279	1.0e+00 (0.0e+00) 1.0, 0.0
XRB Extended Randomized Benchmarking	Cliffords (0,) Key: labels: (0,) protocol: XRB twirl: Cliffords on [0, (1, 2)]	Cliffords (1, 2) Key: labels: (1, 2) protocol: XRB twirl: Cliffords on [0, (1, 2)]
${e}_{U}$ The process infidelity of the coherent error acting on the specifed systems during a random gate.	4.2e-03 (1.4e-03) 0.0041633006726592425, 0.0013519355493582055	2.4e-04 (9.8e-05) 0.00024493506197176274, 9.811668611522744e-05
${e}_{S}$ The probability of a stochastic error acting on the specified systems during a random gate.	3.9e-04 (3.1e-04) 0.0003939733413663715, 0.0003113401844063125	-2.4e-04 (9.8e-05) -0.00024493506197176274, 9.811668611522744e-05
${u}$ The unitarity of the noise, that is, the average decrease in the purity of an initial state.	1.0e+00 (8.3e-04) 0.9989496113763481, 0.0008299133991294943	1.0e+00 (2.1e-04) 1.0005225921249365, 0.0002093668657745526
${A}$ SPAM parameter of the exponential decay $Au^m$.	1.0e+00 (9.1e-03) 1.0264533464493306, 0.009055800567131357	1.1e+00 (4.5e-03) 1.0508505015629082, 0.0045097142572557425