.. index:: installation, virtual environment, venv, pip 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: .. code-block:: console python3 --version On Windows, enter: .. code-block:: powershell 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: .. code-block:: console 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: .. code-block:: console python3 -m venv .venv On Windows PowerShell: .. code-block:: 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: .. code-block:: console source .venv/bin/activate On Windows PowerShell: .. code-block:: powershell .venv\Scripts\Activate.ps1 On Windows Command Prompt instead of PowerShell: .. code-block:: doscon .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: .. code-block:: console 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: console 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: .. code-block:: console 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: .. code-block:: console deactivate Installation alternatives ------------------------- Install directly from GitLab when you need a revision that has not yet been published on PyPI. This requires ``git``: .. code-block:: console 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: .. code-block:: console 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 :doc:`documentation maintenance guide <../help/documentation-maintenance>` 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: .. code-block:: console 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: .. code-block:: text 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: .. code-block:: console mpylab-tem-report script/conf/tem-gtem-verification-virtual/output/tem-verification-virtual.p --list-sections The :doc:`report guide <../results/reports>` explains how to generate PDF, HTML, and SVG output. The :doc:`measurement history guide <../results/history-files>` 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 :doc:`measurement overview <../measurements/index>` describes these dependencies. Before using real hardware -------------------------- Check at least: * :doc:`DOT <../configuration/dot>` and :doc:`INI and DAT files <../configuration/instrument-data>`, 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 :doc:`troubleshooting guide <../help/troubleshooting>` maps common messages to the affected configuration, communication, or runtime layer.