reflection: utilities for processing reflection coefficient traces

Code author: Peter Kraus, Darko Kajfez

Provides several functions for processing reflection coefficient traces. Includes a few trace pruning functions, as well as several algorithms for fitting of quality factors to the reflection trace data. The use of the peak-height based pruning via prune_cutoff() and Kajfez’s circle fitting algorithm [Kajfez1994] via qf_kajfez() is recommended.

Functions

`prune_cutoff`(real, imag, freq[, near, ...])	Cutoff-based reflection coefficient trace prune.
`prune_gradient`(real, imag, freq[, near, ...])	Gradient-based reflection coefficient trace prune.
`qf_kajfez`(real, imag, freq[, iterations, output])	Kajfez's circle-fitting algorithm.
`qf_naive`(real, imag, freq[, output])	Naive quality factor fitting algorithm using FWHM.
`qf_lorentz`(real, imag, freq[, output])	Quality factor fitting algorithm using Lorentzian approximation.

[Kajfez1994] (1,2)

Kajfez, D. Linear fractional curve fitting for measurement of high Q factors, IEEE Transactions on Microwave Theory and Techniques 1994, 42, 1149 - 1153, DOI: https://doi.org/10.1109/22.299749

dgpost.transform.reflection.prune_cutoff(real, imag, freq, near=None, cutoff=0.4, output='pruned')

Cutoff-based reflection coefficient trace prune.

Prunes the reflection trace around a single peak position in \(|\Gamma|\). The pruning is performed using a cutoff value in the \(|\Gamma|\). Should be used with qf_kajfez(). Unless a frequency value using near is specified, the pruning is performed around the global maximum in \(\log(|\Gamma|)\).

Parameters:

real (Quantity) – A pint.Quantity object containing the real part of the reflection coefficient data, \(\text{Re}(\Gamma)\). Unitless.
imag (Quantity) – A pint.Quantity object containing the imaginary part of the reflection coefficient data, \(\text{Im}(\Gamma)\). Unitless.
freq (Quantity) – A pint.Quantity object containing the frequencies \(f\) corresponding to the reflection coefficient data. Defaults to Hz.
near (Optional[Quantity]) – A frequency used to select the point around which to prune. By default, pruning is performed around the highest peak in \(\text{log}|\Gamma|\). When set, pruning will be perfomed around any maximum in \(\text{log}|\Gamma|\) that exists within 10% of the trace size on either side of the selected point. This means that for a trace size of 20001 points, 2000 points below and 2000 points above the point corresponding to the selected frequency will be used to find a local maximum.
cutoff (float) – Relative peak height below which the reflection trace should be pruned. Uses a fraction of normalised \(|\Gamma|\). Defaults to 0.4.
output (str) – Name for the output namespace. Defaults to "pruned".

Returns:

retvals – A dictionary containing the pruned values of real, imag and freq data stored in namespaced pint.Quantities.

Return type:

dict[str, pint.Quantity]

dgpost.transform.reflection.prune_gradient(real, imag, freq, near=None, threshold=1e-06, output='pruned')

Gradient-based reflection coefficient trace prune.

Parameters:

real (Quantity) – A pint.Quantity object containing the real part of the reflection coefficient data, \(\text{Re}(\Gamma)\). Unitless.
imag (Quantity) – A pint.Quantity object containing the imaginary part of the reflection coefficient data, \(\text{Im}(\Gamma)\). Unitless.
freq (Quantity) – A pint.Quantity object containing the frequencies \(f\) corresponding to the reflection coefficient data. Defaults to Hz.
near (Optional[Quantity]) – A frequency used to select around which peak to prune. By default, pruning is performed around the highest peak in \(\text{log}|\Gamma|\). When set, pruning will be perfomed around any maximum in \(\text{log}|\Gamma|\) that exists within 10% of the trace size on either side of the selected point. This means that for a trace size of 20001 points, 2000 points below and 2000 points above the point corresponding to the selected frequency will be used to find a local maximum.
threshold (float) – Threshold for the gradient in the \(\text{abs}(\Gamma)\) below which the trace is pruned. Defaults to 1e-6.
output (str) – Name for the output namespace. Defaults to "pruned".

