Estimate¶
Base class for all estimate types, which store fit information returned from data analysis. |
|
An iterable container of |
|
Stores a joint estimate of a collection of system parameters. |
|
Stores estimates for the confusion matrices associated with readout errors. |
|
Organizes |
|
Organizes KNR estimates into a table with columns grouped by cycle (and possibly other keywords, see |
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
orRCalEstimate
.- 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
Estimate Collection¶
-
class
trueq.estimate.
EstimateCollection
(estimates=None)¶ An iterable container of
Estimate
s 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".SRBStreamlined Randomized BenchmarkingCliffords (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.3.4e-03 (8.7e-04) 0.003413001484111944, 0.00086886079700135710.0e+00 (4.7e-09) 0.0, 4.73509005258764e-09${p}$Decay parameter of the exponential decay $Ap^m$.1.0e+00 (1.2e-03) 0.9954493313545174, 0.00115848106266847611.0e+00 (5.1e-09) 1.0, 5.05076272276015e-09${A}$SPAM parameter of the exponential decay $Ap^m$.1.0e+00 (7.0e-03) 0.9966855448909828, 0.0070460992121430271.0e+00 (1.2e-07) 1.0, 1.1517511068997153e-07XRBExtended Randomized BenchmarkingCliffords (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.3.6e-03 (9.0e-04) 0.0036114424604055673, 0.00089695262092669922.7e-05 (1.3e-04) 2.664676431107793e-05, 0.0001288195791247159${e}_{S}$The probability of a stochastic error acting on the specified systems during a random gate.-2.0e-04 (2.2e-04) -0.00019844097629362345, 0.00022272161911552637-2.7e-05 (1.3e-04) -2.664676431107793e-05, 0.00012881957903769078${u}$The unitarity of the noise, that is, the average decrease in the purity of an initial state.1.0e+00 (5.9e-04) 1.0005292284418779, 0.00059404217656284091.0e+00 (2.7e-04) 1.0000568471879172, 0.00027482242488032437${A}$SPAM parameter of the exponential decay $Au^m$.1.0e+00 (6.8e-03) 0.9992518789972346, 0.0068156444984388081.1e+00 (7.1e-03) 1.061230272533739, 0.007096120955936254- Parameters
estimates (
None
|Estimate
-like |Iterable
) – Either a singleEstimate
or an iterable of several estimates. IfNone
is provided, theEstimateCollection
will be empty.
-
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".KeySetList of all the keys in the KeySetprotocol 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
-
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 anEstimate
and returns eitherTrue
orFalse
.filter – The filter on keys.
- Return type
-
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
.
-
sorted
(*names)¶ Returns an
EstimateCollection
sorted by the keys contained in the estimates, seetrueq.KeySet.sorted()
for more information.- Parameters
names (
str
) – One or more names that should take priority in sorting.- Return type
-
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 alsotrueq.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".KeySetList of all the keys in the KeySetprotocol 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 (
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 thekeep
orremove
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 optionskeep
orremove
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 optionskeep
orremove
may be used.kwargs – Name-value items to update the keys with. If a name specified here already exists after the
keep
orremove
process has taken place, it is updated.
- Returns
This estimate collection.
- Return type
- Raises
ValueError – If the mutally exclusive
keep
andremove
are both set toTrue
.
-
values
(name, *sort_by, skip_missing=True)¶ Returns all the values of a particular name across
Estimate
s in this collection.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() print(estimate_collection.values("A")) print(estimate_collection.values("A", "protocol"))
EstimatesTuple(name='A', vals=array([1.00202876, 1. , 1.00020118, 1.05849829]), stds=array([6.90403184e-03, 1.15175111e-07, 1.04496034e-02, 4.50016567e-03]), sweeps={}) EstimatesTuple(name='A', vals=array([1.00202876, 1. , 1.00020118, 1.05849829]), stds=array([6.90403184e-03, 1.15175111e-07, 1.04496034e-02, 4.50016567e-03]), 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 multiplesort_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 givenname
, or to includenumpy.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
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. IfNone
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
anderr
(if provided) do not match the length ofvalues
.
-
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
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.
-
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
|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. IfNone
, the labels from the key of this estimate are assumed.
- Returns
A new results object equal to the correction of the input.
- Return type
- 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
NormalEstimate
s 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)¶ -
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
-
property
-
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
-
property
-
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.9941353367533439, std=0.001351061121681891), (1,): EstimateTuple(name='p', val=0.9940428213779694, std=0.0012730440147022447), (2,): EstimateTuple(name='p', val=0.9962441951854712, std=0.0009377176553488851)}} Isolated {'p': {(0,): EstimateTuple(name='p', val=0.9938061600094177, std=0.0015666284321348646), (1,): EstimateTuple(name='p', val=0.9946301943495421, std=0.001055629432673273), (2,): EstimateTuple(name='p', val=0.9940117333474451, std=0.0015187916132098538)}}
- 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', '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
-
property
mean
¶ Alias for field number 0
-
property
std
¶ Alias for field number 1
-
property
subcycles
¶ Alias for field number 2
-
property
-
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
-
property
-
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()
androw_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 iscutoff * 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 ofcol_info
.Note
Cell row indices may change when
set_truncation()
is called.- Parameters
idx_cell_row (
int
) – An index belown_cell_rows
.idx_cell_col (
int
) – An index belown_cell_cols
.
- Return type
-
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 belown_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