Network Parameter Data

class libvna.data.NPData

In-memory representation of electrical network parameter data.

Parameters:

ptype (PType, optional) – Type of parameter data to be stored: ANY, S, T, U, Z, Y, H, G, A, B, ZIN. The default is ANY, which stores raw data without interpretation. When given with the filename argument, causes the loaded parameters to be converted to the indicated type as needed.
frequencies (int, optional) – Number of frequency points. Defaults to zero. The number can be changed using the init(), resize(), load(), or add_frequency() functions, or by assignment to the frequency_vector or fz0_array attributes.
rows (int, optional), columns (int, optional) – Dimensions of the parameter matrix. Rows and columns must be equal for S, Z and Y parameters. They must both be 2 for T, U, H, G, A and B parameters. Rows must be 1 for ZIN parameters, which are stored as a row vector. Rows and columns can be any non-negative values for ANY parameters. Both dimensions default to zero. Type and dimensions can be changed using the init(), resize() or load() functions, or by assignment to the type, data_array, or fz0_array attributes.
filename (str, optional) – Load network parameter data from file. The rows, columns, and frequencies arguments should not be given.
filehandle (file handle, optional) – Load network parameter data from an open file. The filename argument must also be given for error messages – it need not refer to an actual file.

Raises:

ValueError – if rows, columns and ptype are not valid

This class stores a vector of frequency points frequency_vector, a frequencies by rows by columns array of network parameter data data_array, and a per-port array of complex reference impedances. The reference impedances can be the same across all frequencies (z0_vector), or can be different for each frequency (fz0_array).

When given non-zero dimensions, the class is constructed with all data and frequency values initialized to zero, and z0 values initialized to 50 ohms.

The class provides methods to load and save in Touchstone versions 1 (.s2p) and 2 (.ts), and in a more general space-separated value Network Parameter Data (.npd) format. It also provides conversion between network parameter types.

Managing Type and Dimensions

NPData.init(ptype, frequencies, rows, columns)

Change the ptype and dimensions as indicated by the arguments, and reset all frequency and data elements back to zero and all z0 entries to 50 ohms.

Parameters:

ptype (PType) – Set the parameter type: ANY, S, T, U, Z, Y, H, G, A, B, ZIN.
frequencies (int) – Number of frequency points
rows (int) –
columns (int) – Dimensions of the parameter matrix. Rows and columns must be equal for S, Z and Y parameters. They must both be 2 for T, U, H, G, A and B parameters. Rows must be 1 for ZIN parameters. Rows and columns can be any non-negative values for ANY parameters.

NPData.resize(ptype, frequencies, rows, columns)

Change the parameter type and dimensions without clearing or converting data. Existing values remain undisturbed when the matrix type, number of rows or number of frequencies is changed, but shift to other cells when the number of columns is changed. Changing the parameter type with this function does not convert existing data to the new type. To convert parameters, use convert() instead.

Parameters:

ptype (PType) – Set the parameter type: ANY, S, T, U, Z, Y, H, G, A, B, ZIN.
frequencies (int) – Number of frequency points
rows (int) –
columns (int) – Dimensions of the parameter matrix. Rows and columns must be equal for S, Z and Y parameters. They must both be 2 for T, U, H, G, A and B parameters. Rows must be 1 for ZIN parameters. Rows and columns can be any non-negative values for ANY parameters.

NPData.convert(new_ptype)

Return a new NPData object with data converted to the new type.

Parameters:: new_type (PType) – new parameter type: ANY, S, T, U, Z, Y, H, G, A, B, ZIN.
Returns:: A new NPData object in the requested type. The original object is left unchanged.
Raises:: ValueError – if conversion to new_type is invalid

NPData.ptype

The parameter type as a PType enum value. Valid values are:: ANY, S, T, U, Z, Y, H, G, A, B, ZIN

When changing this value, the dimensions must be consistent with the new type. Existing data is not converted. See the resize() and convert() functions for alternative ways to change the type.

Type: PType

NPData.ptype_name

The parameter type as a string (read-only).

Type: str

NPData.rows

The number of rows (read-only).

Type: int

NPData.columns

The number of columns (read-only).

Type: int

NPData.frequencies

The number of frequencies (read-only).

Type: int

The Frequency Vector

NPData.frequency_vector

The vector of frequency points (read-write). Slicing operations are supported.

Type: behaves like array[f_index] of float

NPData.add_frequency(frequency)

Add a new frequency entry. The corresponding new data matrix (data_array[-1, :, :]) is initialized to zeros. This function is useful when loading data into the object when the number of frequency points is not known in advance.

Parameters:: frequency (float) – new frequency value to add

The Data Array

NPData.data_array

The parameter data array (read-write). Slicing operations are supported.

Type: behaves like array [f_index, row, column] of complex

Reference Impedances

NPData.z0_vector

The vector of reference impedances for each port (read-write). If the dimensions have been established, setting this attribute to a scalar value sets all ports to the same reference impedance. The default value is 50 ohms.

Type: behaves like array[port] of complex

NPData.fz0_array

Frequency-dependent reference impedances as an array (read-write). Slicing operations are supported. Assigning to or modifying elements in this array automatically establishes frequency-dependent reference impedances.