Returns:

ret – A dictionary containing the pruned values of real, imag and freq data stored in namespaced pint.Quantities.

Return type:

dict[str, pint.Quantity]

dgpost.transform.reflection.qf_kajfez(real, imag, freq, iterations=5, output=None)

Kajfez’s circle-fitting algorithm.

Adapted with permission from Q0REFL.m, which is a part of [Kajfez1994]. This fitting process attempts to fit a circle to a near-circular section of points on a Smith’s chart. It’s robust, quick, and reliable, and produces reasonable error estimates.

Parameters:

real (Quantity) – A pint.Quantity object containing the real part of the reflection coefficient data, \(\text{Re}(\Gamma)\). Unitless.
imag (Quantity) – A pint.Quantity object containing the imaginary part of the reflection coefficient data, \(\text{Im}(\Gamma)\). Unitless.
freq (Quantity) – A pint.Quantity object containing the frequencies \(f\) corresponding to the reflection coefficient data. Defaults to Hz.
iterations (int) – A number of iterations for circle-fitting refinement. Default is 5.
output (Optional[str]) – Name for the output namespace. Defaults to no namespace.

Returns:

ret – An optionally namespaced dictionary containing the fitted values of \(Q_0\) and \(f_0\) as pint.Quantities.

Return type:

dict[str, pint.Quantity]

dgpost.transform.reflection.qf_naive(real, imag, freq, output=None)

Naive quality factor fitting algorithm using FWHM.

This fit finds the central frequency \(f_0\), determines the full-width at the half-maximum \(\Delta f_{HM}\) by linear interpolation, and calculates the quality factor using \(Q_0 = f_0 / \Delta f_{HM}\).

Note

This quality factor fitting algorithm is unreliable and has been implemented only for testing purposes. Use qf_kajfez() for any production runs!

real: A pint.Quantity object containing the real part of the reflection coefficient data, \(\text{Re}(\Gamma)\). Unitless.
imag: A pint.Quantity object containing the imaginary part of the reflection coefficient data, \(\text{Im}(\Gamma)\). Unitless.
freq: A pint.Quantity object containing the frequencies \(f\) corresponding to the reflection coefficient data. Defaults to Hz.
output: Name for the output namespace. Defaults to no namespace.

Returns:: ret – An optionally namespaced dictionary containing the fitted values of \(Q_0\) and \(f_0\) as pint.Quantities.
Return type:: dict[str, pint.Quantity]

dgpost.transform.reflection.qf_lorentz(real, imag, freq, output=None)

Quality factor fitting algorithm using Lorentzian approximation.

This fit fits a Lorentzian to the (pruned) data. The \(f_0 = x_0\), and the \(Q_0\) is calculated from \(x_0 / \Delta x = x_0 / (2\gamma)\). Uncertainties of \(f_0\) and \(Q_0\) are calculated using the covariance matrix of the fit of \(L(x)\) to \(|\Gamma(f)|\).

Note

This quality factor fitting algorithm is unreliable and has been implemented only for testing purposes. Use qf_kajfez() for any production runs!

real: A pint.Quantity object containing the real part of the reflection coefficient data, \(\text{Re}(\Gamma)\). Unitless.
imag: A pint.Quantity object containing the imaginary part of the reflection coefficient data, \(\text{Im}(\Gamma)\). Unitless.
freq: A pint.Quantity object containing the frequencies \(f\) corresponding to the reflection coefficient data. Defaults to Hz.
output: Name for the output namespace. Defaults to no namespace.

Returns:: ret – An optionally namespaced dictionary containing the fitted values of \(Q_0\) and \(f_0\) as pint.Quantities.
Return type:: dict[str, pint.Quantity]