Measurement classes
===================

Measurement classes combine a complete domain workflow: device graph,
measurement, autosave, evaluation, traceability, and reporting. Scripts below
``script`` are the preferred operator interface and configure the respective
class.

.. list-table:: Available measurement environments
   :header-rows: 1
   :widths: 18 28 30 24

   * - Class
     - Tasks
     - Scripts
     - Preparatory data
   * - ``MSC``
     - MainCal, EUTCal, emission, and immunity in a mode-stirred chamber
     - ``msc-maincal.py``, ``msc-eutcal.py``, ``msc-emission.py``,
       ``msc-immunity.py``, and Qt variants
     - MainCal followed by EUTCal
   * - ``TEMCell``
     - Verification, e0y, emission, and immunity in TEM/GTEM cells
     - ``tem-verification.py``, ``tem-e0y.py``, ``tem-emission.py``,
       ``tem-immunity.py``, and Qt variants
     - Geometry and, depending on the task, verification or e0y
   * - ``AmplifierTest``
     - Small-signal gain, compression points, and protection limits
     - ``amplifier-test.py`` and ``amplifier-test-qt.py``
     - Device configuration and correction paths

Configuration chains
--------------------

Measurement scripts accept any number of configuration files. They are
applied from left to right, allowing a local configuration to extend a common
base configuration::

   python script/tem-immunity.py \
       /opt/mpylab/gtem/conf/immunity_conf.py \
       local_conf.py

Each file is a Python module and may define ``cdict``, ``update_config``, or
both. A ``cdict`` is merged recursively into the configuration built so far.
Nested dictionaries are retained, with later values replacing values under
the same key. Lists, tuples, and all other values are replaced in full. This
keeps a local geometry override small and explicit, for example:

.. code-block:: python

   cdict = {
       "log_filename": "local_immunity.log",
       "geometry": {
           "height": 0.75,
       },
   }

Use ``update_config(config)`` for a targeted change inside a list. The hook
runs after the ``cdict`` from the same file, modifies the assembled
configuration in place, and must return ``None``:

.. code-block:: python

   def update_config(config):
       parameters = config["measure_parameters"][0]
       parameters.update(
           {
               "dotfile": "immunity.dot",
               "SearchPaths": ["/opt/mpylab/gtem/conf"],
               "freqs": [150e6],
           }
       )

List elements are deliberately not merged implicitly. To change a complete
frequency or description list, specify the complete replacement in ``cdict``.
Use ``update_config`` for selective changes to ``measure_parameters`` or
``evaluation_parameters``.

Text and Qt scripts use the same loading and override order. Configuration
files are executable Python code and must only be loaded from trusted sources.
Always inspect the resulting assembled configuration during preflight before a
hardware run.

Common lifecycle
----------------

Measurement classes generally follow the same lifecycle:

#. Load and validate configuration.
#. Create a new history or continue from a pickle.
#. Run preflight checks and initialize devices.
#. Perform the measurement with periodic autosave.
#. Switch RF off safely and close devices.
#. Evaluate measured data.
#. Store history and derived files.
#. Optionally generate a modular report.

Pickle files are more than an export format. They retain measurement history
and allow later measurements to trace their results back to calibrations and
preceding steps.

Operator interface and programming API
--------------------------------------

Use the scripts for regular measurements. Direct calls to methods of ``MSC``,
``TEMCell``, or ``AmplifierTest`` are primarily intended for new applications,
tests, and specialized workflows.

.. toctree::
   :maxdepth: 2
   :caption: Measurement environments

   msc
   tem
   amplifier