qftrace: Network analyser trace file parser

The module handles the reading and processing of the network analyzer traces, containing the reflection coefficient as a function of the sweeped frequency, \(\Gamma(f)\).

qftrace loads the reflection trace data, determines the uncertainties of the signal (y-axis), and explicitly populates the points in the time axis (x-axis).

Usage

Available since yadg-3.0. The parser supports the following parameters:

pydantic model dgbowl_schemas.yadg.dataschema_4_2.step.QFTrace.Params

Show JSON schema

{
   "title": "Params",
   "type": "object",
   "properties": {
      "filetype": {
         "title": "Filetype",
         "default": "labview.csv",
         "enum": [
            "labview.csv"
         ],
         "type": "string"
      },
      "method": {
         "title": "Method",
         "default": "kajfez",
         "enum": [
            "naive",
            "lorentz",
            "kajfez"
         ],
         "type": "string"
      },
      "height": {
         "title": "Height",
         "default": 1.0,
         "type": "number"
      },
      "distance": {
         "title": "Distance",
         "default": 5000.0,
         "type": "number"
      },
      "cutoff": {
         "title": "Cutoff",
         "default": 0.4,
         "type": "number"
      },
      "threshold": {
         "title": "Threshold",
         "default": 1e-06,
         "type": "number"
      }
   },
   "additionalProperties": false
}

field filetype: Literal['labview.csv'] = 'labview.csv'

field method: Literal['naive', 'lorentz', 'kajfez'] = 'kajfez'

field height: float = 1.0

field distance: float = 5000.0

field cutoff: float = 0.4

field threshold: float = 1e-06

LabView output in a tab-separated format (csv): labviewcsv

Provides

This raw data is stored, for each timestep, using the following format:

- raw:
    avg:             !!int  # number of scans that are averaged for each trace
    bw:                     # filter bandwith used to measure the trace
      {n: !!float, s: !!float, u: "Hz"}
    traces:
      "{{ trace_name }}":   # detector name, currently hard-coded to S11
        f:                  # frequency-axis units are always Hz
          {n: [!!float, ...], s: [!!float, ...], u: "Hz"}
        Re(Γ):              # real part of the reflection coefficient
          {n: [!!float, ...], s: [!!float, ...], u: !!str}
        Im(Γ):              # imaginary part of the reflection coefficient
          {n: [!!float, ...], s: [!!float, ...], u: !!str}

DEPRECATED in yadg-4.2

The fitting of peaks and quality factors in network analyzer traces is deprecated as of yadg-4.2 and will stop working in yadg-5.0.

The fitting of \(f_0\) and \(Q_0\) to all peaks found in each trace is performed by qftrace automatically, and can be adjusted by specifying the method parameter and related options. The resulting data is stored in the derived entry in each timestep, and contains the following information:

- derived:
    "{{ trace_name }}":   # see above, currently set to S11
      f:                  # the frequencies of each peak
        {n: [!!float, ...], s: [!!float, ...], u: "Hz"}
      Q:                  # the cavity quality factors for each peak
        {n: [!!float, ...], s: [!!float, ...], u: "Hz"}

Submodules

fit: Quality factor fitting routines.

List of supported quality factor fitting methods:

Naive fitting using half-width-half-maximum around the minimum of \(|\Gamma(f)|\) in yadg.parsers.qftrace.fit.naive()

Lorentzian fit to the trace of \(|\Gamma(f)|\) trimmed using a gradient threshold criterium in yadg.parsers.qftrace.fit.lorentz()

Kajfez’s circle fitting routine to \(\Gamma(f)\), using a peak-height cutoff pruning method in yadg.parsers.qftrace.fit.kajfez()

Kajfez’s method is the preferred one and hence set as default, with a cutoff set to 0.4.

Code author: Peter Kraus <peter.kraus@empa.ch>

yadg.parsers.qftrace.fit.naive(fvals, fsigs, gvals, absgvals, **kwargs)

Naive fitting routine.

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}\).

This fit first normalises the \(|\Gamma(f)|\) trace to values between 0 and 1.
The trace is flipped in this process, obtaining \(||\Gamma(f)||\).
The \(f_0\) is determined by finding the frequency corresponding to the minimum in \(|\Gamma(f)|\) (that is, the maximum of \(||\Gamma(f)||\)).
The full-width-half-maximum (\(\Delta f_{HM}\)) value of the peak is then determined using linear interpolation of the trace, by difference of the \(f\) at the two points where \(||\Gamma(f)|| = 0.5\).
Finally, the quality factor is calculated from \(Q_0 = f_0 / \Delta f_{HM}\).

Parameters

fvals (ndarray) – Nominal values of the frequencies
fsigs (ndarray) – Error values of the frequencies
gvals (ndarray) – Not used
absgvals (ndarray) – Absolute values of the reflection coefficient, \(|\Gamma(f)|\)

Returns

(Q0, f0) – Fitted quality factor and central frequency of the data.

Return type

tuple[uc.ufloat, uc.ufloat]

yadg.parsers.qftrace.fit.lorentz(fvals, fsigs, gvals, absgvals, **kwargs)

Lorentz fit.

Fits a Lorentz function to the pruned data. The \(f_0 = x_0\), and the \(Q_0\) is calculated from \(x_0 / \Delta x = x_0 / (2\gamma)\).

This fit starts by fitting a Lorentzian curve in the form \(L(x) = a \frac{\gamma^2}{(x - x_0)^2 + \gamma^2} + c\) to the \(|\Gamma(f)|\) trace, obtaining four parameters (\(a, x_0, \gamma, c\)).
The central frequency \(f_0\) is simply \(x_0\).
The width of the Lorentzian is given by \(\Delta x = 2\gamma\).
The quality factor is determined using \(Q_0 = x_0 / \Delta x\)
Uncertainties of \(f_0\) and \(Q_0\) are calculated using the covariance matrix of the fit of \(L(x)\) to \(|\Gamma(f)|\).

Parameters

fvals (ndarray) – Nominal values of the frequencies
fsigs (ndarray) – Not used
gvals (ndarray) – Not used
absgvals (ndarray) – Absolute values of the reflection coefficient, \(|\Gamma(f)|\)

Returns

(Q0, f0) – Fitted quality factor and central frequency of the data.

Return type

tuple[uc.ufloat, uc.ufloat]

yadg.parsers.qftrace.fit.kajfez(fvals, fsigs, gvals, absgvals, **kwargs)

Kajfez’s circle-fitting program.

Adapted from Q0REFL.m, which is a part of Kajfez, D.: “Linear fractional curve fitting for measurement of high Q factors”, IEEE Trans. Microwave Theory Techn. 42 (1994) 1149-1153.

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

fvals (ndarray) – Nominal values of the frequencies
fsigs (ndarray) – Error values of the frequencies
gvals (ndarray) – Complex reflection coefficient values, \(\Gamma(f)\).
absgvals (ndarray) – Absolute values of the reflection coefficient, \(|\Gamma(f)|\)

Returns

(Q0, f0) – Fitted quality factor and central frequency of the data.

Return type

tuple[uc.ufloat, uc.ufloat]

labviewcsv: Processing LabView CSV files generated using Agilent PNA-L N5320C.

This file format includes a header, with the values of bandwith and averaging, and three tab-separated columns containing the frequency \(f\), and the real and imaginary parts of the complex reflection coefficient \(\Gamma(f)\).

Timestamps are determined from file name. One trace per file. As the set-up for which this format was designed always uses the S11 port, the name of the trace is hard-coded to this value.

Code author: Peter Kraus <peter.kraus@empa.ch>

yadg.parsers.qftrace.labviewcsv.process(fn, encoding='utf-8', timezone='timezone')

VNA reflection trace parser.

Parameters

fn (str) – File to process
encoding (str) – Encoding of fn, by default “utf-8”.
timezone (str) – A string description of the timezone. Default is “localtime”.

Returns

(data, metadata) – Tuple containing the timesteps, metadata, and common data.

Return type

tuple[list, None]

yadg.parsers.qftrace.main.process(fn, encoding='utf-8', timezone='timezone', parameters=None)

VNA reflection trace parser.

This parser processes a VNA log file, containing the complex reflection coefficient data as a function of frequency (\(\Gamma(f)\)). This data is automatically worked up to produce the quality factor \(Q_0\) and the central frequency \(f_0\) of all peaks found in each trace; hence the name qftrace.

Parameters

fn (str) – File to process
encoding (str) – Encoding of fn, by default “utf-8”.
timezone (str) – A string description of the timezone. Default is “localtime”.
parameters (Optional[BaseModel]) – Parameters for QFTrace.

Returns

(data, metadata, fulldate) – Tuple containing the timesteps, metadata, and full date tag. The currently only supported tracetype (“labview.csv”) does not return full date.

Return type

tuple[list, dict, bool]

Trace-pruning routines.

To reduce the impact of baseline noise and speed up the fitting of \(Q_0\) to the \(\Gamma(f)\) trace, only smaller sections of the trace are retained around each minimum. Two routines for trace-pruning are provided:

a height cutoff-based prune in yadg.parsers.qftrace.prune.cutoff()
a gradient threshold-based prune in yadg.parsers.qftrace.prune.threshold()

Code author: Peter Kraus <peter.kraus@empa.ch>

yadg.parsers.qftrace.prune.cutoff(p0, absgamma, cutoff)

Cutoff-based prune.

Parameters

p0 (int) – Index of the minimum of absgamma.
absgamma (ndarray) – The \(|\Gamma(f)|\) data.
cutoff (float) – Normalised height above which the trace is cut off.

Returns

A tuple of the left and right index of the trimmed trace.

Return type

tuple[int, int]

yadg.parsers.qftrace.prune.gradient(p0, absgamma, threshold)

Gradient-based prune.

Parameters

p0 (int) – Index of the minimum of absgamma.
absgamma (ndarray) – The \(|\Gamma(f)|\) data.
threshold (float) – Threshold of the gradient below which the trace is cut off.

Returns

A tuple of the left and right index of the trimmed trace.

Return type

tuple[int, int]