Getting started
===============

Installation
------------

Use Python 3.11 or newer with a graphical desktop. In an activated virtual
environment, install the published application:

.. code-block:: console

   python -m pip install temfield-mpylab

The README describes virtual-environment creation and activation on macOS,
Linux, and Windows. As an alternative, pipx can manage an isolated application
environment:

.. code-block:: console

   pipx install temfield-mpylab

Both methods install ``temfield`` and ``temfield-info`` on the active environment's PATH.

Check the installation
----------------------

.. code-block:: console

   temfield-info
   temfield-info --json
   temfield-info --help

These diagnostic commands show versions, package location, dependencies, and
example-configuration availability without opening instruments. The example
files are not installed with the application wheel. To obtain them, keep the
application environment activated and clone the repository using Git:

.. code-block:: console

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

The GUI starts without beginning a measurement. Its entry point launches the
window; ``--json`` and the documented ``--help`` belong to the separate
``temfield-info`` command.

Explore the virtual setup
-------------------------

#. Choose **File > Load Graph ...** and open
   ``test/conf-virtual/gtem-virtual.dot`` from the cloned repository.
#. Inspect the graph filename and search paths. The graph directory is added
   to the search paths when a file is selected.
#. Inspect the logical device names (``sg``, ``amp1``, ``amp2``, ``gtem``,
   ``prb``), frequency controls, field component, and EUT controls. Do not use
   remembered settings from a laboratory configuration for a different setup.

This graph references only virtual drivers. Loading it and inspecting controls
does not start the measurement. Real measurements additionally require reviewed
device settings, correction data, and the physical probe orientation.

Measurement and results
-----------------------

Before choosing **Start Test**, select the graph and logical device mapping,
frequency range, field target, modulation, dwell time, and EUT assessment settings
for the intended setup. Keep RF-off and manual EUT controls available.

See :doc:`index` for in-loop AM validation, probe coordinates, EUT monitoring,
and CSV/JSON results. The in-loop validation is not a substitute for a separate
empty-volume headroom calibration. Detailed engineering limits and their scope
remain in that reference; this first-use guide does not redefine them.