qblox_scheduler.analysis.fitting_models#

Models and fit functions to be used with the lmfit fitting framework.

Classes#

LorentzianModel

Model for data which follows a Lorentzian function.

CosineModel

Exemplary lmfit model with a guess for a cosine.

ResonatorModel

Resonator model

ExpDecayModel

Model for an exponential decay, such as a qubit T1 measurement.

RabiModel

Model for a Rabi oscillation as a function of the microwave drive amplitude.

DecayOscillationModel

Model for a decaying oscillation which decays to a point with 0 offset from

Functions#

get_model_common_doc(→ str)

Returns a common docstring to be used with custom fitting

get_guess_common_doc(→ str)

Returns a common docstring to be used for the guess()

mk_seealso(→ str)

Returns a sphinx seealso pointing to a function.

hanger_func_complex_SI(→ complex)

This is the complex function for a hanger (lambda/4 resonator).

cos_func(→ float)

An oscillating cosine function:

lorentzian_func(→ float)

A Lorentzian function.

exp_decay_func(→ float)

This is a general exponential decay function:

exp_damp_osc_func(t, tau, n_factor, frequency, phase, ...)

A sinusoidal oscillation with an exponentially decaying envelope function:

resonator_phase_guess(→ tuple[float, float])

Guesses the phase velocity in resonator spectroscopy,

fft_freq_phase_guess(→ tuple[float, float])

Guess for a cosine fit using FFT, only works for evenly spaced points.

Module Contents#

get_model_common_doc() → str[source]#

Returns a common docstring to be used with custom fitting Model s.

Usage example for a custom fitting model

See the usage example at the end of the ResonatorModel source-code:

get_guess_common_doc() → str[source]#

Returns a common docstring to be used for the guess() method of custom fitting Model s.

Usage example for a custom fitting model

See the usage example at the end of the ResonatorModel source-code:

mk_seealso(function_name: str, role: str = 'func', prefix: str = '\n\n', module_location: str = '.') → str[source]#

Returns a sphinx seealso pointing to a function.

Intended to be used for building custom fitting model docstrings.

Usage example for a custom fitting model

See the usage example at the end of the ResonatorModel source-code:

Parameters:

  • function_name – name of the function to point to

  • role – a sphinx role, e.g. "func"

  • prefix – string preceding the seealso

  • module_location – can be used to indicate a function outside this module, e.g., my_module.submodule which contains the function.

Returns:

: resulting string

hanger_func_complex_SI(f: float, fr: float, Ql: float, Qe: float, A: float, theta: float, phi_v: float, phi_0: float, alpha: float = 1) → complex[source]#

This is the complex function for a hanger (lambda/4 resonator).

Parameters:

  • f – frequency

  • fr – resonance frequency

  • A – background transmission amplitude

  • Ql – loaded quality factor of the resonator

  • Qe – magnitude of extrinsic quality factor Qe = |Q_extrinsic|

  • theta – phase of extrinsic quality factor (in rad)

  • phi_v – phase to account for propagation delay to sample

  • phi_0 – phase to account for propagation delay from sample

  • alpha – slope of signal around the resonance

Returns:

: complex valued transmission

See eq. S4 from Bruno et al. (2015) ArXiv:1502.04082.

\[S_{21} = A \left(1+\alpha \frac{f-f_r}{f_r} \right) \left(1- \frac{\frac{Q_l}{|Q_e|}e^{i\theta} }{1+2iQ_l \frac{f-f_r}{f_r}} \right) e^{i (\phi_v f + \phi_0)}\]

The loaded and extrinsic quality factors are related to the internal and coupled Q according to:

\[\frac{1}{Q_l} = \frac{1}{Q_c}+\frac{1}{Q_i}\]

and

\[\frac{1}{Q_c} = \mathrm{Re}\left(\frac{1}{|Q_e|e^{-i\theta}}\right)\]
cos_func(x: float, frequency: float, amplitude: float, offset: float, phase: float = 0) → float[source]#

An oscillating cosine function:

\(y = \mathrm{amplitude} \times \cos(2 \pi \times \mathrm{frequency} \times x + \mathrm{phase}) + \mathrm{offset}\)

Parameters:

  • x – The independent variable (time, for example)

  • frequency – A generalized frequency (in units of inverse x)

  • amplitude – Amplitude of the oscillation

  • offset – Output signal vertical offset

  • phase – Phase offset / rad

Returns:

: Output signal magnitude

lorentzian_func(x: float, x0: float, width: float, a: float, c: float) → float[source]#

A Lorentzian function.

\[y = \frac{a*\mathrm{width}}{\pi(\mathrm{width}^2 + (x - x_0)^2)} + c\]
Parameters:

  • x – independent variable

  • x0 – horizontal offset

  • width – Lorenztian linewidth

  • a – amplitude

  • c – vertical offset

Returns:

: Lorentzian function

exp_decay_func(t: float, tau: float, amplitude: float, offset: float, n_factor: float) → float[source]#

This is a general exponential decay function:

\(y = \mathrm{amplitude} \times \exp\left(-(t/\tau)^\mathrm{n\_factor}\right) + \mathrm{offset}\)

Parameters:

  • t – time

  • tau – decay time

  • amplitude – amplitude of the exponential decay

  • offset – asymptote of the exponential decay, the value at t=infinity

  • n_factor – exponential decay factor

Returns:

: Output of exponential function as a float

exp_damp_osc_func(t: float, tau: float, n_factor: float, frequency: float, phase: float, amplitude: float, offset: float)[source]#

A sinusoidal oscillation with an exponentially decaying envelope function:

\(y = \mathrm{amplitude} \times \exp\left(-(t/\tau)^\mathrm{n\_factor}\right)(\cos(2\pi\mathrm{frequency}\times t + \mathrm{phase}) + \mathrm{oscillation_offset}) + \mathrm{exponential_offset}\)

