laboneq.analysis

Utilities mainly useful for analysing results and experiments.

calculate_integration_kernels(state_traces)

Calculates the optimal kernel arrays for state discrimination given a set of reference traces corresponding to measurement of each qubit state. The calculated kernels can directly be used as kernels in acquire statements.

Parameters:

Name	Type	Description	Default
state_traces	list[NDArray]	List of complex-valued reference traces, one array per state. The reference traces are typically obtained by an averaged scope measurement of the readout resonator response when the qudit is prepared in a certain state.	required

Raises:

Type	Description
ValueError	If any element of state_traces contains NaN values.

Deprecated in version 2.26.0

Deprecated in favor of calculate_integration_kernels_thresholds which additionally supplies the threshold information.

calculate_integration_kernels_thresholds(state_traces)

Calculates the optimal kernel arrays and threshold values for state discrimination given a set of reference traces corresponding to measurement of each qubit state.

Parameters:

Name	Type	Description	Default
state_traces	list[NDArray]	List of complex-valued reference traces, one array per state. The reference traces are typically obtained by an averaged scope measurement of the readout resonator response when the qudit is prepared in a certain state.	required

Returns:

Name	Type	Description
kernels	list[PulseSampled]	List of kernels to be used directly as an argument to acquire statements.
thresholds	list[float]	List of thresholds that can be used in the threshold setting when calibrating acquire signals.

Raises:

Type	Description
ValueError	If any element of state_traces contains NaN values.

Added in version 2.26.0

Added extended functionality to additionally supply threshold information.

laboneq.analysis.fitting

Fitting functions for modeling results in common quantum computing experiments.

exponential_decay(x, decay_rate, offset, amplitude=1.0)

A function for modelling exponential decay such as T1 or T2 decay.

The form of the function is a decaying exponential:

\[ f(x) = amplitude \times \exp(-decay \text{\textunderscore} rate \times x) + offset \]

Calling this function evaluates it. One may also fit this function by calling exponential_decay.fit which calls fit with this function.

Parameters:

Name	Type	Description	Default
x	ArrayLike	An array of values to evaluate the function at.	required
decay_rate	float	The exponential decay rate.	required
offset	float	The offset of the function.	required
amplitude	float	The amplitude multiplying the exponential.	1.0

Returns:

Name	Type	Description
values	ArrayLike	The values of the decay function at the times x.

Examples:

Evaluate the function:

x = np.linspace(0, 10, 100)
values = exponential_decay(x, 0.1, 0.5, 2.0)

Fit the function:

x = np.linspace(0, 10, 100)
popt, pcov = exponential_decay.fit(x, values, 0, 0, 1.0)
decay_rate, offset, amplitude = popt

fano_lineshape(x, width, position, amplitude, fano=0.0, offset=0.5)

A function for modelling a Fano resonance.

The form of the Fano line-shape function is:

\[ f(x) = offset + amplitude \times \frac{fano \times width + x - position) ** 2}{ width^2 + (x - position)^2} \]

Calling this function evaluates it. One may also fit this function by calling fano_lineshape.fit which calls fit with this function.

Parameters:

Name	Type	Description	Default
x	ArrayLike	An array of values to evaluate the function at.	required
width	float	The width of the resonance.	required
position	float	The position of the resonance peak.	required
amplitude	float	The amplitude of the resonance.	required
fano	float	The Fano parameter.	0.0
offset	float	The offset of the resonance.	0.5

Returns:

Name	Type	Description
values	ArrayLike	The values of the line-shape at the times x.

Examples:

Evaluate the function:

x = np.linspace(0, 10, 100)
values = fano_lineshape(x, 2.0, 0.5, 3.0, 1.0, 0.5, 0.1)

Fit the function:

x = np.linspace(0, 10, 100)
popt, pcov = fano_lineshape.fit(x, values, 1.0, 0.0, 1.0, 0.0, 0.0)
width, position, amplitude = popt

fit(func, x, y, *args, bounds=None, plot=False)

Fit the given model.

This function is a lightweight wrapper around scipy.optimize.curve_fit.

Parameters:

Name	Type	Description	Default
func	Callable	The model to fit. The model function must accept an initial parameter x, the points to evaluate the function at, and return y, the values at those points. The function must also accept, as positional parameters, the parameters passed in *args to fit.	required
x	ArrayLike	The points to fit the function at.	required
y	ArrayLike	The data to fit.	required
*args	tuple[float, ...]	The initial values of the model parameters. Only the parameters supplied here are fitted. Any parameters of func not passed here are not fitted and retain their default values.	()
bounds	tuple[list, list] | None	If specified, a tuple containing the (lower, upper) bounds for the model parameters. The lower and upper bounds are both lists of the same length as args. I.e. there should be a bound for each of the specified model parameters.	None
plot	bool	If True, also plot the fit using matplotlib.pyplot.	False

Returns:

Name	Type	Description
popt	ArrayLike	The fitted values of the model parameters.
pcov	ArrayLike	The covariance matrix of the fit. The standard deviations of the fitted values may be calculate using: perr = np.sqrt(np.diag(pcov)).

Examples:

def line(x, m, c):
    return m * x + c


x = np.linspace(0, 10, 100)
data = np.random(*x.shape)
popt, pcov = fit(line, x, data, 1, 0, bounds=([0, 0], [10, 10]))

lorentzian(x, width, position, amplitude, offset)

A function for modelling a Lorentzian spectrum.

The form of the spectrum function is:

\[ f(x) = offset + amplitude \times \frac{width}{width^2 + (x - position)^2} \]

An inverted spectrum may be modelled by specifying a negative amplitude.

Calling this function evaluates it. One may also fit this function by calling lorentzian.fit which calls fit with this function.

Parameters:

Name	Type	Description	Default
x	ArrayLike	An array of values to evaluate the function at.	required
width	float	The width of the spectrum.	required
position	float	The position of the spectrum peak.	required
amplitude	float	The amplitude of the spectrum. Specify a negative amplitude for an inverted spectrum.	required
offset	float	The offset of the spectrum.	required

Returns:

Name	Type	Description
values	ArrayLike	The values of the spectrum at the times x.

Examples:

Evaluate the function:

x = np.linspace(0, 10, 100)
values = lorentzian(x, 2.0, 0.5, 3.0, 0.1)

Fit the function:

x = np.linspace(0, 10, 100)
popt, pcov = lorentzian.fit(x, values, 1.0, 0.0, 1.0, 0.0)
width, position, amplitude, offset = popt

oscillatory(x, frequency, phase, amplitude=1.0, offset=0.0)

A function for modelling oscillartions such as Rabi oscillations.

The form of the function is a cosine:

\[ f(x) = amplitude \times \cos(frequency \times x + phase) + offset \]

Calling this function evaluates it. One may also fit this function by calling oscillatory.fit which calls fit with this function.

Parameters:

Name	Type	Description	Default
x	ArrayLike	An array of values to evaluate the function at.	required
frequency	float	The frequency of the cosine.	required
phase	float	The phase of the cosine.	required
amplitude	float	The amplitude of the cosine.	1.0
offset	float	The offset of the cosine.	0.0

Returns:

Name	Type	Description
values	ArrayLike	The values of the oscillatory function at the times x.

Examples:

Evaluate the function:

x = np.linspace(0, 10, 100)
values = oscillatory(x, 2, np.pi / 2, 0.5, 0.1)

Fit the function:

x = np.linspace(0, 10, 100)
popt, pcov = oscillatory.fit(x, values, 1, 0, 0, 0)
frequency, phase, amplitude, offset = popt

oscillatory_decay(x, frequency, phase, decay_rate, amplitude=1.0, offset=0.0)

A function for modelling decaying oscillations such as Ramsey decay.

The form of the function is a decaying cosine:

\[ f(x) = amplitude \times \cos(frequency \times x + phase) \exp(-decay \text{\textunderscore} rate \times x) + offset \]

Calling this function evaluates it. One may also fit this function by calling oscillatory_decay.fit which calls fit with this function.

Parameters:

Name	Type	Description	Default
x	ArrayLike	An array of values to evaluate the function at.	required
frequency	float	The frequency of the cosine.	required
phase	float	The phase of the cosine.	required
decay_rate	float	The exponential decay rate.	required
amplitude	float	The amplitude of the cosine.	1.0
offset	float	The offset of the function.	0.0

Returns:

Name	Type	Description
values	ArrayLike	The values of the decaying oscillation function at the times x.

Examples:

Evaluate the function:

x = np.linspace(0, 10, 100)
values = oscillatory_decay(x, 2, np.pi / 2, 0.1, 0.5, 0.1)

Fit the function:

x = np.linspace(0, 10, 100)
popt, pcov = oscillatory_decay.fit(x, values, 1, 0, 0, 0, 0)
frequency, phase, decay_rate, amplitude, offset = popt