Tool modules and import migration ================================= The historical :mod:`mpylab.tools.util` module collected helpers from many unrelated domains. It remains available as a compatibility facade for external scripts, but new and maintained code should import from the focused modules directly. This makes dependencies visible and avoids extending the generic module again. Migration policy ---------------- Existing external scripts do not have to change immediately. Apply these rules when maintaining them: * keep an existing :mod:`mpylab.tools.util` import until the script is edited for another reason; * replace imported names individually with the focused paths below; * use only focused modules in new code; * do not add new helpers or reimplementations to ``util.py``. The compatibility facade currently delegates to the same implementations as the focused modules. Migrating an import therefore does not intentionally change its behavior. Run the affected tests nevertheless, especially for terminal input and runtime introspection. Import map ---------- .. list-table:: Recommended replacements :header-rows: 1 :widths: 28 30 42 * - Historical import - Focused module - Functions and objects * - ``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``; compatibility 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`` For example, replace: .. code-block:: python from mpylab.tools.util import format_block, locate, tstamp with: .. code-block:: python from mpylab.tools.files import locate from mpylab.tools.logging_utils import tstamp from mpylab.tools.text import format_block Special cases ------------- Physical constants ~~~~~~~~~~~~~~~~~~ Use ``SPEED_OF_LIGHT``, ``mu_0``, ``epsilon_0``, and ``Z_0`` for new quantity-aware code. They reference the protected objects in :mod:`scuq.constants`, use canonical SI units, and preserve the CODATA-2022 uncertainty graph. For example: .. code-block:: python from mpylab.tools.physical_constants import SPEED_OF_LIGHT, mu_0 from scuq.ucomponents import Context value, standard_uncertainty, unit = Context().value_uncertainty_unit(mu_0) The names ``c``, ``mu0``, and ``eps0`` remain ordinary SI-valued floats for source compatibility and are still re-exported by :mod:`mpylab.tools.util`. They expose expectation values only. ``mu0`` and ``eps0`` now follow the post-2019 SI/CODATA values rather than treating ``mu0`` as exactly ``4*pi*1e-7``. ``pi`` remains :data:`math.pi`. Strict SCUQ mode rejects ``float(SPEED_OF_LIGHT)`` because the constant is dimensional. At an explicitly unitless legacy boundary, reduce to the desired unit and call ``get_expectation_value_as_float()`` instead. Keep the characteristic impedance ``Zc = U/I`` of a transmission line or TEM cell separate from the vacuum field impedance ``Z_0 = E/H``. A typical GTEM cell has ``Zc = 50 ohm``; free-space field relations use the uncertainty-aware ``Z_0`` from :mod:`scuq.constants` (historically approximated as ``120*pi ohm`` or ``377 ohm``). In particular, the analytical ``e0y`` series in IEC 61000-4-20, Equation (A.5), uses ``sqrt(Zc)``, not ``sqrt(Z_0)``. Terminal input ~~~~~~~~~~~~~~ Use :mod:`mpylab.tools.keyboard` for terminal-style keyboard input. Calls can fail when no real terminal is attached, for example in an IDE, CI job, or Qt application. Handle :class:`mpylab.tools.keyboard.KeyboardUnavailableError` or use a UI adapter instead. The historical module now exists only as ``mpylab.tools.legacy.unixcrt``; do not add new dependencies on it. Runtime introspection ~~~~~~~~~~~~~~~~~~~~~ ``get_var_from_nearest_outerframe`` remains available because autosave and some dynamic measurement scripts still use stack-frame lookup. New APIs should pass values explicitly. In particular, DOT conditions should receive an explicit context as described in the :doc:`DOT reference <../configuration/dot>`. Statistics and autocorrelation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Use :func:`mpylab.tools.stats.autocorrelation` for ordinary ordered sequences, including MSC evaluations. The separate :mod:`mpylab.tools.autocorrelation` module is intended for angular or non-uniformly sampled data and spline-based noise handling. Coverage factors for expanded uncertainties are also provided by :mod:`mpylab.tools.stats`. New applications import ``get_k_factor``, ``get_k_factor_norm``, ``get_k_factor_rect``, ``get_k_factor_ushape``, and ``get_dB_factors`` from that module. The former ``mpylab.tools.uncertain`` module remains temporarily as an import compatibility layer and no longer contains a separate implementation. Complex quantities and path corrections ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Use :mod:`mpylab.tools.quantity_uncertainty` when real and complex SCUQ uncertainty models meet. The :doc:`path-correction guide ` documents multiplication, division, magnitude formation, and the prepared fast path. Do not move this logic back into generic utility functions. Configuration maintenance tools ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DOT and NPORT migration are command-line workflows rather than ``util`` helpers. See :doc:`configuration validation <../configuration/validation>` for ``mpylab-dot-migrate``, ``mpylab-nport-migrate``, and ``mpylab-nport-check``. Probe an explicit VISA resource ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Use ``mpylab-visa-probe`` to open and close exactly one known VISA resource. The tool deliberately does not call ``list_resources`` and therefore does not scan GPIB or any other VISA bus. Without another option it performs no query and no write operation on the instrument: .. code-block:: console mpylab-visa-probe GPIB0::29::INSTR An explicitly authorized read-only query can be sent with ``--query``. The tool accepts only non-empty single queries that end in ``?`` and contain no semicolon: .. code-block:: console mpylab-visa-probe GPIB0::29::INSTR --query '*IDN?' Use ``--timeout-ms`` to set the VISA timeout in milliseconds. It must be positive and defaults to ``3000``. If more than one VISA backend is installed, select it through ``PYVISA_LIBRARY`` as usual for PyVISA, for example ``@py`` for PyVISA-py. Command validation and tests with simulated resources are hardware-free. Opening a real resource must only be done on a machine with hardware access and after explicit authorization. See :doc:`../../api/commands` for the complete option reference. API references -------------- The curated :doc:`utility API <../../api/utilities>` contains the most common public conversion and script helpers. The :doc:`complete generated API <../../api/full-reference>` also lists the focused modules and the temporary ``mpylab.tools.util`` compatibility facade.