Parameters:

  • t – time

  • tau – decay time

  • n_factor – exponential decay factor

  • frequency – frequency of the oscillation

  • phase – phase of the oscillation

  • amplitude – initial amplitude of the oscillation

  • offset – Output signal vertical offset

Returns:

: Output of decaying cosine function as a float

class LorentzianModel(*args, **kwargs)[source]#

Bases: lmfit.model.Model

Model for data which follows a Lorentzian function.

Uses the function lorentzian_func() as the defining equation.

guess(data: numpy.typing.NDArray, **kws) → lmfit.parameter.Parameters[source]#

Guess some initial values for the model based on the data.

class CosineModel(*args, **kwargs)[source]#

Bases: lmfit.model.Model

Exemplary lmfit model with a guess for a cosine.

Note

The lmfit.models module provides several fitting models that might fit your needs out of the box.

guess(data, x, **kws) → lmfit.parameter.Parameters[source]#

Guess parameters based on the data

Parameters:

  • data (np.ndarray) – Data to fit to

  • x (np.ndarray) – Independent variable

class ResonatorModel(*args, **kwargs)[source]#

Bases: lmfit.model.Model

Resonator model

Implementation and design patterns inspired by the complex resonator model example (lmfit documentation).

guess(data, **kws) → lmfit.parameter.Parameters[source]#

Guess starting values for the parameters of a Model.

This is not implemented for all models, but is available for many of the built-in models.

Parameters:

  • data (array_like) – Array of data (i.e., y-values) to use to guess parameter values.

  • x (array_like) – Array of values for the independent variable (i.e., x-values).

  • **kws (optional) – Additional keyword arguments, passed to model function.

Returns:

Parameters Initial, guessed values for the parameters of a Model.

Raises:

NotImplementedError – If the guess method is not implemented for a Model.

Notes

Should be implemented for each model subclass to run self.make_params(), update starting values and return a Parameters object.

Changed in version 1.0.3: Argument x is now explicitly required to estimate starting values.

class ExpDecayModel(*args, **kwargs)[source]#

Bases: lmfit.model.Model

Model for an exponential decay, such as a qubit T1 measurement.

guess(data, **kws) → lmfit.parameter.Parameters[source]#

Guess starting values for the parameters of a Model.

This is not implemented for all models, but is available for many of the built-in models.

Parameters:

  • data (array_like) – Array of data (i.e., y-values) to use to guess parameter values.

  • x (array_like) – Array of values for the independent variable (i.e., x-values).

  • **kws (optional) – Additional keyword arguments, passed to model function.

Returns:

Parameters Initial, guessed values for the parameters of a Model.

Raises:

NotImplementedError – If the guess method is not implemented for a Model.

Notes

Should be implemented for each model subclass to run self.make_params(), update starting values and return a Parameters object.

Changed in version 1.0.3: Argument x is now explicitly required to estimate starting values.

class RabiModel(*args, **kwargs)[source]#

Bases: lmfit.model.Model

Model for a Rabi oscillation as a function of the microwave drive amplitude. Phase of oscillation is fixed at \(\pi\) in order to ensure that the oscillation is at a minimum when the drive amplitude is 0.

guess(data, **kws) → lmfit.parameter.Parameters[source]#

Guess starting values for the parameters of a Model.

This is not implemented for all models, but is available for many of the built-in models.

Parameters:

  • data (array_like) – Array of data (i.e., y-values) to use to guess parameter values.

  • x (array_like) – Array of values for the independent variable (i.e., x-values).

  • **kws (optional) – Additional keyword arguments, passed to model function.

Returns:

Parameters Initial, guessed values for the parameters of a Model.

Raises:

NotImplementedError – If the guess method is not implemented for a Model.

Notes

Should be implemented for each model subclass to run self.make_params(), update starting values and return a Parameters object.

Changed in version 1.0.3: Argument x is now explicitly required to estimate starting values.

class DecayOscillationModel(*args, **kwargs)[source]#

Bases: lmfit.model.Model

Model for a decaying oscillation which decays to a point with 0 offset from the centre of the oscillation (as in a Ramsey experiment, for example).

guess(data, **kws) → lmfit.parameter.Parameters[source]#

Guess starting values for the parameters of a Model.

This is not implemented for all models, but is available for many of the built-in models.

Parameters:

  • data (array_like) – Array of data (i.e., y-values) to use to guess parameter values.

  • x (array_like) – Array of values for the independent variable (i.e., x-values).

  • **kws (optional) – Additional keyword arguments, passed to model function.

Returns:

Parameters Initial, guessed values for the parameters of a Model.

Raises:

NotImplementedError – If the guess method is not implemented for a Model.

Notes

Should be implemented for each model subclass to run self.make_params(), update starting values and return a Parameters object.

Changed in version 1.0.3: Argument x is now explicitly required to estimate starting values.

resonator_phase_guess(s21: numpy.ndarray, freq: numpy.ndarray) → tuple[float, float][source]#

Guesses the phase velocity in resonator spectroscopy, based on the median of all the differences between consecutive phases.

Parameters:

  • s21 – Resonator S21 data

  • freq – Frequency of the spectroscopy pulse

Returns:

phi_0:

Guess for the phase offset

phi_v:

Guess for the phase velocity

fft_freq_phase_guess(data: numpy.ndarray, t: numpy.ndarray) → tuple[float, float][source]#

Guess for a cosine fit using FFT, only works for evenly spaced points.

Parameters:

  • data – Input data to FFT

  • t – Independent variable (e.g. time)

Returns:

freq_guess:

Guess for the frequency of the cosine function

ph_guess:

Guess for the phase of the cosine function