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.