temfield-mpylab documentation

TEMField performs radiated susceptibility measurements in (G)TEM cells using MpyLab. The PySide6 user interface starts the measurement sequence in a dedicated worker thread, keeping the GUI responsive while instrument commands are executed by the measurement worker.

Installation

Install the package from PyPI:

pip install temfield-mpylab

For an isolated application-style installation, pipx is also useful:

pipx install temfield-mpylab

This installs the package in its own environment and exposes the command line tools temfield and temfield-info on your PATH.

Run main.py from the package or use the installed temfield entry point. Use temfield-info to show installation and dependency information, or temfield-info --json for machine-readable output.

In-loop AM waveform validation

The headroom procedures in IEC 61000-4-3 and IEC 61000-4-20 characterize an empty test volume. TEMField operates with the EUT already present. A preliminary 1.8 * E_target CW exposure could therefore overtest an EUT before a 3 V/m, 80 percent AM test. TEMField deliberately does not perform that procedure during an EUT run and does not label its replacement normative.

The in-loop sequence is:

  1. Keep RF off while changing frequency and resetting the generator to its lowest configured level.

  2. With AM off, enable RF and level from below to E_start = E_target / (1 + m).

  3. Start EUT monitoring and enable AM. The first ideal positive peak is only E_target.

  4. Increase signal-generator power adaptively in protected steps of at most 1 dB and acquire a field waveform after every step. The next power follows the local estimate \(P_{i+1}=P_i(E_\mathrm{target}/E_i)^2\), capped by the step limit and bounded correction ceiling. Intermediate fits are retained as diagnostics and checked for unsafe fitted-peak overshoot. Full signal-quality and compression decisions apply at the final carrier target.

  5. Require three consecutive valid waveforms at the requested carrier field before starting the dwell time.

  6. Switch AM and RF off after an invalid waveform, a protection limit, or an EUT event.

Amplifier-model basis

The ideal envelope is

\[E(t) = E_c \left(1 + m \sin(\omega t)\right).\]

After an ordinary sinusoidal fit, TEMField fits the same samples to a memoryless Rapp AM/AM model:

\[E_\mathrm{out} = \frac{G E_\mathrm{in}} {\left(1 + \left(G E_\mathrm{in}/E_\mathrm{sat}\right)^{2p}\right)^{1/(2p)}}.\]

The smoothness parameter \(p\) describes how abruptly saturation starts. The primary metric, rapp_peak_compression_db, is the fitted differential gain loss between the carrier input and the positive AM peak. Absolute field scale cancels, so the metric remains comparable across frequencies and test levels.

The historical 80-percent-AM reduction criterion leaves 2 dB between the ideal 5.1 dB ratio and the 3.1 dB saturation boundary. This motivates an outer model-based compression limit. Since the EUT is already present, TEMField uses the more conservative default of 1 dB.

Default engineering limits

The Rapp estimate cannot detect every signal defect by itself. Generator errors, clipping, probe bandwidth, noise, and amplifier memory can also alter the waveform. temfield_mpylab.waveform_validation.AMWaveformLimits therefore combines the model with independent guards:

  • modulation depth: 75 through 85 percent;

  • modulation frequency: 0.95 through 1.05 kHz;

  • sinusoidal \(R^2\) of at least 0.995;

  • sinusoidal RMSE no greater than 3 percent of fitted amplitude;

  • mean fitted carrier of the three stable final waveforms within 2 percent of E_target;

  • fitted positive peak no more than 2 percent above its configured ideal;

  • three final waveforms with at most 2 percent relative spread in carrier and modulation depth; each waveform independently has to satisfy the 1 dB compression limit.

The normalized RMSE is intentionally not used to reject an intermediate ramp point. The probe has an approximately absolute residual and noise floor. At the safe starting field, division by the correspondingly smaller AM amplitude would produce a larger normalized residual despite unchanged signal quality and would make the decision level-dependent.

Compression stability is also not inferred from the relative spread of the three fitted Rapp values. For a nearly linear amplifier the Rapp knee and smoothness are weakly identifiable and small changes in probe noise can move a near-zero compression estimate substantially in relative terms. Requiring all three final waveforms to meet the absolute compression limit is the physically meaningful guard.

The adaptive final step avoids frequency-dependent overshoot from a fixed power schedule. The controller aims at the nominal carrier field; the 2-percent acceptance interval is used only for the mean of the final waveforms. Starting the final acquisition at its lower boundary would make probe noise alternate between pass and fail.

The ordinary ceiling is the ideal \((1+m)^2\) power factor relative to the safe CW start. TEMField permits only the small additional correction that would move a carrier at the lower accepted boundary back to nominal. The absolute ceiling is therefore \((1+m)^2/(1-t_\mathrm{carrier})^2\). With the default 2-percent carrier tolerance, the additional allowance is about 4.1 percent power or 0.18 dB. This is not an unchecked exposure margin: the configured step limit, upper carrier-field decision limit, fitted positive-peak safety limit, and amplifier protection remain independent guards. A waveform acquisition and all safety checks remain between any two level changes. If that bounded ceiling is reached just below nominal but still inside the accepted carrier interval, the three-waveform mean makes the decision; an individual noisy ramp fit does not cause an immediate failure.

