Getting started¶

This guide starts with an empty working directory and does not assume prior Python experience. Commands are entered in a terminal: use Terminal on macOS or Linux and PowerShell on Windows.

Installation step by step¶

1. Check Python¶

mpylab requires Python 3.11 or newer. On macOS or Linux, enter:

python3 --version

On Windows, enter:

py --version

The output should start with Python 3.11 or a higher version. If the command is not found or the version is older, download and install a current release from the official Python website before continuing. On Windows, enable the option that makes Python available from the command line during installation.

2. Create a working directory¶

Choose a directory for the virtual environment, configurations, and output files. The following example creates mpylab-work below the current directory:

mkdir mpylab-work
cd mpylab-work

3. Create a virtual environment¶

A virtual environment keeps mpylab and its Python dependencies separate from other projects and the operating system. Create one named .venv.

On macOS or Linux:

python3 -m venv .venv

On Windows PowerShell:

py -m venv .venv

This command creates the hidden .venv directory. It may take a few seconds and normally produces no output.

4. Activate the virtual environment¶

On macOS or Linux:

source .venv/bin/activate

On Windows PowerShell:

.venv\Scripts\Activate.ps1

On Windows Command Prompt instead of PowerShell:

.venv\Scripts\activate.bat

The terminal prompt usually starts with (.venv) afterwards. Activation applies only to the current terminal window. If PowerShell blocks the script because of an organization policy, use Command Prompt or ask the local administrator rather than disabling the policy globally.

5. Update pip and install mpylab¶

The following commands are the same on all systems after activation:

python -m pip install --upgrade pip
python -m pip install mpylab

This installs the core without Qt. For the limit explorer, device test windows and Qt measurement launchers, install the GUI extra:

python -m pip install "mpylab[gui]"

The graphical tools explain this requirement when Qt is missing. The mpylab-limit-explorer --help and --version commands work without Qt.

The second command installs the published release from PyPI together with its required Python dependencies.

6. Verify the installation¶

python -c "import mpylab; print(mpylab.__version__)"

The command should print the installed mpylab version without a traceback. You can also inspect the installation with:

python -m pip show mpylab

7. Use the environment again later¶

After opening a new terminal, return to the working directory and repeat only the activation command from step 4. Leave the active environment with:

deactivate

Installation alternatives¶

Install directly from GitLab when you need a revision that has not yet been published on PyPI. This requires git:

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

Replace main with a release tag for a fixed version. Editable development installation and contributor checks are documented in CONTRIBUTING.md.

Documentation build instructions are in the documentation maintenance guide.

A safe first run¶

The following example runs a small TEM/GTEM verification from measurement through evaluation. All instruments are virtual: no VISA, GPIB, network connection, or laboratory hardware is used. The run nevertheless uses the real configuration, device graph, leveling, output, and history mechanisms.

The example files are part of the repository and are not installed as stand-alone applications by pip install mpylab. With the environment from the installation steps still activated, obtain the examples using Git and enter the repository root:

git clone https://gitlab.hrz.tu-chemnitz.de/chair-of-electromagnetic-theory-and-compatibility-at-tu-dresden/mpylab/mpylab.git
cd mpylab

Run the example using the installed mpylab package:

python script/tem-verification.py script/conf/tem-gtem-verification-virtual/conf.py

The virtual configuration acknowledges the field-probe positioning messages automatically. No probe has to be moved and no key has to be pressed. During a successful run, the console shows five points of the virtual uniform area, target field strengths of 3 V/m, 5 V/m, and 10 V/m, and AM-headroom checks using the configured factor 1.8. The final measurement message is:

End of TEM verification. Status: 0

Status: 0 means that the measurement completed successfully. The run normally takes less than a minute.

The results are written below script/conf/tem-gtem-verification-virtual/output/. Important files are:

tem-verification-virtual.log: Chronological log of the measurement and evaluation.
tem-verification-virtual-after-measure-verification.p: Measurement history after acquisition and before evaluation.
tem-verification-virtual.p: Final history pickle containing measurement and evaluated results.
out_raw_tem-verification-verification.dat: Measured field-probe data.
out_processed_tem-verification-verification.dat: Main verification results as a function of frequency.
out_points_tem-verification-verification.dat: Point-wise values from the uniform area.
out_leveling_tem-verification-verification.dat: Leveling and target-field information.
out_e0y-comparison_tem-verification-verification.dat: Comparison of measured and analytical normalized field strength.

List the report sections stored in the final pickle with:

mpylab-tem-report script/conf/tem-gtem-verification-virtual/output/tem-verification-virtual.p --list-sections

The report guide explains how to generate PDF, HTML, and SVG output. The measurement history guide describes the relationship between autosave, after-measurement, and final pickles.

This virtual run verifies the Python environment, imports, virtual drivers, DOT and INI parsing, measurement loop, leveling, evaluation, and output paths. It does not validate real communication libraries, device drivers, physical limits, RF safety, or the laboratory configuration.

The exact sequence depends on the measurement environment. TEM/GTEM immunity testing, for example, requires verification before exposing an EUT. The measurement overview describes these dependencies.

Before using real hardware¶

Check at least:

DOT and INI and DAT files, including their search paths;
frequency coverage and device limits;
RF-off and amplifier protection;
preflight output;
autosave destination and write permissions;
EUT monitoring and manual intervention.

When something fails, the troubleshooting guide maps common messages to the affected configuration, communication, or runtime layer.