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

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 tag such as v1.0.9 for a fixed version. For work on mpylab itself, clone the repository, activate a virtual environment in the repository root, and install the editable development and documentation dependencies:

git clone https://gitlab.hrz.tu-chemnitz.de/chair-of-electromagnetic-theory-and-compatibility-at-tu-dresden/mpylab/mpylab.git
cd mpylab
python -m pip install -e ".[dev,docs]"

The separate documentation maintenance guide explains how to build and review the documentation.

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. Use the cloned repository from the alternative installation above, activate its virtual environment, and run this command from the repository root:

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.