Estimate¶

`trueq.estimate.base.Estimate`	Base class for all estimate types, which store fit information returned from data analysis.
`trueq.estimate.EstimateCollection`	A iterable container of `Estimate`s 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.

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.

property key¶

The Key of this estimate, used for bookkeeping.

Type: Key

Estimate Collection¶

class trueq.estimate.EstimateCollection(estimates=None)¶

A 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]))

tq.Simulator().add_depolarizing(0.02).run(circs)

estimate_collection = circs.fit()
estimate_collection

SRB Streamlined Randomized Benchmarking	Cliffords (0,) Key: labels: (0,) protocol: SRB twirl: (('C', 0),)
${e}_{P}$ The probability of an error acting on the targeted systems during a random gate.	1.4e-02 (9.1e-04) 0.013812378396361902, 0.0009070220363592088
${p}$ Decay parameter of the exponential decay $Ap^m$.	9.8e-01 (1.2e-03) 0.9815834954715175, 0.0012093627151456116
${A}$ SPAM parameter of the exponential decay $Ap^m$.	9.7e-01 (1.7e-02) 0.9745975523343522, 0.01722533577846196
RCAL Readout Calibration	Confusion
(0,)	P(0 \| 0) = 1.000 P(1 \| 1) = 0.980 Confusion Matrix:

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

append(estimate)¶

Append a single Estimates or an iterable of several estimates to the collection.

Parameters: estimates (Estimate-like | Iterable) – Either a single Estimate (or child class), 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]))

tq.Simulator().add_depolarizing(0.02).run(circs)

estimate_collection = circs.fit()
estimate_collection.keys(protocol="SRB")

KeySet List of all the keys in the KeySet	protocol The characterization protocol used to generate a circuit.	labels	twirl The twirling groups used on each subsystem.
Key Key: labels: (0,) protocol: SRB twirl: (('C', 0),)	SRB	(0,)	(('C', 0),)

Parameters: filter – The filter on keys.
Return type: KeySet

subset(filter_fn=None, **filter)¶

Returns a trueq.estimate.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

generator

one_or_none(filter_fn=None, **filter)¶

If exactly one estimate in this collection matches the filter, returns that estimate, 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

generator

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.

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 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])
tq.Simulator().add_overrotation(0.08).run(circuits)
estimates = circuits.fit()

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

estimates.keys()

KeySet List of all the keys in the KeySet	protocol The characterization protocol used to generate a circuit.	labels	twirl The twirling groups used on each subsystem.	banana
Key Key: banana: 10 labels: (0,) protocol: SRB twirl: (('C', 0),)	SRB	(0,)	(('C', 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.

Raises

ValueError – If the mutally exclusive keep and remove are both set to True.

Returns

This estimate collection.

Return type

EstimateCollection

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])
tq.Simulator().add_depolarizing(0.02).run(circs)
estimate_collection = circs.fit()

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

EstimatesTuple(name='A', vals=array([1.02877136, 1.05134623, 0.97815722, 0.98888566]), stds=array([0.0256522 , 0.02454529, 0.0156006 , 0.01530004]), sweeps={})
EstimatesTuple(name='A', vals=array([0.97815722, 0.98888566, 1.02877136, 1.05134623]), stds=array([0.0156006 , 0.01530004, 0.0256522 , 0.02454529]), 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

EstimatesTuple

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.

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: nummpy.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

Readout Estimates¶

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.

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