The carrier-field decision is based on the arithmetic mean of the three stable final fits. Testing the 2-percent boundary independently on every waveform would make a single probe-noise fluctuation at the boundary an intermittent failure. All signal-quality, modulation, peak-safety, and compression limits continue to apply to every final waveform individually.

If an otherwise valid and stable final set exceeds the upper carrier-field limit, TEMField performs one downward closed-loop correction according to \(P_\mathrm{new}=P(E_\mathrm{target}/\overline{E}_\mathrm{carrier})^2\) and acquires three new final waveforms. The superseded set is retained in carrier_correction_waveforms. A second overshoot, an invalid waveform, or a protection response still fails the validation. Only a downward correction is allowed here, so this recovery cannot increase EUT exposure.

Peak acceptance uses the positive peak of the sinusoidal fit rather than the largest individual probe sample. Sample noise biases a raw maximum upward and would make isolated noise excursions false safety failures. The raw maximum is still recorded. Fit residual, \(R^2\), and Rapp compression remain independent guards against real waveform defects.

These values are documented engineering acceptance limits, not quoted IEC tolerances. Pass an AMWaveformLimits instance or mapping to TEMFieldWorker to change them. The log and JSON result use method = "in_loop_waveform_rapp" and normative = False and retain all ramp points, final waveforms, Rapp parameters, quality metrics, limits, and the decision reason.

The Waveform tab displays only the three final-target validation waveforms and their sinusoidal fits. Ramp and dwell acquisitions remain diagnostic and do not replace this final validation view.

An empty-volume calibration is still required wherever a formal normative headroom demonstration is needed. mpylab’s general headroom evaluator remains available for that separate task but is intentionally not used in TEMField’s in-loop EUT workflow. IEC publication records: https://webstore.iec.ch/en/publication/59849 and https://webstore.iec.ch/en/publication/34378.

Field-probe coordinate contract

mpylab field-probe drivers return raw (probe_x, probe_y, probe_z) values. TEMField resolves the physical probe orientation once and maps each reading into (cell_x, cell_y, cell_z). The GUI, datafunc, leveling, AM waveform validation, waveform plot, sinusoidal fit, and result data operate only on this mapped cell-coordinate vector.

Define an axis permutation on the field-probe DOT node, for example:

prb [ini="fieldprobe.ini"
     probe_axis_map="cell_x:+probe_y,cell_y:+probe_x,cell_z:-probe_z"]

The same definition may be stored in a FIELDPROBE INI file. Programmatic integrations may pass probe_orientations to TEMFieldWorker or TestSusceptibility.Init. Conflicting definitions abort before hardware initialization.

Ey is the default leveling component, while later runs restore the last selected component. A stored legacy value of auto is migrated to Ey. Custom functions passed as TestSusceptibility.Init(datafunc=...) receive the mapped cell-coordinate vector. Current probes provide unsigned component magnitudes, so exact axis permutations are supported but arbitrary rotations requiring synchronous signed vector data are rejected.

EUT monitoring

TEMField uses the shared mpylab.env.eut API. Manual reporting is always available and can be supplemented by automatic monitors for cameras, communication links, or process data. Automatic monitors are placed behind mpylab.env.eut.ThreadedEUTMonitor; they do not access MGraph and never switch RF themselves.

During exposure the operator can report Degraded, Failed, or Not evaluable. An event requiring the safety action rf_off is routed immediately through the measurement worker. After an impairment, AM and RF remain off while the operator or an automatic monitor reports the resulting EUT state and the recovery method separately. The two check boxes record whether the operating mode changed or stored data was lost. TEMField evaluates the structured history against the selected performance criterion A, B, or C and shows the result and event history in the table tooltip. The EUT panel also defines the maximum time allowed for the post-exposure observation.

mpylab.env.eut.RandomEUTMonitor supplies reproducible hardware-independent simulations and a template for custom automatic monitors. It must not be used as evidence of real EUT performance.

An embedding application can attach a custom automatic monitor before the measurement starts:

from mpylab.env.eut import RandomEUTMonitor

window.set_automatic_eut_monitor(RandomEUTMonitor(seed=42))

Structured results

Saving the table creates the selected CSV file and a JSON companion with the same filename stem. The JSON document contains the EUT event history, performance assessment, and the applied immunity disturbance. Physical quantities are represented by value, uncertainty, and unit.

The shared mpylab.env.immunity_result disturbance representation is intentionally independent of a particular immunity method:

{
  "quantity_kind": "electric_field_strength",
  "target": {"value": 10.0, "uncertainty": 0.0, "unit": "V/m"},
  "measured_components": {
    "y": {"value": 9.9, "uncertainty": 0.1, "unit": "V/m"}
  }
}

TEMField supplies the electric-field-specific content shown above, but the schema does not prescribe field axes or units. A conducted-immunity application can use injected_current with a current monitor, or an applied voltage with suitable component names. This keeps the EUT assessment and result tooling reusable across immunity methods.

API

Contents: