laboneq_applications.analysis.fitting_helpers

This module contains helper function for experiment analyses.

cosine_oscillatory_decay(x, frequency, phase, decay_time, amplitude=1.0, oscillation_offset=0.0, exponential_offset=0.0, decay_exponent=1.0)

A function for modelling decaying oscillations such as Ramsey and Echo decay.

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_time	float	The exponential decay time.	required
amplitude	float	The amplitude of the cosine.	1.0
oscillation_offset	float	The offset of the oscillatory part of the function.	0.0
exponential_offset	float	The offset of the exponential-decay part of the function.	0.0
decay_exponent	float	Exponential decay exponent power	1.0

Returns:

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

cosine_oscillatory_decay_fit(x, data, param_hints=None)

Performs a fit of an exponentially decaying cosine model to data.

Parameters:

Name	Type	Description	Default
data	ArrayLike	the data to be fitted	required
x	ArrayLike	the independent variable	required
param_hints	dict[str, dict[str, float | bool | str]] | None	dictionary of guesses for the fit parameters. See the lmfit docstring for details on the form of the parameter hints dictionary: https://lmfit.github.io/lmfit-py/model.html#lmfit.model.Model.set_param_hint	None

Returns:

Type	Description
ModelResult	The lmfit result

cosine_oscillatory_fit(x, data, param_hints=None)

Performs a fit of a cosine model to data.

Parameters:

Name	Type	Description	Default
data	ArrayLike	the data to be fitted	required
x	ArrayLike	the independent variable	required
param_hints	dict | None	dictionary of guesses for the fit parameters. See the lmfit docstring for details on the form of the parameter hints dictionary: https://lmfit.github.io/lmfit-py/model.html#lmfit.model.Model.set_param_hint	None

Returns:

Type	Description
ModelResult	The lmfit result

exponential_decay_fit(x, data, param_hints=None)

Performs a fit of an exponential-decay model to data.

Parameters:

Name	Type	Description	Default
data	ArrayLike	the data to be fitted	required
x	ArrayLike	the independent variable	required
param_hints	dict[str, dict[str, float | bool | str]] | None	dictionary of guesses for the fit parameters. See the lmfit docstring for details on the form of the parameter hints dictionary: https://lmfit.github.io/lmfit-py/model.html#lmfit.model.Model.set_param_hint	None

Returns:

Type	Description
ModelResult	The lmfit result

find_oscillation_frequency_and_phase(time, data)

Extracts the frequency and phase of an oscillatory data set.

The frequency and phase are extracted using a fast-Fourier analysis.

Parameters:

Name	Type	Description	Default
data	ArrayLike	the data describing the oscillation	required
time	ArrayLike	the independent variable	required

Returns:

Type	Description
tuple[ArrayLike, ArrayLike]	the frequency and phase values

fit_data_lmfit(model, x, y, param_hints)

Performs a fit of model to the data (x,y).

Parameters:

Name	Type	Description	Default
model	Model | Callable | str	the model to fit to	required
x	ArrayLike	the independent variable	required
y	ArrayLike	the data to fit	required
param_hints	dict	dictionary of guesses for the fit parameters. See the lmfit docstring for details on the form of the parameter hints dictionary: https://lmfit.github.io/lmfit-py/model.html#lmfit.model.Model.set_param_hint	required

Returns:

Type	Description
ModelResult	the lmfit result

get_pi_pi2_xvalues_on_cos(x, frequency, phase)

Calculate the useful x-values of a cosine function.

Calculate the x-values of a cosine function of the form cos(x * frequency + phase) at which x * frequency + phase = n * pi and x * frequency + phase = n * pi + pi/2.

Only the values that are inside the interval [min(x), max(x)] are returned. Note: To achieve this, we have heuristically chosen n=+/-20 periods of the fitted cosine to make sure the entire range spanned by x. Then we use a mask to return only the pi and pi/2 values of the cosine within this range.

Parameters:

Name	Type	Description	Default
x	ArrayLike	array of x-values of the cosine function, corresponding for example to: - amplitudes in an amplitude-Rabi measurement - voltages in a resonator-spectroscopy-vs-dc-voltage measurement - phases in a dynamic-phase measurement	required
frequency	float | ArrayLike	the frequency of the cosine oscillation in angular units	required
phase	float | ArrayLike	the phase of the cosine oscillation in radians	required

the following array in the following order

Type	Description
float | ArrayLike	x-values for which cos(x * frequency + phase) = 1
float | ArrayLike	x-values for which cos(x * frequency + phase) = - 1
float | ArrayLike	x-values for which cos(x * frequency + phase) = 0 on the rising edge
float | ArrayLike	x-values for which cos(x * frequency + phase) = 0 on the falling edge

is_data_convex(x, y)

Check if a data set is convex.

The check is done by comparing the data points y to the line between the two end points of the data set (x[0], y[0]), (x[-1], y[-1]).

Parameters:

Name	Type	Description	Default
x	ArrayLike	x values of the data set	required
y	ArrayLike	y values of the data set	required

Returns:

Type	Description
bool	True if the data set is convex, else False.

linear(x, gradient, intercept)

A function for modelling linear.

Parameters:

Name	Type	Description	Default
x	ArrayLike	An array of values to evaluate the function at.	required
gradient	float	The gradient.	required
intercept	float	The offset.	required

Returns:

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

linear_fit(x, data, param_hints=None)

Performs a fit of a linear model to the data.

Parameters:

Name	Type	Description	Default
data	ArrayLike	the data to be fitted	required
x	ArrayLike	the independent variable	required
param_hints	dict[str, dict[str, float | bool | str]] | None	dictionary of guesses for the fit parameters. See the lmfit docstring for details on the form of the parameter hints dictionary: https://lmfit.github.io/lmfit-py/model.html#lmfit.model.Model.set_param_hint	None

Returns:

Type	Description
ModelResult	The lmfit result

lorentzian_fit(x, data, spectral_feature='auto', param_hints=None)

Fit a Lorentzian model to the data as a function of sweep_points.

This function determines whether the Lorentzian structure has a peak or a dip by performing two fits with two guess values, the min and the max of the data. To determine whether there is a peak or a dip, the distance between the value at the fitted peak/dip is compared to the mean of the data array: the larger distance is the true spectroscopy signal.

Parameters:

Name	Type	Description	Default
x	ArrayLike	numpy array of the independent variable	required
data	ArrayLike	numpy array of data to fit	required
spectral_feature	Literal['peak', 'dip', 'auto']	whether to perform the fit assuming the Lorentzian is pointing upwards ("peak") or downwards ("dip"). By default, this parameter is "auto", in which case, the routine tries to work out the orientation of the Lorentzian feature.	'auto'
param_hints	dict[str, dict[str, float | bool | str]] | None	dict with parameter hints for the fit (see fit_data_lmfit)	None

Returns:

Type	Description
ModelResult	an instance of lmfit.model.ModelResult