INI and DAT reference for instrument data¶

INI files configure a concrete instrument instance. DAT files provide frequency-dependent quantities with units and uncertainty. An INI file may reference DAT files for one or more channels.

INI files¶

[DESCRIPTION]
description = Virtual 40 dB attenuator
type = CABLE
driver = nport.py

[INIT_VALUE]
FSTART = 1e5
FSTOP = 26e9
NR_OF_CHANNELS = 1

[CHANNEL_1]
NAME = S21
UNIT = dB
FREQUENCY_INTERPOLATION = LINEAR
VALUE_INTERPOLATION = LINEAR
COMPLEX_INTERPOLATION = POLAR
FILE = attenuator.dat

DESCRIPTION.type identifies the instrument class; driver selects its implementation. INIT_VALUE contains instrument-wide limits and communication parameters. Channel sections describe measured quantities, safety channels, and data sources.

Instrument limits such as MAXIN belong at this layer. The driver knows the fixed internal unit of the instrument, while UNIT selects the unit requested by the user for the channel. The concrete driver class determines which entries are required.

DAT files¶

mpylab.tools.dataparser.DatFile reads text-based calibration and correction data and returns a dictionary. Its keys are frequencies as float values in Hz; its values are SCUQ quantities in the corresponding canonical linear unit.

A minimal file looks like this:

FUNIT: Hz
UNIT: dB
ABSERROR: 0.2
1e6  -39.8
1e9  -40.1

Blank lines are allowed. A # starts a comment extending to the end of the line. FUNIT, UNIT, and an error declaration apply from their position in the file. A later declaration replaces the preceding one.

Grammar¶

The domain grammar is:

line := FUNIT unit
      | UNIT unit
      | RELERROR number
      | ABSERROR value
      | frequency value
      | frequency value value value

value := number
       | (real, imaginary)
       | [magnitude, phase_deg]

Before the first data point, FUNIT must name a frequency unit. UNIT must precede the first value or ABSERROR declaration. The historical syntax with input and target unit in the same UNIT line is not supported. Perform output conversions after parsing with mpylab.tools.uconv.UConv.

Each converted frequency may occur only once. This also detects duplicates that result from using different frequency units.

Value representations¶

Scalar: -39.8 represents a real value.
Cartesian complex: (0.8, -0.2) represents real and imaginary part.
Polar complex: [0.825, -14.0] represents magnitude and phase. The phase is always specified in degrees, independently of UNIT.

All values are converted to the canonical linear SCUQ unit while parsing. Consequently, a logarithmic input unit does not leave a dB value in the result object.

Uncertainty¶

Two-column data points¶

For frequency value, the most recent error declaration determines the uncertainty. Without RELERROR or ABSERROR, uncertainty is zero.

RELERROR: A non-negative relative standard uncertainty. It is always applied to the already linearized value. With UNIT: dB, RELERROR: 0.1, and value 20, the linear nominal value is 100 and its linear uncertainty is 10.
ABSERROR: An absolute standard uncertainty in the declared input UNIT. A new ABSERROR declaration disables RELERROR and vice versa.

Explicit bounds¶

A data point with three values contains nominal value, lower bound, and upper bound:

1e6  10.0  9.5  10.8

The order of the three values is not significant. The parser sorts them, uses the middle value as the nominal value, and uses half the span between the lower and upper value as standard uncertainty. An explicit triple takes precedence over an active RELERROR or ABSERROR.

dB units¶

For logarithmic units, ABSERROR is a non-negative scalar difference on the dB scale. For example:

FUNIT: Hz
UNIT: dBm
ABSERROR: 1
1e6 20

The parser first forms the bounds 19 dBm and 21 dBm and then linearizes all three values. It does not interpret 1 dBm as an absolute linear power uncertainty.

SCUQ stores a symmetric linear uncertainty here. The parser therefore uses half of the total linear span. Converting this quantity back to dB generally produces asymmetric bounds. A complex ABSERROR is not valid for a logarithmic unit.

Complex polar uncertainty¶

For new complex uncertainty data, use a triple in polar notation:

FUNIT: Hz
UNIT: powerratio
1e6 [0.8, -1] [1.0, 0] [1.2, 1]

The value with the middle magnitude becomes the nominal value. Half the span between the smallest and largest magnitude is the magnitude uncertainty. The phases are unwrapped around the nominal phase; half of the phase span is stored as phase uncertainty in radians. Magnitude and phase are assumed to be independent.

DatFile transforms this polar model into a complex SCUQ component. Its Cartesian 2x2 covariance matrix describes real and imaginary part. mpylab.tools.interpol.UQ_interpol and pickle serialization preserve this covariance.

A Cartesian triple using (real, imaginary) retains the historical scalar uncertainty representation and should not be used for new complex uncertainty data.

Antenna and transducer factors¶

Antenna factors are deliberately not reduced to their shortened dimension internally. The units (V/m)/V and (A/m)/V preserve whether the factor maps an input voltage to electric or magnetic field strength. This keeps the reverse conversion unambiguous.

