Workflow configuration with conf.py
===================================

A ``conf.py`` connects a measurement script, history pickle, and instrument
configuration. It is executable Python code and must therefore be loaded only
from a trusted source.

Basic structure
---------------

Scripts expect a dictionary named ``cdict``. Typical keys are:

.. code-block:: python

   cdict = {
       "pickle_input_filename": None,
       "pickle_output_filename": str(OUTPUT_DIR / "measurement.p"),
       "autosave_filename": str(OUTPUT_DIR / "measurement-autosave.p"),
       "log_filename": str(OUTPUT_DIR / "measurement.log"),
       "minimal_autosave_interval": 3600,
       "descriptions": ["example"],
       "measure_parameters": [{...}],
       "evaluation_parameters": [{...}],
   }

Not every script requires every key. The supplied templates define the
contract for their respective measurement class.

Inspect the effective configuration
-----------------------------------

Configuration sources are applied from left to right. Display the completely
merged configuration without starting a measurement:

.. code-block:: console

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

Output is deterministic, attributes every scalar value to the last source
that changed it, and redacts password, secret, and token keys. The shared Qt
starters show the same snapshot on the read-only **Configuration** tab. The
snapshot is taken before UI and other runtime objects are attached. **Stop /
RF Off** remains visible regardless of the selected tab.

For compatibility, ``update_conf`` still mutates its mapping and returns
``None``. New applications can use ``resolve_config_chain`` when they also
need ordered source and change provenance.

History and files
-----------------

``pickle_input_filename``
   Loads the complete history from a preceding measurement. ``None`` creates
   a new instance.

``pickle_output_filename``
   Contains the extended history after successful completion.

``autosave_filename``
   Is updated during a running measurement. On resume, an existing autosave
   takes precedence over the normal input pickle.

Place all runtime output in a separate ``output`` directory. Prefer paths
based on ``Path(__file__).resolve().parent`` so they do not depend on the
current working directory.

Measurement parameters
----------------------

Each entry in ``measure_parameters`` describes one domain dataset. The script
adds ``description`` from ``descriptions``. Typical parameters include:

* ``dotfile`` and ``SearchPaths``;
* frequencies, levels, and measurement times;
* ``names`` mapping logical names to DOT nodes;
* preflight and protection settings;
* measurement-specific geometry or EUT settings.

Several descriptions may share one parameter block or map positionally to
several blocks. Keep descriptions short, stable, and unambiguous to preserve
traceable histories.

Named TEM uniform areas
~~~~~~~~~~~~~~~~~~~~~~~

The TEM starters accept ``uniform_areas`` as a mapping from stable names to
area definitions. A mapping key must match ``name`` in its definition. Each
definition contains the full width and height, its center, and exactly one
plane position, ``h`` or ``z``.

``uniform_area`` continues to identify the default definition for older
configurations. When ``uniform_areas`` is also present, the starters register
all named areas without registering the default twice. Redefining an existing
name with different geometry is rejected so the meaning of a history pickle
cannot change silently.

``Measure_Verification`` processes exactly one area per dataset. With several
areas, each parameter block must explicitly select the required name under
``uniform_area``. Because configuration chains replace lists as complete
values, an ``update_config(config)`` hook should deliberately copy or extend
existing ``measure_parameters`` rather than accidentally discard an already
hardware-configured block.

Evaluation parameters
---------------------

``evaluation_parameters`` contains evaluation decisions only, such as
reference datasets, interpolation methods, or output channels. A measurement
parameter should not be configured again with a different meaning during
evaluation.

Safe adaptation strategy
------------------------

#. Copy the closest virtual example.
#. Adapt output and pickle paths.
#. Reduce frequencies and descriptions for a short run.
#. Replace DOT, INI, and DAT files.
#. Run preflight and virtual tests.
#. Only then enable real bus parameters.