Tool modules and import migration¶
The historical 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
mpylab.tools.utilimport 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¶
Historical import |
Focused module |
Functions and objects |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
For example, replace:
from mpylab.tools.util import format_block, locate, tstamp
with:
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
scuq.constants, use canonical SI units, and preserve the CODATA-2022
uncertainty graph. For example:
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 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 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 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 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 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 DOT reference.
Statistics and autocorrelation¶
Use mpylab.tools.stats.autocorrelation() for ordinary ordered
sequences, including MSC evaluations. The separate
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
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 mpylab.tools.quantity_uncertainty when real and complex SCUQ
uncertainty models meet. The 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 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:
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:
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 Command-line tools for the complete option reference.
API references¶
The curated utility API contains the most common
public conversion and script helpers. The complete generated API also lists the focused modules and the temporary
mpylab.tools.util compatibility facade.