Quote units containing parentheses:

UNIT: "dB((V/m)/V)"
UNIT: "dB((A/m)/V)"

UNIT: dB/m is an alias for the electric antenna factor. UNIT: 1/m and the historical UNIT: dB1/m remain generic inverse-length units without antenna-factor semantics.

The logarithmic values are referenced to the value 1 in the corresponding linear factor unit:

\[AF_E[\mathrm{dB}((\mathrm{V/m})/\mathrm{V})] = 20 \log_{10}\left( \frac{AF_E}{1\,(\mathrm{V/m})/\mathrm{V}} \right)\]

Supported units¶

The authoritative list is held by mpylab.tools.uconv.UConv. Query it without duplicating the registry:

>>> from mpylab.tools.uconv import UConv
>>> UConv.available_units()
('(a/m)/v', '(v/m)/v', '1', '1/m', ...)

Supported groups include:

dimensionless values and amplitude or power ratios;
power, voltage, and frequency;
electric and magnetic field strength;
length and angle;
power flux density and conductivity;
electric and magnetic antenna factors;
henry and farad.

Unit names are processed case-insensitively. Structured names must be quoted because they contain special characters.

Error handling¶

The parser uses PLY with a separate lexer and parser for every DatFile instance. Concurrently prepared files therefore do not affect each other’s state. Parse tables are created in memory; parsetab.py is not part of the public interface.

Lexical and syntax errors raise mpylab.tools.dataparser.DatFileSyntaxError. The message contains the source, line, and column. An invalid file does not return incomplete partial data.

In particular, the parser rejects:

unknown units or units used in the wrong position;
an FUNIT that is not a frequency unit;
negative relative or logarithmic absolute errors;
inf, nan, and values that become non-finite during conversion;
duplicate frequencies;
incomplete data lines.

Interpolation¶

Interpolation is not part of the DAT grammar. It is selected by the consuming channel, especially an NPORT channel:

FREQUENCY_INTERPOLATION: LINEAR or LOG for the frequency axis.
VALUE_INTERPOLATION: LINEAR or DB for magnitude or value.
COMPLEX_INTERPOLATION: Treatment of complex quantities, typically POLAR.

The choices must match how the support points were produced and the physical quantity represented. Excessive gaps between support points may be formally valid but physically inadequate. The configuration validation page describes the corresponding tools.

VNA conversion and polar dB values¶

VNA exports to DAT documents CSV/Touchstone import with mpylab-vna2dat. Polar values under UNIT: dB store a power-scaled magnitude and unchanged transfer phase. Conversion to AMPLITUDERATIO uses mpylab.tools.ratio_conversion.convert_transfer_ratio(): only the magnitude is square-rooted, not the complex number. Magnitude, phase and uncertainty dependencies remain consistent. For three identical polar magnitudes, the middle supplied value is nominal; rounding in the Cartesian representation does not affect this selection. This permits zero magnitude uncertainty with nonzero phase uncertainty.

Factor-free logarithmic interpolation¶

VALUE_INTERPOLATION = DB geometrically interpolates positive linear values or magnitudes. Values already converted by DatFile to their canonical unit are logarithmically transformed, interpolated and transformed back. A common factor of 10 or 20 cancels; this is not another unit conversion. The same applies to the lower and upper bounds of real uncertain values. Existing complex phase and covariance interpolation is unchanged.

DB_FACTOR is therefore deprecated. The INI key and Python argument db_factor still accept 10 or 20, emit mpylab.tools.interpol.DeprecatedDBFactorWarning and have no effect on new calculations. Other values remain errors. Omission is supported for linear DAT units including W, V, amplituderatio and powerratio. Zero values, nonpositive lower bounds and Cartesian DB interpolation remain invalid.

The diagnostic key NPORT.data[channel]['interpolation']['db_factor'] remains present for compatibility: it contains the explicit INI value or None when omitted. No factor is inferred from UNIT anymore. Python interpolators likewise retain db_factor as the explicit argument or None. New interpolators add the private marker _logarithm_scale = 1.0. When loading older pickles without this marker, the historical factor is used only to interpret their already scaled interpolation coordinates. Existing DAT values, units and measurement data are not rewritten. Removing compatibility arguments requires a separately announced breaking change; no removal release is scheduled.

Preview, apply and check cleanup with:

mpylab-nport-migrate --remove-db-factor --recursive configs/
mpylab-nport-migrate --remove-db-factor --recursive --write configs/
mpylab-nport-migrate --remove-db-factor --recursive --check configs/

The tool also performs its existing migration of historical INTERPOLATION settings. The option removes only valid DB_FACTOR entries in NPORT channel sections. Comments, line endings, UTF-8 BOM, permissions and embedded DAT text are retained; duplicate or invalid factors prevent modifying that file. Without --remove-db-factor, the existing migration behavior is retained. Actual conversion factors in UConv, dB uncertainty calculations and S-parameter conversions remain necessary and are not removed.