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*(f-h) 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 = 1-f (ftox=(1,-1)). For an entanglement witness, you might use x = 2-f (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, using fit_fn_direct(). If a custom callable is used, the quantum error bars cannot be automatically calculated and a call to quantumErrorBars() 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 built-in 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 chi-squraed statistic for the fit. Should be close to 1 for a good fit.

ftox(f)

Convert an f-value (value of the figure of merit) to an x-value (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 y-axis.
  • xlabel – the label for the x axis (i.e., the figure of merit). Note this is the f-value, not the x-value.
  • 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=<built-in 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=<built-in 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 x-value (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 TAB-separated 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 higher-level 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 (see tomographer.HistogramWithErrorBars.normalized()).
  • ftox – a function which transforms the figure of merit values (f-values) into the natural parameter for the fit function (x-values). 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(…).
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 and FitParamToQuErrorBars_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 x-values are not directly the figure of merit, but may be possibly transformed via a f-to-x 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 x-values are not directly the figure of merit, but may be possibly transformed via a f-to-x 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, built-in fit models. The key is the the built-in 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.

De-skew 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.