Metadata-Version: 2.4
Name: temfield_mpylab
Version: 0.0.12
Summary: Radiated Susceptibility in (G)TEM cells using MpyLab
Author-email: Hans Georg Krauthäuser <hgk@ieee.org>
Maintainer-email: Hans Georg Krauthäuser <hgk@ieee.org>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://www.tu-dresden.de/et/tet
Project-URL: Repository, https://gitlab.hrz.tu-chemnitz.de/chair-of-electromagnetic-theory-and-compatibility-at-tu-dresden/mpylab/TEMField.git
Project-URL: Documentation, https://temfield-1012e2.gp.hrz.tu-chemnitz.de/
Keywords: pyvisa,gpib,measurements,laboratory
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib>=3.9.4
Requires-Dist: mpylab>=1.0.19
Requires-Dist: numpy>=2.0.2
Requires-Dist: pyside6>=6.10.1
Requires-Dist: scuq>=0.9.1
Provides-Extra: docs
Requires-Dist: sphinx>=8.0; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Provides-Extra: release
Requires-Dist: build>=1.2; extra == "release"
Requires-Dist: twine>=6.2; extra == "release"
Requires-Dist: wheel; extra == "release"
Dynamic: license-file

# TemField

Radiated EMC susceptibility measurements in (G)TEM waveguides using **mpylab**

This software is distributed unter GPL-3 or higher. See LICENSE for details.

## Installation

```bash
pip install temfield-mpylab
```

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

```bash
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`.

## Command line

Start the GUI with:

```bash
temfield
```

Show installation and dependency information with:

```bash
temfield-info
```

Use `temfield-info --json` for machine-readable output.

## AM headroom safety check

Before modulation is enabled, TEMField first levels the unmodulated field to
the AM peak factor. For 80 % AM this is `1.8 * E_target`. It then reduces the
signal-generator output by 5.1 dB and checks the resulting decrease. A
configured forward-power meter provides the measurement method prescribed by
IEC 61000-4-20; otherwise the field probe is used as an explicitly
non-normative proxy. After a passed check, TEMField levels once more to the
requested carrier field and only then enables AM. Failed leveling or headroom
checks keep AM off and switch RF off for that frequency.

By default mpylab applies the nominal interval 3.10545...7.1 dB for 80 % AM.
IEC 61000-4-3:2020 explicitly uses the 3.1...7.1 dB interval. IEC
61000-4-20:2022 retains older wording that declares 3.1...5.1 dB suitable and
values below 3.1 dB saturated, but does not consistently resolve values above
5.1 dB. TEMField deliberately applies the current IEC 61000-4-3 linearity
criterion to its IEC 61000-4-20 workflow as a documented engineering
interpretation. The withdrawn IEC 61000-4-3:2006/ISH1:2008 supports accepting
reductions above 5.1 dB but is not presented as a current normative reference.
The corresponding IEC publication records are
[ISH1:2008](https://webstore.iec.ch/en/publication/4210),
[IEC 61000-4-3:2020](https://webstore.iec.ch/en/publication/59849), and
[IEC 61000-4-20:2022](https://webstore.iec.ch/en/publication/34378).

Both interval limits use nominal values: uncertainty does not change pass/fail
by default. The mpylab API makes the upper limit configurable and can
optionally allow expanded-uncertainty overlap only at that upper limit;
TEMField leaves this option disabled. Programmatic integrations can set
`am_headroom_maximum_drop_db` and
`am_headroom_allow_upper_uncertainty` on `TEMFieldWorker` or
`TestSusceptibility.Init`. Ratio uncertainty is retained with coverage factor
`k = 2`; shared calibration contributions remain correlated and can cancel in
the ratio, while independent acquisition scatter remains.

The log and JSON result distinguish `passed`, `passed_with_uncertainty`,
`failed_below_interval`, and `failed_above_interval`. They record both nominal
limits, the uncertainty option, standard and expanded asymmetric uncertainties,
decision interval, method, and normative-method flag.

## Field-probe coordinate contract

mpylab field-probe drivers return raw `(probe_x, probe_y, probe_z)` values.
TEMField resolves the probe orientation once and maps those readings into
`(cell_x, cell_y, cell_z)`. The GUI selections, `datafunc`, leveling,
AM-headroom field proxy, waveform plot, sinusoidal fit, and result files all
operate only on this mapped cell-coordinate vector.

Define the physical probe orientation on its DOT node, for example:

```dot
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 the `DESCRIPTION` or `Init_Value`
section of a `FIELDPROBE` INI file. Programmatic integrations may pass
`probe_orientations` to `TEMFieldWorker` or `TestSusceptibility.Init`.
Conflicting definitions stop the run before hardware initialization.

The default leveling component is `Ey`. TEMField remembers the last selected
component. Installations with the removed legacy `auto` setting are migrated
to `Ey` when their settings are next loaded.

Custom `TestSusceptibility.Init(datafunc=...)` functions receive the mapped
three-component cell-coordinate vector. Current probes provide unsigned
component magnitudes, so TEMField supports axis permutations but not arbitrary
rotations that require synchronous signed vector data.

## EUT monitoring

TEMField uses the shared `mpylab.env.eut` API. Manual EUT reporting is
always available in the GUI and may be supplemented by automatic monitors for
cameras, communication links, or process data. Automatic monitors run behind
`ThreadedEUTMonitor`; they never access `MGraph` or switch RF themselves.

During exposure, the operator can report `Degraded`, `Failed`, or `Not
evaluable`. After an impairment, TEMField switches AM and RF off and separately
records the post-exposure state and recovery method. The table reports the
result for performance criterion A, B, or C and includes the structured events
in its tooltip. The post-exposure timeout is configurable in the EUT panel. A
safety event is routed immediately through the measurement worker's RF-off
path.

`RandomEUTMonitor` provides reproducible hardware-independent simulations and
a starting point for custom automatic monitors. It must not be used as evidence
of real EUT performance.

An application embedding the window can configure an automatic monitor before
the measurement starts:

```python
from mpylab.env.eut import RandomEUTMonitor

window.set_automatic_eut_monitor(RandomEUTMonitor(seed=42))
```

## Structured results

Saving the measurement table writes both the selected CSV file and a JSON file
with the same stem. The JSON document preserves quantities as `value`,
`uncertainty`, and `unit` and includes the EUT event history and performance
assessment.

The shared `mpylab.env.immunity_result` schema calls the applied test quantity
`disturbance`. Its
`quantity_kind`, `target`, and freely named `measured_components` are not tied
to an electric field. TEMField currently records `electric_field_strength`
with its measured probe components. The same format can represent, for
example, `injected_current` in A or an applied voltage in a future conducted
immunity application.

## License

GPL-3 or higher

## Repository

[https://gitlab.hrz.tu-chemnitz.de/chair-of-electromagnetic-theory-and-compatibility-at-tu-dresden/mpylab/TEMField.git](https://gitlab.hrz.tu-chemnitz.de/chair-of-electromagnetic-theory-and-compatibility-at-tu-dresden/mpylab/TEMField.git)

## Documentation

[https://temfield-1012e2.gp.hrz.tu-chemnitz.de/](https://temfield-1012e2.gp.hrz.tu-chemnitz.de/)


## Contact

Prof. Dr. Hans Georg Krauthäuser (hgk@ieee.org)  
Chair for Electromagnetic Theory and Compatibility  
Technische Universität Dresden, Dresden, Germany
