Werkzeugmodule und Importmigration ================================== Das historische Modul :mod:`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 :mod:`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 ------------- .. list-table:: Empfohlene Ersetzungen :header-rows: 1 :widths: 28 30 42 * - Historischer Import - Fokussiertes Modul - Funktionen und Objekte * - ``mpylab.tools.util`` - :mod:`mpylab.tools.text` - ``format_block``, ``normalize_string``, ``case_insensitive_string_compare``, ``map2singlechar`` * - ``mpylab.tools.util`` - :mod:`mpylab.tools.filenames` - ``filename_token``, ``format_output_filename`` * - ``mpylab.tools.util`` - :mod:`mpylab.tools.files` - ``locate`` * - ``mpylab.tools.util`` - :mod:`mpylab.tools.keyboard` - ``keypress``, ``anykeyevent``, ``funkeypress``, ``getch``, ``kbhit``, ``LookForUserInterrupt``, ``KeyboardUnavailableError`` * - ``mpylab.tools.util`` - :mod:`mpylab.tools.logging_utils` - ``tstamp``, ``LogError``, ``OutputError`` * - ``mpylab.tools.util`` - :mod:`mpylab.tools.email_utils` - ``send_email`` * - ``mpylab.tools.util`` - :mod:`mpylab.tools.numeric_solvers` - ``secant_solve`` * - ``mpylab.tools.util`` - :mod:`mpylab.tools.physical_constants` - ``SPEED_OF_LIGHT``, ``mu_0``, ``epsilon_0``, ``Z_0``; Kompatibilitäts-Floats ``c``, ``mu0``, ``eps0``, ``pi`` * - ``mpylab.tools.util`` - :mod:`mpylab.tools.runtime_introspection` - ``get_var_from_nearest_outerframe``, ``interactive`` * - ``mpylab.tools.util`` - :mod:`mpylab.tools.sequences` - ``cmp``, ``combinations``, ``flatten``, ``getIndex``, ``isiterable``, ``issequence`` * - ``mpylab.tools.util`` - :mod:`mpylab.tools.stats` - ``mean``, ``CalcSigma``, ``CalcPsi``, ``CalcRho0`` * - ``mpylab.tools.util`` - :mod:`mpylab.tools.interpol` - ``extrap1d``, ``InterpolateMResults``, ``MResult_Interpol`` * - ``mpylab.tools.util`` - :mod:`mpylab.tools.radiated_emission_geometry` - ``gmax_oats``, ``gmax_fs`` Beispielsweise wird: .. code-block:: python from mpylab.tools.util import format_block, locate, tstamp ersetzt durch: .. code-block:: python 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 :mod:`scuq.constants`, verwenden kanonische SI-Einheiten und erhalten den CODATA-2022-Unsicherheitsgraphen. Zum Beispiel: .. code-block:: python 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 :mod:`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 :data:`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 :mod:`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 :mod:`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 :class:`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 :doc:`DOT-Referenz <../configuration/dot>` beschreibt. Statistik und Autokorrelation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Für gewöhnliche geordnete Sequenzen dient :func:`mpylab.tools.stats.autocorrelation`, auch bei MSC-Auswertungen. Das separate Modul :mod:`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 :mod:`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 :mod:`mpylab.tools.quantity_uncertainty` verwendet. Der :doc:`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 :doc:`Konfigurationsprüfung <../configuration/validation>` 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: .. code-block:: console 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: .. code-block:: console 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 :doc:`../../api/commands`. API-Referenzen -------------- Die kuratierte, englischsprachige :doc:`Utility-API <../../api/utilities>` enthält die wichtigsten öffentlichen Konvertierungs- und Skripthelfer. Die :doc:`vollständige generierte API <../../api/full-reference>` listet außerdem die fokussierten Module und die vorübergehende Kompatibilitätsfassade ``mpylab.tools.util`` auf.