Type: behaves like array[f_index, port] of complex

NPData.has_fz0

True if frequency-dependent system impedances are in effect (read-only).

Type: bool

Loading and Saving

NPData.load(filename)

Load network parameter data from filename, automatically resetting the type and dimensions as needed.

Parameters:

filename (str) – pathname to file

Raises:

OSError – if can’t open file
SyntaxError – if the file is badly formed

NPData.save(filename)

Save network parameter data to filename.

Parameters:

filename (str) – pathname to file

Raises:

OSError – if can’t open file
ValueError – if file type inconsistent with parameter data

NPData.fload(filehandle, filename)

Load network parameter data from an open file handle, automatically resetting the type and dimensions as needed.

Parameters:

filehandle – open file handle
filename – name of file (used in error messages only)

Raises:

OSError – if can’t read file
SyntaxError – if the file is badly formed

NPData.fsave(filehandle, filename)

Save network parameter data to an open file handle.

Parameters:

filehandle – open file handle to write
filename – name of file (used in error messages only)

Raises:

OSError – if can’t write file
ValueError – if file type inconsistent with parameter data

NPData.cksave(filename)

Test if we would be able to save the currently selected format in the currently selected filetype without actually saving.

This function is useful to test if there’s a conflict between the requested parameter format and the save file type before doing potentially expensive operations such as VNA measurements only to ultimately fail at save time. The filename argument is used only to determine the filetype when filetype is AUTO.

Parameters:: filename (str) – proposed pathname to save file
Raises:: ValueError – if file type inconsistent with parameter data

NPData.format

The file format (str, read-write):

Valid values:

S[ri|ma|dB]: scattering parameters
T[ri|ma|dB]: scattering-transfer parameters
U[ri|ma|dB]: inverse scattering-transfer parameters
Z[ri|ma]: impedance parameters
Y[ri|ma]: admittance parameters
H[ri|ma]: hybrid parameters
G[ri|ma]: inverse-hybrid parameters
A[ri|ma]: ABCD parameters
B[ri|ma]: inverse ABCD parameters
Zin[ri|ma]: impedance looking into each port
PRC: Zin as parallel resistance and capacitance
PRL: Zin as parallel resistance and inductance
SRC: Zin as series resistance and capacitance
SRL: Zin as series resistance and inductance
IL: insertion loss (dB)
RL: return loss (dB)
VSWR: voltage standing wave ratio

where the ri, ma or dB suffix is an optional coordinate system modifier:

ri: real, imaginary
ma: magnitude, angle
dB: decibels, angle

Format specifiers are case-insensitive. Note that not all formats can be represented in all file formats. Touchstone formats support only S, Y, Z, H, and G parameters, with version 1 imposing further restrictions on the maximum number of ports (4), and disallowing per-port Z0 values. The .npd file type can store all formats. With the .npd type only, format may be a comma-separated list of formats, e.g. “IL,RL,VSWR”.

Type: str

NPData.filetype

The file type (read-write):

AUTO: Determine type based on filename extension (default)
TOUCHSTONE1: Use Touchstone version 1 (.s2p)
TOUCHSTONE2: Use Touchstone version 2 (.ts)
NPD: Use network parameter data (.ndp)

Type: FileType

When a file is loaded, filetype is set to the type of the loaded file. To save in a different format with type based on the file extension, set filetype back to AUTO before saving.

NPData.fprecision

The number of significant figures to use for frequency values when saving parameters to a file. Default is 7.

Type: int

NPData.dprecision

The number of significant figures to use for data values when saving parameters to a file. Default is 6.

Type: int

File Type / Parameter Conversion Example

#!/usr/bin/python3
import argparse
from libvna.data import NPData, FileType

usage = """
    %s [-f format] input-file output-file
    where format is a comma-separated list of:
      s[ri|ma|dB]  scattering parameters
      t[ri|ma|dB]  scattering-transfer parameters
      u[ri|ma|dB]  inverse scattering-transfer parameters
      z[ri|ma]     impedance parameters
      y[ri|ma]     admittance parameters
      h[ri|ma]     hybrid parameters
      g[ri|ma]     inverse-hybrid parameters
      a[ri|ma]     ABCD parameters
      b[ri|ma]     inverse ABCD parameters
      Zin[ri|ma]   input impedances
      PRC          Zin as parallel RC
      PRL          Zin as parallel RL
      SRC          Zin as series RC
      SRL          Zin as series RL
      IL           insertion loss
      RL           return loss
      VSWR         voltage standing wave ratio

    Coordinates
      ri  real, imaginary
      ma  magnitude, angle
      dB  decibels, angle

    Specifiers are case-insensitive."

    File Types
      Touchstone v1:          .s1p, .s2p, .s3p, .s4p
      Touchstone v2:          .ts
      Network Parameter Data: .npd
"""

parser = argparse.ArgumentParser(usage=usage)
parser.add_argument("-f", "--format")
parser.add_argument("input_file", metavar="input-file")
parser.add_argument("output_file", metavar="output-file")
args = parser.parse_args()

npd = NPData()
npd.load(args.input_file)
npd.filetype = FileType.AUTO
if args.format:
    npd.format = args.format
npd.save(args.output_file)