libvna.cal Module

This module uses measurements of calibration standards to find error terms for vector network analyzers (VNAs). It applies the resulting calibration to measurements of devices under test to correct for the errors.

The basic sequence for generating a new calibration is:

Create a Calset object, then a Solver object.
Make measurements of calibration standards and add them using the Solver.add_* methods.
Solve using Solver.solve()
Use Solver.add_to_calset() to add the new calibration to the Calset
Use Calset.save() to save the calibration to a file

The sequence for applying a calibration to a device measurement is:

Load the calibration by passing the calibration filename to the Calset constructor.
Get the Calibration object from the Calset.calibrations attribute.
Measure the device under test.
Use Calibration.apply() to apply the calibration correction to the measurements.

class libvna.cal.Calset

The Calset loads, saves and manages solved VNA calibrations. It’s the central data structure of VNA calibration, needed by other classes in the module.

Though the Calset usually holds just one calibration, it can hold any number of related calibrations, for example, covering different frequency bands or test set configurations.

Parameters:: filename (str, optional) – Load the Calset from the given file. Note that the recommended .vnacal extension is not added automatically and should be included in filename.

calibrations: Vector of Calibration objects in this Calset. This attribute is indexable, iterable, and the elements can be deleted.

index(name) → int

Convert from calibration name to index:

Parameters:: name (str) – Name of the calibration

properties

A tree of nested dictionaries, lists, scalars and None values representing arbitrary user-defined global properties of the calibration set, for example, the model and serial number of the instrument, test fixture used, and other conditions under which the calibration was made.

Also see the calibration-specific properties, Calibration.properties.

save(filename)

Save the Calset to a file.

Parameters:: filename (str) – Pathname of the save file. The recommended file extension, “.vnacal”, is not added automatically and should included in filename.

class libvna.cal.Calibration

A solved calibration. Note: you cannot instantiate this class directly: use Calset.calibrations to access instances of this class.

name: Name of the calibration (str, readonly)

ctype: Type of the calibration (CalType, readonly)

rows: Number of rows in the calibration (int, readonly)

columns: Number of columns in the calibration (int, readonly)

frequencies: Number of frequencies in the calibration (int, readonly)

frequency_vector: Vector of calibration frequencies (array of float, readonly)

z0: Reference frequency of all ports in the calibration (complex, readonly)

properties: A tree of nested dictionaries, lists, scalars and None values representing arbitrary user-defined properties of the calibration. Some examples are the calibration date, cable lengths, and test set used.

apply(f, b, *, a=None) → NPData

Apply the calibration correction to measured data. The calibration must have dimensions 2x1, 1x2, or NxN.

Parameters:

f (array of float or None) – vector of frequencies at which the measurements were made, or None if measured at the calibration frequencies
b (frequencies long vector of complex matrix) – root power received into each VNA port
a (frequencies long vector of complex matrix, optional) – incident root power out of each VNA port, or None if not available

Returns:

libvna.data.NPData object containing the corrected parameters

class libvna.cal.Parameter

An element of the S-parameter matrix describing a calibration standard. The Parameter is an abstraction that can represent a single complex scalar such as -1 for short, a vector of (frequency, gamma) tuples representing a reflect with complex impedance or the through component of a transmission line, or an unknown parameter the library must solve, e.g. the R or L parameters in TRL.

Note: this class cannot be instantiated directly: use ScalarParameter, VectorParameter, UnknownParameter, CorrelatedParameter, or Parameter.from_value().

static from_value(calset, value)

Construct a Parameter from a given value.

Parameters:

calset (Calset) – The associated calibration set.
value – If number, return a ScalarParameter. If tuple(frequency_vector, gamma_vector), return a VectorParameter. If Parameter, return the argument.

get_value(frequencies)

Parameters:: frequencies (float or array of float) – Frequencies at which to evaluate the value.

Return the value of the parameter at each given frequency, with output in the same shape as frequencies. For a scalar parameter, the function ignores frequency and simply returns the fixed gamma value. For a vector parameter, it returns the gamma value at the given frequency, interpolating as necessary. If the parameter is unknown and Solver.solve() has completed successfully, get_value() returns the solved value, again interpolating as necessary.

class libvna.cal.ScalarParameter

Bases: Parameter

An element of the S parameter matrix of a calibration standard that has a constant value at all frequencies, e.g. -1 for short.

Parameters:

calset (Calset) – The associated calibration set.
gamma (complex) – an element of the S parameter matrix of the standard that doesn’t depend on frequency, e.g. 0 for match.

class libvna.cal.VectorParameter

Bases: Parameter

An element of the S parameter matrix of a calibration standard that varies with frequency.

Parameters:

calset (Calset) – The associated calibration set.
frequency_vector (vector of float) – monotonically increasing list of frequencies
gamma_vector (vector of complex) – list or array of complex values corresponding to each frequency in frequency_vector

