qftrace: VNA trace parser

The qftrace parser handles the reading and processing of the network analyzer traces, containing the reflection coefficient as a function of the sweeped frequency, \(\Gamma(f)\). The basic function of the parser is to:

1. read in the raw data and create timestamped traces

2. detect the peaks in each trace (\(f_0\)) and fit the quality factor \(Q_0\)

Usage

The use of qftrace can be requested by supplying qftrace as an argument to the parser keyword in the dataschema. The parser supports the following parameters:

pydantic model dgbowl_schemas.yadg.dataschema_4_1.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

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

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"}

Metadata

The metadata section is currently empty.

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.

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]

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.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]

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.

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()

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]