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 --------- .. code-block:: ini [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 --------- :class:`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: .. code-block:: text 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: .. code-block:: text 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 :class:`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: .. code-block:: text 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: .. code-block:: text 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: .. code-block:: text 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. :class:`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: .. code-block:: text 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: .. math:: 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 :class:`mpylab.tools.uconv.UConv`. Query it without duplicating the registry: .. code-block:: pycon >>> 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 :class:`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 :doc:`configuration validation ` page describes the corresponding tools.