The frequencies must cover the entire span of the calibration frequency range, but do not have to coincide with the calibration frequencies – the library uses rational function interpolation as needed to interpolate between frequency points.

class libvna.cal.UnknownParameter

Bases: Parameter

An element of the S parameter matrix of a calibration standard that is only approximately known and that the library must determine.

Parameters:

calset (Calset) – The associated calibration set.
initial_guess (complex, (frequency_vector, gamma_vector) tuple, or Parameter) – Approximate value of the unknown parameter

class libvna.cal.CorrelatedParameter

Bases: Parameter

An element of the S parameter matrix of a calibration standard that is known to be correlated with another (possibly unknown) Parameter. This type of parameter is useful for modeling connection non-repeatability.

Parameters:

calset (Calset) – The associated calibration set.
other (complex, (frequency_vector, gamma_vector) tuple, or Parameter) – Another Parameter to which this Parameter is known to be correlated
frequency_vector (vector of float) – monotonically increasing list of frequencies
sigma_vector (vector of float) – standard deviations of the differences between this Parameter and its correlate at each frequency

The frequencies must cover at least the entire span of the calibration frequency range, but do not have to coincide with the calibration frequencies – the library uses natural cubic spline interpolation as needed to interpolate between points.

class libvna.cal.Solver

Error Term Solver: solve for VNA error terms from measurements of calibration standards.

Parameters:

calset (Calset) – The associated calibration set.
ctype (CalType) –
The calibration type determines which error terms the library corrects. Valid values are:

T8, U8:
8-term T or U parameters: correct for directivity, reflection / transmission tracking, and port match errors on each VNA port. At least three standards, (e.g. short-open, short-match, through) are needed to solve the 2x2 T8 or U8 calibration.

TE10, UE10:
8-term T or U parameters plus 2 leakage: correct for the same errors as T8 and U8, but also correct for leakage within the VNA from the driving port to the other ports. At least three standards (e.g. short-open, short-match, through) are needed to solve the 2x2 TE10 or UE10 calibration.

T16, U16:
16-term T or U parameters: correct for the same errors as TE10 and UE10, but add the remaining leakage terms including leakage between the DUT ports in the test fixture. At least five standards (e.g. short-open, short-match, open-match, open-short, through) are needed to solve the 2x2 T16 or U16 calibration.

UE14:
Correct for the same errors as TE10 and UE10, except treat each column (driving port) as an independent calibration. This type produces separate error parameters for the forward and reverse directions, and for this reason, it’s able to correct for errors in the forward-reverse switch without reference (a matrix) measurements, even for a switch that lies between the detectors and the DUT. At least four standards (e.g. short-open, match-open, match-short, through) are needed to solve the 2x2 UE14 calibration.

E12:
Generalization of classic SOLT: the library uses UE14 terms internally to solve this calibration, and this type corrects for exactly the same errors at UE14. The difference is only in the representation of the saved error terms. After finding the UE14 error terms, the library converts from inverse scattering transfer (U) error terms to scattering error terms (E). At least four standards (e.g. short-open, match-open, match-short, through) are needed to solve the 2x2 E12 calibration.
rows (int) – Number of rows in the calibration, where rows is the number of VNA ports that detect signal. Normally, rows and columns are both simply the number of VNA ports. Some simple VNAs, however, measure only a subset of the S parameters such as \(S_{11}\) and \(S_{21}\). If the VNA measures \(S_{11}\) and \(S_{21}\) only, set rows to 2 and columns to 1. If the VNA measures \(S_{11}\) and \(S_{12}\) only, set rows to 1 and columns to 2. In general, if rows > columns, U parameters must be used; if rows < columns, T parameters must be used. For square calibrations, either T or U parameters may be used.
columns (int) – Number columns in the calibration, where columns is the number of VNA ports that transmit signal. See rows.
frequency_vector (list/array of float) – Vector of frequency points to be used in the calibration. Must be monotonically increasing.
z0 (complex, optional) – Reference impedance of the VNA ports. All ports must have the same reference impedance. If not specified, z0 defaults to 50 ohms.

Note that the calibration method used, e.g. LRL, LRM, LRRL, LRRM, LXYZ, SOLT, TRD, TRL, TRM, TXYZ, UXYZ, etc., does not have to be specified. The library automatically determines the method based on the standards given, or uses a general solver if it does not have a special solver for the given set of standards. The main requirement is that the standards used must provide a sufficient number of conditions for the number of unknowns to be solved.

add_single_reflect(b, s11, *, a=None, port=1)

Add the measurement of a single reflect standard with parameter s11 on the given VNA port.

Parameters:

b (frequencies long vector of complex matrix) – root power received into each VNA port
s11 (complex, (frequency_vector, gamma_vector) tuple, or Parameter) – \(S_{11}\) parameter of the the calibration standard
a (frequencies long vector of complex matrix, optional) – incident root power out of each VNA port, or None if not available
port (int, optional) – VNA port number connected to the standard. If not given, defaults to 1.

