Werkzeugmodule und Importmigration¶

Das historische Modul mpylab.tools.util sammelte Hilfsfunktionen aus vielen unabhängigen Bereichen. Für externe Skripte bleibt es vorerst als Kompatibilitätsfassade verfügbar. Neuer und gepflegter Code sollte dagegen direkt aus den fokussierten Modulen importieren. Dadurch werden Abhängigkeiten sichtbar und das generische Modul wächst nicht weiter.

Migrationsstrategie¶

Bestehende externe Skripte müssen nicht sofort geändert werden. Bei ihrer Pflege gelten folgende Regeln:

Ein vorhandener Import aus mpylab.tools.util darf bestehen bleiben, bis das Skript ohnehin bearbeitet wird.
Importierte Namen werden einzeln durch die nachstehenden fokussierten Pfade ersetzt.
Neuer Code verwendet ausschließlich fokussierte Module.
util.py erhält keine neuen Helfer oder Neuimplementierungen.

Die Kompatibilitätsfassade delegiert derzeit an dieselben Implementierungen wie die fokussierten Module. Das Ändern eines Imports soll daher kein Verhalten ändern. Die betroffenen Tests sollten trotzdem ausgeführt werden, besonders bei Terminaleingaben und Runtime-Introspection.

Importtabelle¶

Empfohlene Ersetzungen¶
Historischer Import	Fokussiertes Modul	Funktionen und Objekte
`mpylab.tools.util`	`mpylab.tools.text`	`format_block`, `normalize_string`, `case_insensitive_string_compare`, `map2singlechar`
`mpylab.tools.util`	`mpylab.tools.filenames`	`filename_token`, `format_output_filename`
`mpylab.tools.util`	`mpylab.tools.files`	`locate`
`mpylab.tools.util`	`mpylab.tools.keyboard`	`keypress`, `anykeyevent`, `funkeypress`, `getch`, `kbhit`, `LookForUserInterrupt`, `KeyboardUnavailableError`
`mpylab.tools.util`	`mpylab.tools.logging_utils`	`tstamp`, `LogError`, `OutputError`
`mpylab.tools.util`	`mpylab.tools.email_utils`	`send_email`
`mpylab.tools.util`	`mpylab.tools.numeric_solvers`	`secant_solve`
`mpylab.tools.util`	`mpylab.tools.physical_constants`	`SPEED_OF_LIGHT`, `mu_0`, `epsilon_0`, `Z_0`; Kompatibilitäts-Floats `c`, `mu0`, `eps0`, `pi`
`mpylab.tools.util`	`mpylab.tools.runtime_introspection`	`get_var_from_nearest_outerframe`, `interactive`
`mpylab.tools.util`	`mpylab.tools.sequences`	`cmp`, `combinations`, `flatten`, `getIndex`, `isiterable`, `issequence`
`mpylab.tools.util`	`mpylab.tools.stats`	`mean`, `CalcSigma`, `CalcPsi`, `CalcRho0`
`mpylab.tools.util`	`mpylab.tools.interpol`	`extrap1d`, `InterpolateMResults`, `MResult_Interpol`
`mpylab.tools.util`	`mpylab.tools.radiated_emission_geometry`	`gmax_oats`, `gmax_fs`

Beispielsweise wird:

from mpylab.tools.util import format_block, locate, tstamp

ersetzt durch:

from mpylab.tools.files import locate
from mpylab.tools.logging_utils import tstamp
from mpylab.tools.text import format_block

Sonderfälle¶

Physikalische Konstanten¶

Neuer Code mit Einheiten verwendet SPEED_OF_LIGHT, mu_0, epsilon_0 und Z_0. Diese Namen verweisen auf die geschützten Objekte aus scuq.constants, verwenden kanonische SI-Einheiten und erhalten den CODATA-2022-Unsicherheitsgraphen. Zum Beispiel:

from mpylab.tools.physical_constants import SPEED_OF_LIGHT, mu_0
from scuq.ucomponents import Context

wert, standardunsicherheit, einheit = Context().value_uncertainty_unit(mu_0)

Die Namen c, mu0 und eps0 bleiben zur Quellcode-Kompatibilität gewöhnliche Floats mit SI-Werten und werden weiterhin von mpylab.tools.util re-exportiert. Sie geben nur die Erwartungswerte aus. mu0 und eps0 folgen nun den Werten des SI nach 2019 und CODATA, statt mu0 als exakt 4*pi*1e-7 zu behandeln. pi bleibt math.pi.

Der strikte SCUQ-Modus weist float(SPEED_OF_LIGHT) zurück, weil die Konstante dimensionsbehaftet ist. An einer ausdrücklich einheitenlosen Legacy-Schnittstelle wird zunächst in die gewünschte Einheit reduziert und danach get_expectation_value_as_float() aufgerufen.

