.. index:: Installation, virtuelle Umgebung, venv, pip Einstieg ======== Diese Anleitung beginnt mit einem leeren Arbeitsverzeichnis und setzt keine Python-Erfahrung voraus. Die Befehle werden in einem Terminal eingegeben: unter macOS und Linux in *Terminal*, unter Windows in *PowerShell*. Installation Schritt für Schritt --------------------------------- 1. Python prüfen ^^^^^^^^^^^^^^^^ mpylab benötigt Python 3.11 oder neuer. Geben Sie unter macOS oder Linux ein: .. code-block:: console python3 --version Unter Windows geben Sie ein: .. code-block:: powershell py --version Die Ausgabe sollte mit ``Python 3.11`` oder einer höheren Version beginnen. Wird der Befehl nicht gefunden oder ist die Version älter, installieren Sie zuerst eine aktuelle Version von der `offiziellen Python-Webseite `_. Aktivieren Sie unter Windows bei der Installation die Option, Python über die Kommandozeile verfügbar zu machen. 2. Arbeitsverzeichnis anlegen ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Wählen Sie ein Verzeichnis für die virtuelle Umgebung, Konfigurationen und Ausgabedateien. Das folgende Beispiel legt ``mpylab-work`` unterhalb des aktuellen Verzeichnisses an: .. code-block:: console mkdir mpylab-work cd mpylab-work 3. Virtuelle Umgebung anlegen ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Eine virtuelle Umgebung hält mpylab und seine Python-Abhängigkeiten getrennt von anderen Projekten und dem Betriebssystem. Legen Sie eine Umgebung mit dem Namen ``.venv`` an. Unter macOS oder Linux: .. code-block:: console python3 -m venv .venv Unter Windows PowerShell: .. code-block:: powershell py -m venv .venv Der Befehl erzeugt das versteckte Verzeichnis ``.venv``. Dies kann einige Sekunden dauern und erzeugt normalerweise keine Ausgabe. 4. Virtuelle Umgebung aktivieren ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Unter macOS oder Linux: .. code-block:: console source .venv/bin/activate Unter Windows PowerShell: .. code-block:: powershell .venv\Scripts\Activate.ps1 In der Windows-Eingabeaufforderung anstelle von PowerShell: .. code-block:: doscon .venv\Scripts\activate.bat Danach beginnt die Eingabezeile üblicherweise mit ``(.venv)``. Die Aktivierung gilt nur für das aktuelle Terminalfenster. Blockiert PowerShell das Skript aufgrund einer betrieblichen Richtlinie, verwenden Sie die Eingabeaufforderung oder fragen Sie die lokale Administration, statt die Richtlinie global zu deaktivieren. 5. pip aktualisieren und mpylab installieren ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Nach der Aktivierung sind die folgenden Befehle auf allen Systemen gleich: .. code-block:: console python -m pip install --upgrade pip python -m pip install mpylab Der zweite Befehl installiert die veröffentlichte Version von PyPI zusammen mit den benötigten Python-Abhängigkeiten. 6. Installation prüfen ^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: console python -c "import mpylab; print(mpylab.__version__)" Der Befehl sollte ohne Traceback die installierte mpylab-Version ausgeben. Weitere Angaben zur Installation erhalten Sie mit: .. code-block:: console python -m pip show mpylab 7. Umgebung später erneut verwenden ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Wechseln Sie nach dem Öffnen eines neuen Terminals wieder in das Arbeitsverzeichnis und wiederholen Sie nur den Aktivierungsbefehl aus Schritt 4. Die aktive Umgebung verlassen Sie mit: .. code-block:: console deactivate Alternative Installationswege ----------------------------- Installieren Sie direkt aus GitLab, wenn Sie einen Stand benötigen, der noch nicht auf PyPI veröffentlicht ist. Dafür muss ``git`` installiert sein: .. 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" Ersetzen Sie ``main`` durch ein Tag wie ``v1.0.9``, um eine feste Version zu installieren. Für die Arbeit an mpylab selbst klonen Sie das Repository, aktivieren im Repository-Wurzelverzeichnis eine virtuelle Umgebung und installieren die Entwicklungs- und Dokumentationsabhängigkeiten editierbar: .. 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]" Die separate :doc:`Anleitung zur Pflege der Dokumentation <../help/documentation-maintenance>` beschreibt Build und Review der Dokumentation. Ein sicherer erster Lauf ------------------------ Das folgende Beispiel führt eine kleine TEM-/GTEM-Verifikation von der Messung bis zur Auswertung aus. Alle Geräte sind virtuell: VISA, GPIB, Netzwerkzugriff und Laborhardware werden nicht benötigt. Der Lauf verwendet trotzdem die echten Mechanismen für Konfiguration, Gerätegraph, Leveling, Ausgabe und Messhistorie. Die Beispieldateien sind Teil des Repositorys und werden durch ``pip install mpylab`` nicht als eigenständige Anwendungen installiert. Verwenden Sie das geklonte Repository aus dem alternativen Installationsweg, aktivieren Sie dessen virtuelle Umgebung und führen Sie im Repository-Wurzelverzeichnis aus: .. code-block:: console python script/tem-verification.py script/conf/tem-gtem-verification-virtual/conf.py Die virtuelle Konfiguration bestätigt die Meldungen zur Positionierung der Feldsonde automatisch. Es muss weder eine Sonde bewegt noch eine Taste gedrückt werden. Bei einem erfolgreichen Lauf zeigt die Konsole fünf Punkte der virtuellen Verifikationsebene, Zielfeldstärken von 3 V/m, 5 V/m und 10 V/m sowie AM-Headroom-Prüfungen mit dem konfigurierten Faktor 1,8. Die abschließende Messmeldung lautet: .. code-block:: text End of TEM verification. Status: 0 ``Status: 0`` bedeutet, dass die Messung erfolgreich abgeschlossen wurde. Der Lauf dauert normalerweise weniger als eine Minute. Die Ergebnisse werden unter ``script/conf/tem-gtem-verification-virtual/output/`` abgelegt. Wichtige Dateien sind: ``tem-verification-virtual.log`` Chronologisches Log von Messung und Auswertung. ``tem-verification-virtual-after-measure-verification.p`` Messhistorie nach der Messwertaufnahme und vor der Auswertung. ``tem-verification-virtual.p`` Finales History-Pickle mit Messung und ausgewerteten Ergebnissen. ``out_raw_tem-verification-verification.dat`` Gemessene Feldsondendaten. ``out_processed_tem-verification-verification.dat`` Zentrale Verifikationsergebnisse als Funktion der Frequenz. ``out_points_tem-verification-verification.dat`` Punktweise Werte der Verifikationsebene. ``out_leveling_tem-verification-verification.dat`` Leveling- und Zielfeldinformationen. ``out_e0y-comparison_tem-verification-verification.dat`` Vergleich von gemessener und analytischer normierter Feldstärke. Listen Sie die im finalen Pickle enthaltenen Report-Abschnitte auf mit: .. code-block:: console mpylab-tem-report script/conf/tem-gtem-verification-virtual/output/tem-verification-virtual.p --list-sections Die :doc:`Report-Anleitung <../results/reports>` erklärt die Erzeugung von PDF-, HTML- und SVG-Ausgaben. :doc:`Messhistorie und Ausgabedateien <../results/history-files>` erläutert den Zusammenhang zwischen Autosave-, After-Measurement- und finalem Pickle. Der virtuelle Lauf prüft Python-Umgebung, Imports, virtuelle Treiber, DOT- und INI-Parser, Messschleife, Leveling, Auswertung und Ausgabepfade. Er prüft nicht die reale Kommunikation, Gerätetreiber, physikalische Grenzen, HF-Sicherheit oder die Laborkonfiguration. Die konkrete Reihenfolge hängt von der Messumgebung ab. Bei TEM-/GTEM- Störfestigkeitsmessungen wird beispielsweise zuerst verifiziert, bevor eine Prüfung am EUT durchgeführt wird. Die :doc:`Übersicht der Messanwendungen <../measurements/index>` beschreibt diese Abhängigkeiten. Vor realer Hardware ------------------- Prüfen Sie mindestens: * :doc:`DOT- <../configuration/dot>` sowie :doc:`INI- und DAT-Dateien <../configuration/instrument-data>` einschließlich ihrer Suchpfade; * Frequenzbereich und Gerätegrenzen; * RF-Off- und Verstärkerschutz; * Preflight-Ausgabe; * Autosave-Ziel und Schreibrechte; * EUT-Überwachung und manuelle Intervention. Bei Problemen führt die :doc:`Fehlersuche <../help/troubleshooting>` von typischen Fehlermeldungen zu den betroffenen Konfigurations-, Kommunikations- oder Laufzeitebenen.