# Estimate¶

 trueq.estimate.base.Estimate Base class for all estimate types, which store fit information returned from data analysis. trueq.estimate.EstimateCollection An iterable container of Estimates with several convenience functions which make it easier to select specific estimates. 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 NormalEstimates into a parent-children structure based on twirling groups in a way that makes it easier to compare values. trueq.estimate.knr_table.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.Estimate(key)

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

to_dict()

Converts the estimate to a dictionary representation.

Note

The stored Key is also converted to a dictionary.

Return type

dict

classmethod 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

## Estimate Collection¶

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

circs = tq.make_srb([0], [4, 64])
circs.append(tq.make_rcal([0]))

estimate_collection = circs.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] ${e}_{F}$ The probability of an error acting on the targeted systems during a random gate. 1.5e-02 (1.2e-03) 0.015049615972341918, 0.0012284698870109654 ${p}$ Decay parameter of the exponential decay $Ap^m$. 9.8e-01 (1.6e-03) 0.9799338453702108, 0.0016379598493479535 ${A}$ SPAM parameter of the exponential decay $Ap^m$. 1.0e+00 (1.4e-02) 1.0106858869184925, 0.013608415715845937 RCAL Readout Calibration Confusion (0,) P(0 | 0) = 1.000 P(1 | 1) = 0.980 Confusion Matrix: 1.000 0.020 0.980 Key: labels: (0,) protocol: RCAL
Parameters

estimates (None | 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.

keys(**filter)

Returns the set of all keys of this estimate collection matching the given filter.

import trueq as tq

circs = tq.make_srb([0], [4, 64])
circs.append(tq.make_rcal([0]))

estimate_collection = circs.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] SRB (0,) Cliffords on [0]
Parameters

filter – The filter on keys.

Return type

KeySet

subset(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.

Parameters
• 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 | None

sorted(*names)

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

Parameters

names (str) – One or more names 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, [4, 10])
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] SRB (0,) Cliffords on [0] 10
Parameters
• other (Key | dict) – One or more dict-like objects 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.

values(name, *sort_by, skip_missing=True)

Returns all the values of a particular name across Estimates in this collection.

import trueq as tq

circs = tq.make_xrb([[0], [1]], [4, 64])
circs += tq.make_srb([[0], [1]], [4, 64])
estimate_collection = circs.fit()

print(estimate_collection.values("A"))
print(estimate_collection.values("A", "protocol"))

EstimatesTuple(name='A', vals=array([1.01838753, 0.97718424, 0.97971248, 0.97756703]), stds=array([0.02016997, 0.02687712, 0.01628428, 0.01494197]), sweeps={})
EstimatesTuple(name='A', vals=array([0.97971248, 0.97756703, 1.01838753, 0.97718424]), stds=array([0.01628428, 0.01494197, 0.02016997, 0.02687712]), sweeps={'protocol': ['SRB', 'SRB', 'XRB', 'XRB']})

Parameters
• name (str) – The name of the parameter to extract.

• sort_by (str) – The name(s) of the keys to sort values by. The ordering is lexicographical if multiple sort_by names are provided. If this parameter is not provided, the order of this collection is preserved.

• skip_missing (bool) – Whether to skip estimates without the given name, or to include numpy.nan values at these locations.

Return type

tuple

plot = PlottingSuite(<8 plotters>)

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

## Normal Estimates¶

class trueq.estimate.NormalEstimate(key, names, values, err=None, decays=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 (None | 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.

• decays (None | dict) – Optional, the data used to estimate the values. If not provided, this defaults to an empty dictionary.

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 decays

The data used to estimate the values. If decays=None was provided, this will be an empty dictionary.

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

class trueq.estimate.RCalEstimate(key, values)

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.

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 circuit
circuit = tq.Circuit([{0: tq.Gate.x}, {range(5): tq.Meas()}])

# construct a simulator with readout error
sim.run(circuit)

# create an RCAL estimate with a 5000 shot simulation
rcal_circuits = tq.make_rcal(range(5))
sim.run(rcal_circuits, 10000)
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 | None) – 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

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

circuits = tq.make_cb({range(3): tq.Gate.x}, [0, 3])
circuits.append(tq.make_cb({range(2): tq.Gate.x}, [0, 3]))
circuits.append(tq.make_cb({1: tq.Gate.x}, [0, 3]))

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

circuits.append(tq.make_cb({(0, 5, 2): tq.Gate.x}, [0, 3]))

sim.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)
property labels

Alias for field number 2

property members

Alias for field number 4

property names

Alias for field number 3

property parent

Alias for field number 0

property protocols

Alias for field number 5

property title

Alias for field number 1

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

Alias for field number 2

property protocol

Alias for field number 3

property title

Alias for field number 0

property 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], [1, 4])
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=1.3320695095112127, std=0.6444554628267976), (1,): EstimateTuple(name='p', val=0.005760286093565001, std=0.29346151998093944), (2,): EstimateTuple(name='p', val=1.3359989408553568, std=1.883299886542553)}}
Isolated
{'p': {(0,): EstimateTuple(name='p', val=1.290662880674033, std=1.3095989067395606), (1,): EstimateTuple(name='p', val=0.006920373219046933, std=0.010751601107894096), (2,): EstimateTuple(name='p', val=0.9761813628953947, std=0.3401830036911222)}}


Parameters

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

Return type

list

## KNR Data Table¶

class trueq.estimate.knr_table.KnrDataTable(fit_or_circuits, group_by=('name', 'cycle', '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 (“cycle”, “chip”, “twirl”). The keywords “cycle” and “twirl” should appear in this list.

class Cell(mean, std, subcycles)

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

property mean

Alias for field number 0

property std

Alias for field number 1

property subcycles

Alias for field number 2

class Row(sort_key, degens, param_names, latex)

Storage type for row descriptions, which index Cell rows.

property degens

Alias for field number 1

property latex

Alias for field number 3

property param_names

Alias for field number 2

property sort_key

Alias for field number 0

set_truncation(cutoff, relative_to_max=True, cl=0.95)

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) – The confidence level at which to cutoff.

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