Die charakteristische Impedanz Zc = U/I einer Leitung oder TEM-Zelle ist von der Vakuum-Feldimpedanz Z_0 = E/H zu unterscheiden. Eine typische GTEM-Zelle besitzt Zc = 50 Ohm; Freiraum-Feldbeziehungen verwenden das unsicherheitsbehaftete Z_0 aus scuq.constants (historisch durch 120*pi Ohm oder 377 Ohm angenähert). Insbesondere verwendet die analytische e0y-Reihe nach IEC 61000-4-20, Gleichung (A.5), sqrt(Zc) und nicht sqrt(Z_0).

Terminaleingaben¶

Für terminalartige Tastatureingaben dient mpylab.tools.keyboard. Aufrufe können fehlschlagen, wenn kein echtes Terminal verbunden ist, etwa in einer IDE, einem CI-Job oder einer Qt-Anwendung. In diesem Fall muss mpylab.tools.keyboard.KeyboardUnavailableError behandelt oder ein UI-Adapter verwendet werden. Das historische Modul liegt nur noch unter mpylab.tools.legacy.unixcrt; neue Abhängigkeiten davon sollen nicht entstehen.

Runtime-Introspection¶

get_var_from_nearest_outerframe bleibt verfügbar, weil Autosave und einige dynamische Messskripte weiterhin Stack-Frame-Zugriffe verwenden. Neue APIs sollen Werte explizit übergeben. Insbesondere erhalten DOT-Conditions einen expliziten Kontext, wie es die DOT-Referenz beschreibt.

Statistik und Autokorrelation¶

Für gewöhnliche geordnete Sequenzen dient mpylab.tools.stats.autocorrelation(), auch bei MSC-Auswertungen. Das separate Modul mpylab.tools.autocorrelation ist für winkelförmige oder nicht äquidistant abgetastete Daten und spline-basierte Rauschbehandlung vorgesehen.

Faktoren für erweiterte Unsicherheiten werden ebenfalls in mpylab.tools.stats bereitgestellt. Neue Anwendungen importieren get_k_factor, get_k_factor_norm, get_k_factor_rect, get_k_factor_ushape und get_dB_factors von dort. Das frühere Modul mpylab.tools.uncertain bleibt vorübergehend als Importkompatibilität erhalten und enthält keine eigene Implementierung mehr.

Komplexe Größen und Pfadkorrekturen¶

Wenn reelle und komplexe SCUQ-Unsicherheitsmodelle zusammentreffen, wird mpylab.tools.quantity_uncertainty verwendet. Der Leitfaden zu Pfadkorrekturen dokumentiert Multiplikation, Division, Betragsbildung und den vorbereiteten schnellen Pfad. Diese Logik gehört nicht zurück in generische Hilfsfunktionen.

Werkzeuge zur Konfigurationspflege¶

DOT- und NPORT-Migration sind Kommandozeilenabläufe und keine util-Helfer. Die Konfigurationsprüfung beschreibt mpylab-dot-migrate, mpylab-nport-migrate und mpylab-nport-check.

VISA-Ressource gezielt prüfen¶

Mit mpylab-visa-probe kann genau eine bekannte VISA-Ressource geöffnet und wieder geschlossen werden. Das Werkzeug ruft bewusst kein list_resources auf und sucht daher weder GPIB- noch andere VISA-Busse ab. Ohne weitere Option führt es keine Abfrage und keinen Schreibzugriff am Gerät aus:

mpylab-visa-probe GPIB0::29::INSTR

Eine explizit freigegebene, nur lesende Abfrage kann mit --query gesendet werden. Das Werkzeug akzeptiert nur nicht leere Einzelabfragen, die mit ? enden und kein Semikolon enthalten:

mpylab-visa-probe GPIB0::29::INSTR --query '*IDN?'

Mit --timeout-ms wird der VISA-Timeout in Millisekunden festgelegt; der Wert muss positiv sein und ist standardmäßig 3000. Falls mehrere VISA- Backends installiert sind, kann das Backend wie bei PyVISA üblich über PYVISA_LIBRARY gewählt werden, zum Beispiel @py für PyVISA-py.

Die Validierung des Befehls und die Tests mit simulierten Ressourcen sind hardwarefrei. Das Öffnen einer realen Ressource darf dagegen nur auf einem Rechner mit Hardwarezugriff und nach ausdrücklicher Freigabe erfolgen. Die vollständige Optionsreferenz steht unter Command-line tools.

API-Referenzen¶

Die kuratierte, englischsprachige Utility-API enthält die wichtigsten öffentlichen Konvertierungs- und Skripthelfer. Die vollständige generierte API listet außerdem die fokussierten Module und die vorübergehende Kompatibilitätsfassade mpylab.tools.util auf.