Metadata-Version: 2.4
Name: mpylab
Version: 1.0.20
Summary: A framework to simplify development of measurement 'scripts' for measurements in laboratories over e.g pyvisa.
Author: Christian Albrecht, Stephan, Oscar Rivera, Mathias Magdowski, Sophie Rautschek, Frank Schröder, Luzia Tesar, Konstantin Pasche, Thomas Reidemeister
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/mpylab.git
Project-URL: Documentation, https://mpylab-75fcff.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.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: bidict>=0.23.1
Requires-Dist: gpib-ctypes>=0.3.0
Requires-Dist: ipywidgets>=8.1.8
Requires-Dist: levenshtein>=0.27.1
Requires-Dist: matplotlib>=3.7.5
Requires-Dist: numpy>=1.24.4
Requires-Dist: pathvalidate>=3.3.1
Requires-Dist: plotly>=6.5.2
Requires-Dist: ply>=3.11
Requires-Dist: psutil>=7.2.2
Requires-Dist: pydot>=4.0.1
Requires-Dist: pyparsing>=3.1.4
Requires-Dist: pyserial>=3.5
Requires-Dist: pyside6>=6.9.2
Requires-Dist: pyusb>=1.2.1
Requires-Dist: pyvisa>=1.14.1
Requires-Dist: pyvisa-py>=0.7.2
Requires-Dist: requests>=2.32.5
Requires-Dist: scipy>=1.10.1
Requires-Dist: scipy-stubs~=1.16.1
Requires-Dist: scuq>=1.0.10
Requires-Dist: simpleeval>=0.9.13
Requires-Dist: sphinx>=9.0.4
Requires-Dist: typing-extensions>=4.16.0
Requires-Dist: zeroconf>=0.148.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: coverage[toml]>=7.0; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Provides-Extra: release
Requires-Dist: build; extra == "release"
Requires-Dist: twine; extra == "release"
Provides-Extra: docs
Requires-Dist: sphinx>=8.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Requires-Dist: breathe; extra == "docs"
Provides-Extra: gui
Requires-Dist: PySide6; extra == "gui"
Dynamic: license-file


# mpylab

