Computing the quantum error bars (tomographer.querrorbars)¶
Utilities for fitting the histogram data and computing the quantum error bars.

class
tomographer.querrorbars.
HistogramAnalysis
(final_histogram, ftox=(0, 1), fit_fn=None, **kwopts)¶ Bases:
object
Take care of analyzing histogram data obtained from performing a random walk over state space according to the distribution \(\mu_{B^n}(\cdot)\) defined by the tomography data, while collecting a histogram of a figure of merit.
Arguments to the constructor:
final_histogram: the final histogram returned by the random walks procedure. It is expected to be a tomographer.HistogramWithErrorBars.
ftox: Specify how to transform the figure of merit value f into the x coordinate for fit. Specify the transformation as a pair of values (h, s) in the relation x = s*(fh) or f=s*x+h, where h can be any constant, and where s must be plus or minus one. By default there is no transformation (x=f, corresponding to ftox=(0,1). For the fidelity, you should use x = 1f (ftox=(1,1)). For an entanglement witness, you might use x = 2f (ftox=(2,1)) for example.
fit_fn: a function which serves as fit model (for the log of the data). Specify None (the default fit model), the strings ‘a2’ or ‘direct’, or a custom callable to use as fit model. The ‘a2’ model (the default) is the “straightforward” one, using
fit_fn_a2()
, while the ‘direct’ model is aimed at better fit optimization stability, usingfit_fn_direct()
. If a custom callable is used, the quantum error bars cannot be automatically calculated and a call toquantumErrorBars()
will fail.Note
for the ‘direct’ fit model, it is currently not possible to enforce the condition that \(a  m/(2 x_0^2) \geq 0\) (required from \(a_2 \geq 0\)), so this condition must be checked manually. A warning will be issued if you call quantumErrorBars() in this case.
Changed in version 5.2: Support for additional builtin fit models.
additional named arguments in kwopts are passed on to
fit_histogram()
.

fitParameters
()¶ Return the parameters of the fit. The return value type is a named tuple whose fields are the argument names of the fit model fit_fn specified to the constructor. For example, for the default fit model
fit_fn_a2()
, the fields are (a2, a1, m, c).

fitRedChi2
()¶ Return the Reduced chisquraed statistic for the fit. Should be close to 1 for a good fit.

ftox
(f)¶ Convert an fvalue (value of the figure of merit) to an xvalue (natural variable of the fit model).

plot
(log_scale=False, xlabel='Distribution of values', plot_deskewed_gaussian=True, show_plot=True, curve_npts=200, **kwopts)¶ Plot the histogram data using matplotlib.
Parameters:  log_scale – if True, then use a logarithmic scale for the yaxis.
 xlabel – the label for the x axis (i.e., the figure of merit). Note this is the fvalue, not the xvalue.
 show_plot – if True (the default), then the plot is displayed immediately. If False, then the returned object has an additional method show() which can be used to display the plot.
 curve_npts – Number of points for the smooth fit curve plot.
The return value is an object with the attributes fig (the matplotlib figure object) and ax (the matplotlib axes object) which you can use to set specific custom properties. If you specified show_plot=False, then you should call the show() method on the returned object in order to show the plots (which is simply an alias for matplotlib.pyplot.show().

printFitParameters
(print_func=<builtin function print>, show_cov=False)¶ Display the fit parameters.
By default the values are displayed using print(…). You may specify a custom print function if you want them displayed somewhere else.
The fit parameters are returned in the same format as
fitParameters()
.

printQuantumErrorBars
(print_func=<builtin function print>)¶ Calculates and displays the values of the quantum error bars.
The quantum error bars are returned, provided in the same format as
quantumErrorBars()
.

quantumErrorBars
()¶ Calculate the quantum error bars.
This function is only available if you use the default fit model or one of the predefined fit models (i.e., if you didn’t specify a custom callable to the fit_fn argument in the constructor).
Returns a
QuantumErrorBars
named tuple.

xtof
(x)¶ Convert an xvalue (natural variable of the fit model) to the value of the figure of merit (f).

class
tomographer.querrorbars.
QuantumErrorBars
(f0, Delta, gamma, y0)¶ Bases:
tuple
A named tuple to store the quantum error bars.

Delta
¶ Alias for field number 1

f0
¶ Alias for field number 0

gamma
¶ Alias for field number 2

y0
¶ Alias for field number 3


tomographer.querrorbars.
load_tomorun_csv_histogram_file
(fn)¶ Load a histogram data file produced by executing the tomorun executable program (instead of via the
tomographer.tomorun
python module).The argument fn is the file name. It is expected to be a TABseparated CSV file where the first row (header) is blindly discarded. Any fourth column is disregarded.
Note
This function blindly assumes, without checking, that the first column is a list of linearly spaced values (which is what the tomorun executable always produces currently).
The returned value is a
tomographer.HistogramWithErrorBars
object.New in version 5.0.

tomographer.querrorbars.
fit_histogram
(normalized_histogram, fit_fn, ftox, **kwopts)¶ Fit the histogram data to a model function.
You should prefer to use the higherlevel
HistogramAnalysis
class directly, which calls this function internally and automatically. Only call this function if you are implementing very specific functionality and you know what you are doing.Parameters:  normalized_histogram – the final histogram data, provided as a
tomographer.HistogramWithErrorBars
class (or a subclass thereof), and normalized to a proper probability density (seetomographer.HistogramWithErrorBars.normalized()
).  ftox – a function which transforms the figure of merit values (fvalues) into the natural parameter for the fit function (xvalues). For example, for the fidelity, one should use \(x = 1  f\).
 threshold_fraction – a fraction (i.e. value between 0 and 1) of the maximum peak value over which the data points are kept; values below the threshold are ignored for the fit. (By default, threshold_fraction=0 and all points are considered; since the error bars are taken into account this should be fine in most cases.)
 kwopts – additional keyword options are passed on to scipy.optimize.curve_fit(…).
 normalized_histogram – the final histogram data, provided as a

class
tomographer.querrorbars.
FitParamToQuErrorBarsBase
¶ Bases:
object
Base class for converters between fit parameters for a specific fit model, and (standard) quantum error bars.
The members of this base class do not do anything. This class should be overridden to provide functionality. See for instance
FitParamToQuErrorBars_a2
andFitParamToQuErrorBars_direct
.New in version 5.2.

calcQuantumErrorBarsX
(fit_params)¶ Return the quantum error bars (as a :py:class`QuantumErrorBarsX` instance, i.e., specifying the parameters x0, Delta, gamma and y0) corresponding to the given fit parameters fit_params.

fitParamBounds
()¶ Return the bounds the fit parameters should be constrained to by default. (In a format suitable for scipy.curve_fit, see also HistogramAnalysis constructor.)

guessFitParamsFromQuErrorBarsX
(qu_err_bars)¶ Return a tuple of fit parameters corresponding to the given quantum error bars qu_err_bars, given as a
QuantumErrorBarsX
instance (i.e., parameters x0, Delta, gamma, along with the offset y0).


class
tomographer.querrorbars.
FitParamToQuErrorBars_a2
¶ Bases:
tomographer.querrorbars.FitParamToQuErrorBarsBase
Quantum error bars calculator for fit parameters resulting from fitting to the fit model function
fit_fn_a2()
.New in version 5.2.

calcQuantumErrorBarsX
(p)¶ Return the quantum error bars (as a :py:class`QuantumErrorBarsX` instance, i.e., specifying the parameters x0, Delta, gamma and y0) corresponding to the given fit parameters fit_params.

fitParamBounds
()¶ Return the bounds the fit parameters should be constrained to by default. (In a format suitable for scipy.curve_fit, see also HistogramAnalysis constructor.)

guessFitParamsFromQuErrorBarsX
(q, educated_guess=True)¶ Return a tuple of fit parameters corresponding to the given quantum error bars qu_err_bars, given as a
QuantumErrorBarsX
instance (i.e., parameters x0, Delta, gamma, along with the offset y0).


tomographer.querrorbars.
fit_fn_a2
(x, a2, a1, m, c)¶ A standard fit model for the logarithm of the histogram data. The xvalues are not directly the figure of merit, but may be possibly transformed via a ftox transformation (see
HistogramAnalysis
).Returns the value
\[y(x) = a_2\,x^2  a_1\,x + m\log(x) + c \ ,\]which is the default fit model. If a NumPy array is specified as x, the function is evaluated for all the given values and the values are returned as a vector.
New in version 5.2.

class
tomographer.querrorbars.
FitParamToQuErrorBars_direct
¶ Bases:
tomographer.querrorbars.FitParamToQuErrorBarsBase
Quantum error bars calculator for fit parameters resulting from fitting to the fit model function
fit_fn_direct()
.New in version 5.2.

calcQuantumErrorBarsX
(p)¶ Return the quantum error bars (as a :py:class`QuantumErrorBarsX` instance, i.e., specifying the parameters x0, Delta, gamma and y0) corresponding to the given fit parameters fit_params.

fitParamBounds
()¶ Return the bounds the fit parameters should be constrained to by default. (In a format suitable for scipy.curve_fit, see also HistogramAnalysis constructor.)

guessFitParamsFromQuErrorBarsX
(q)¶ Return a tuple of fit parameters corresponding to the given quantum error bars qu_err_bars, given as a
QuantumErrorBarsX
instance (i.e., parameters x0, Delta, gamma, along with the offset y0).


tomographer.querrorbars.
fit_fn_direct
(x, a, x0, y0, m)¶ The new “direct” fit model for the logarithm of the histogram data. The xvalues are not directly the figure of merit, but may be possibly transformed via a ftox transformation (see
HistogramAnalysis
).The fit model is exactly the same as \(y(x)\) given by
fit_fn_a2()
, except that it is parametrized in a different way in the hope that the fit optimization is more stable. Namely, the fit function is rewritten as a function of \((a, x_0, y_0, m)\) as:\[y(x) =  a (x  x_0)^2 + y_0 + z_m(x / x_0)\ .\]New in version 5.2.

tomographer.querrorbars.
fit_fn_default
(x, a2, a1, m, c)¶ The default fit model. This is currently an alias for
fit_fn_a2()
, but this might change in a future version of tomographer.

tomographer.querrorbars.
fit_models
= {'a2': FitModelSpec(fn=<function fit_fn_a2 at 0x10be53840>, converter=<tomographer.querrorbars.FitParamToQuErrorBars_a2 object at 0x10de295c0>), 'direct': FitModelSpec(fn=<function fit_fn_direct at 0x10fc1eae8>, converter=<tomographer.querrorbars.FitParamToQuErrorBars_direct object at 0x10fc094a8>)}¶ Dictionary of known, builtin fit models. The key is the the builtin name (e.g., ‘a2’), and the value is a
FitModelSpec
named tuple type with information about the function to use as fit model as well as a converter implementation allowing to convert the fit parameters to quantum error bars.New in version 5.2.

class
tomographer.querrorbars.
QuantumErrorBarsX
(x0, Delta, gamma, y0)¶ Bases:
tuple
A named tuple to store the quantum error bars, but where x0 is used instead of f0, i.e., the figure of merit is not transformed according to the xtof transformation specified to the
HistogramAnalysis
constructor.This class should only be used internally.
New in version 5.2.

Delta
¶ Alias for field number 1

gamma
¶ Alias for field number 2

x0
¶ Alias for field number 0

y0
¶ Alias for field number 3


class
tomographer.querrorbars.
FitModelSpec
(fn, converter)¶ Bases:
tuple
Type used to specify a fit model function along with a “converter” implementation.
See
fit_models
.New in version 5.2.

converter
¶ Alias for field number 1

fn
¶ Alias for field number 0


tomographer.querrorbars.
zm
(w, m)¶ Returns the “skewing” portion of \(y(x)\).
The function is defined as
\[z_m(w) = \frac{m}{2} w^2  2m\,w + m \ln w + \frac{3m}{2} \ ,\]and relates to the difference of our fit model with its deskewed version as \(y(x)  y_{\mathrm{deskewed}}(x) = z_m(x/x_0)\).
New in version 5.2.

tomographer.querrorbars.
qu_error_bars_from_deskewed
(xtof, m, a, x0, y0)¶ Deprecated since version 5.2: Use
FitParamToQuErrorBars_a2
instead.

tomographer.querrorbars.
qu_error_bars_to_deskewed_c
(ftox, f0, Delta, gamma, y0=1)¶ Deprecated since version 5.2: Use
FitParamToQuErrorBars_a2
instead.

tomographer.querrorbars.
deskew_logmu_curve
(a2, a1, m, c)¶ Deprecated since version 5.2: Use
FitParamToQuErrorBars_a2
instead.Deskew the fit model to obtain a second order approximation at the peak maximum (see details of how to calculate the quantum error bars in our paper).
Usage:
(a, x0, y0) = deskew_logmu_curve(a2, a1, m, c)

tomographer.querrorbars.
reskew_logmu_curve
(m, a, x0, y0)¶ Deprecated since version 5.2: Use
FitParamToQuErrorBars_a2
instead.