add_double_reflect(b, s11, s22, *, a=None, port1=1, port2=2)

Add the measurement of a double reflect standard with parameters s11 and s22 on the given VNA ports, assuming \(S_{12} = S_{21} = 0\).

Parameters:

b (frequencies long vector of complex matrix) – root power received into each VNA port
s11 (complex, (frequency_vector, gamma_vector) tuple, or Parameter) – the \(S_{11}\) parameter of the the calibration standard
s22 (complex, (frequency_vector, gamma_vector) tuple, or Parameter) – the \(S_{22}\) parameter of the calibration standard
a (frequencies long vector of complex matrix, optional) – incident root power out of each VNA port, or None if not available
port1 (int, optional) – VNA port number connected to port 1 of the calibration standard. If not given, defaults to 1.
port2 (int, optional) – VNA port number connected to port 2 of the calibration standard. If not given, defaults to 2.

add_through(b, *, a=None, port1=1, port2=2)

Add the measurement of a perfect through standard between port1 and port2, i.e. \(S_{12} = S_{21} = 1\) and \(S_{11} = S_{22} = 0\).

Parameters:

b (frequencies long vector of complex matrix) – root power received into each VNA port
a (frequencies long vector of complex matrix, optional) – incident root power out of each VNA port, or None if not available
port1 (int, optional) – First VNA port connected to the through standard. If not given, defaults to 1.
port2 (int, optional) – Second VNA port connected to the through standard. If not given, defaults to 2.

add_line(b, s, *, a=None, port1=1, port2=2)

Add the measurement of an arbitrary two-port standard with S parameter matrix, s, on the given VNA ports.

Parameters:

b (frequencies long vector of complex matrix) – root power received into each VNA port
s (2x2 matrix) – S-parameter matrix of the standard, where each element of the matrix can be a complex, (frequency_vector, gamma_vector) tuple, or Parameter
a (frequencies long vector of complex matrix, optional) – incident root power out of each VNA port, or None if not available
port1 (int, optional) – VNA port number connected to port 1 of the calibration standard. If not given, defaults to 1.
port2 (int, optional) – VNA port number connected to port 2 of the calibration standard. If not given, defaults to 2.

add_mapped_matrix(b, s, *, a=None, port_map=None)

Add the measurement of an arbitrary n-port standard with S parameter matrix, s, and a map of ports of the standard to ports of the VNA in port_map.

Parameters:

b (frequencies long vector of complex matrix) – root power received into each VNA port
s (matrix) – S-parameter matrix of the standard, where each element of the matrix can be a complex, (frequency_vector, gamma_vector) tuple, or Parameter
a (frequencies long vector of complex matrix, optional) – incident root power out of each VNA port, or None if not available
port_map (vector of int, optional) – List of the VNA port numbers attached to each port of the standard in order. Optional if the standard has the same number of ports as the VNA and the ports of the VNA are attached to the corresponding port numbers of the standard. VNA port numbers start with 1.

set_m_error(frequency_vector, noise_floor, tracking_error=None)

Enable measurement error modeling.

Parameters:

frequency_vector (vector of float) – vector of ascending frequencies spanning at least the full calibration frequency range
noise_floor (vector of float) – vector of noise floor root-power measurements at the VNA detectors at each frequency when no signal is applied
tracking_error (vector of float, optional) – optional vector describing an additional root-power noise source proportional to the amplitude of the measured signal

Both noise sources are assumed to be Gaussian and independent. Specifying measurement errors with this function can significantly improve accuracy, especially for significantly overdetermined systems, as the 16 term models typically are.

et_tolerance: For iterative solution methods, this parameter controls the degree of change in the root-mean-squared of the error terms sufficiently small to stop iteration (float). Default is 1.0e-6.

p_tolerance: For iterative solution methods, this parameter controls the degree of change in the root-mean-squared of the unknown parameters sufficiently small to stop iteration (float). This parameter has no effect if there are no unknown parameters in the S matrix. Default is 1.0e-6.

iteration_limit: For iterative solution methods, this parameter controls the maximum number of iterations permitted to reach convergence (int). The default is 30.

pvalue_limit

p-value, below which to reject the null hypothesis that the measurement errors are less than or equal to the values given in set_m_error (float).

This parameter has no effect if measurement error modeling has not been enabled through set_m_error(). The default is 0.001.

solve(): Solve for the error terms. Note: if this function raises an exception due to an insufficient number of standards, you may add additional standards and try again.

add_to_calset(name) → int

Add the solved calibration to the Calset. If name matches an existing calibration, the existing calibration is replaced; if name is unique, then the new calibration is appended to the Calset.calibrations array.

Parameters:: name – Name for the calibration.
Returns:: Index of the new entry in Calset.calibrations