[![pipeline status](https://gitlab.hrz.tu-chemnitz.de/chair-of-electromagnetic-theory-and-compatibility-at-tu-dresden/mpylab/mpylab/badges/main/pipeline.svg)](https://gitlab.hrz.tu-chemnitz.de/chair-of-electromagnetic-theory-and-compatibility-at-tu-dresden/mpylab/mpylab/-/pipelines)
[![coverage](https://gitlab.hrz.tu-chemnitz.de/chair-of-electromagnetic-theory-and-compatibility-at-tu-dresden/mpylab/mpylab/badges/main/coverage.svg)](https://gitlab.hrz.tu-chemnitz.de/chair-of-electromagnetic-theory-and-compatibility-at-tu-dresden/mpylab/mpylab/-/commits/main)
[![PyPI version](https://img.shields.io/pypi/v/mpylab.svg)](https://pypi.org/project/mpylab/)
[![Python versions](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://www.python.org/downloads/)
[![documentation](https://img.shields.io/badge/docs-GitLab%20Pages-blue.svg)](https://mpylab-75fcff.gp.hrz.tu-chemnitz.de/)

## Overview

mpylab is a Python framework for developing reproducible and traceable
laboratory measurement applications. It combines instrument drivers,
configurable RF measurement paths, measurement procedures, uncertainty-aware
physical quantities, hardware-independent test configurations, and user
interfaces.

The framework is used for electromagnetic compatibility measurements such as
TEM/GTEM emission and immunity tests, mode verification, amplifier
characterization, and mode-stirred chamber measurements. Measurement
applications can use real instruments or virtual drivers without changing
their measurement logic.

A typical mpylab setup consists of:

- Python measurement logic defining the measurement sequence;
- a DOT file describing instruments and signal paths;
- INI files configuring individual devices and channels;
- DAT files containing frequency-dependent correction and calibration data;
- a pickle history containing measurement configuration, raw data, evaluated
  results, and the information required to resume interrupted measurements.

## Core architecture

### Device drivers

`mpylab.device.driver.DRIVER` provides the common foundation for instrument
drivers. It handles device configuration, communication setup, command
execution, error reporting, and virtual operation. Device-type base classes
such as `SIGNALGENERATOR`, `POWERMETER`, `RECEIVER`, `FIELDPROBE`, and `NPORT`
define the interfaces expected by measurement applications.

Concrete drivers implement these interfaces for particular instruments.
Communication backends include VISA/GPIB, Prologix adapters, serial and
network-based devices, as well as debug and virtual drivers for tests without
laboratory hardware.

### Measurement graphs

`mpylab.tools.mgraph.MGraph` turns a DOT configuration into an executable
measurement setup. Graph nodes represent active or passive devices, while
edges describe the signal paths and their frequency-dependent corrections.

MGraph creates and initializes devices, evaluates conditional paths, applies
N-port corrections, switches active signal paths, controls RF state, and
provides common leveling and amplifier-protection functions. Measurement code
therefore works with logical device roles instead of hard-coding a particular
laboratory setup.

### Measurement environments

`mpylab.env.Measure.Measure` provides shared measurement infrastructure such
as logging, UI adapters, autosave and resume support, user interruption,
device initialization and fail-safe shutdown, protected signal-generator
control, and common leveling operations.

Specialized environments build on this foundation. Examples include
`TEMCell` for TEM/GTEM measurements, `MSC` for mode-stirred chamber
measurements, and `AmplifierTest` for amplifier characterization. Measurement
scripts combine these environments with a configuration and preserve the
complete measurement history in pickle files.

### Physical quantities and uncertainty

mpylab uses [SCUQ](https://pypi.org/project/scuq/) consistently for physical
measurement values and derived results. A SCUQ `Quantity` combines a numerical
value, its uncertainty, and its physical unit. Unit conversion, uncertainty
propagation, interpolation, path correction, evaluation, and result export can
therefore retain the metrological meaning of a value instead of reducing it
prematurely to a plain float.

This is particularly important for EMC measurements, where values routinely
move between linear and logarithmic representations and where calibration,
path loss, field strength, power, voltage, and uncertainty must remain
traceable.

This software is distributed under the GPL-3.0-or-later license. See LICENSE
for details.

## Installation

Install the current release from PyPI:

```bash
python -m pip install mpylab
```

Alternatively, install directly from GitLab:

```bash
python -m pip install git+https://gitlab.hrz.tu-chemnitz.de/chair-of-electromagnetic-theory-and-compatibility-at-tu-dresden/mpylab/mpylab.git
```

This requires `git`. Append a branch or tag to the URL to select a particular
revision, for example `@main` or `@v1.0.9`.

Optional dependency groups can be installed from PyPI as needed:

```bash
# Tests, coverage, formatting, and linting
python -m pip install "mpylab[dev]"

# Build the Sphinx documentation
python -m pip install "mpylab[docs]"

# Build and check release artifacts
python -m pip install "mpylab[release]"
```

Extras can be combined:

```bash
python -m pip install "mpylab[dev,docs,release]"
```

They also work with a direct GitLab installation:

```bash
python -m pip install "mpylab[dev,docs] @ git+https://gitlab.hrz.tu-chemnitz.de/chair-of-electromagnetic-theory-and-compatibility-at-tu-dresden/mpylab/mpylab.git@main"
```

For an editable development installation from a local checkout:

```bash
python -m pip install -e ".[dev,docs]"
```

## Command-line tools

Installing mpylab provides configuration-maintenance commands and a modular
TEM report generator:

```bash
# Migrate legacy f condition identifiers in one DOT file or a directory.
mpylab-dot-migrate --write local-config.dot
mpylab-dot-migrate --check --recursive path/to/configurations

# Migrate legacy NPORT interpolation settings.
mpylab-nport-migrate --write local-cable.ini
mpylab-nport-migrate --check --recursive path/to/configurations

# Check NPORT coverage, sampling and interpolation quality.
mpylab-nport-check --recursive path/to/configurations \
    --json-report nport-quality.json

# Discover and report all supported sections in a TEMCell history pickle.
mpylab-tem-report measurement-history.p --list-sections
mpylab-tem-report measurement-history.p --output tem-report \
    --formats pdf html svg \
    --profile script/conf/tem-report-profile.toml \
    --profile script/conf/tem-report-measurement.toml
```

Both migration commands perform a dry run and show a diff unless ``--write``
or ``--check`` is selected. Use ``--no-diff`` to suppress diff output. The DOT
tool can additionally validate selected signal paths with ``--path``,
``--frequency-range``, ``--path-mode`` and ``--context``. Run any command with
``--help`` for its complete option list. Detailed usage is available in the
[documentation](https://mpylab-75fcff.gp.hrz.tu-chemnitz.de/).

The TEM report generator reads the complete pickle history and automatically
includes every supported data set. Report modules currently cover TEM-mode
verification, measured e0y field-factor data, evaluated emission data, and
evaluated immunity data including EUT performance assessments. The top-level
HTML and PDF reports include a cross-section traceability overview, and
``traceability.tsv`` provides the same information for machine processing. It
shows frequency coverage, referenced source data sets, unresolved dependencies,
completeness, and warnings without recalculating measurement results.

Measurement content and traceability are kept separate from report styling.
This allows later report profiles to add laboratory identity, measurement date,
environmental conditions, free text, logos, colors, and page layout without
changing the stored measurement history.

The commented examples `script/conf/tem-report-profile.toml` and
`script/conf/tem-report-measurement.toml` separate global laboratory and
presentation settings from measurement-specific values. `--profile` may be
repeated; files are merged in command-line order and later values override only
the same keys. Profile values with their source files, generated values,
defaults, and missing fields are distinguished in the top-level
`report-metadata.tsv` file.

## MSC virtual workflows

The MSC scripts can be run with virtual device configurations below
`script/conf`. The pickle files written by these scripts are history
containers: a new measurement loads an existing `MSC` instance, appends new
measurement and evaluation data, and writes a new pickle containing the full
previous history.

Typical sequences are:

```text
maincal -> eutcal -> immunity
maincal -> eutcal -> emission
maincal -> eutcal -> immunity -> emission
```

Example from the `script` directory:

```bash
python msc-maincal.py conf/msc-immunity-virtual/conf.py
python msc-eutcal.py conf/msc-immunity-virtual/conf-eutcal.py
python msc-immunity.py conf/msc-immunity-virtual/conf-immunity.py
python msc-emission.py conf/msc-emission-virtual/conf-after-immunity.py
```

## GTEM virtual workflows

The current TEM/GTEM scripts focus on one-port GTEM cells. The virtual
workflow follows the traceable pickle-history model used by the MSC scripts:

```text
e0y -> emission
```

Example from the `script` directory:

```bash
python tem-e0y.py conf/tem-gtem-e0y-virtual/conf.py
python tem-emission.py conf/tem-gtem-emission-virtual/conf.py
```

The measurement and evaluation workflow is based on IEC 61000-4-20:2010,
especially Annex A.3.2.3 for one-port GTEM emission correlation and Annex
A.3.2.3.3 for the `e0y` field factor.

## Immunity result interchange

`mpylab.env.immunity_result` provides an optional, disturbance-neutral JSON
exchange format for immunity results. It is currently used by TEMField when
exporting measurement tables. Native TEMCell and MSC measurement histories
remain stored in pickle files; the modular TEM report generator produces
HTML, PDF, TSV, and graphical output.

SCUQ quantities are serialized as value, uncertainty, and unit. Details and
examples are available in the documentation.

## License

GPL-3 or higher

## Repository

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

The documentation is also available from the gitlab server of TU Chemnitz:

[https://mpylab-75fcff.gp.hrz.tu-chemnitz.de/](https://mpylab-75fcff.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
