TEM verification data
=====================

A TEM verification history contains the measured point data, its normative
evaluation, and the forward-power references derived for later immunity tests.
Only load trusted pickles with :func:`mpylab.env.Measure.load_pickle_compat`.

Indices and structure
---------------------

``description`` is the user-selected dataset name, for example
``"stage1_verification"``. Frequencies are numeric mapping keys in hertz.
``verification_target_label`` identifies a measured verification target;
``target_label`` identifies a derived immunity-test level. Applications
should construct neither label themselves.

.. code-block:: text

   rawData_Verification[description]
   processedData_Verification[description]
   ├── target_results[verification_target_label]
   ├── immunity_reference[target_label][frequency]
   └── all_targets_summary

Schema 4 always places explicitly labelled verification targets below
``target_results``—including a single labelled target. Use
``select_verification_target``. There is no order-dependent flat target
projection and no duplicate frequency-first immunity-reference mapping.

Raw data
--------

The raw dataset is available as::

   raw = history.rawData_Verification[description]

Important metadata are ``verification_evaluation_schema_version`` (``4``),
``geometry``, ``uniform_area_name``, ``uniform_area`` (the complete
``CalibrationPlane``), ``probe_to_cell_axis_mappings``,
``verification_field_strength``, ``target_forward_power``,
``target_forward_power_level_dbm``, ``immunity_test_field_strengths``,
``verification_measurement_targets``,
``amplifier_saturation_test_field_factor``,
``amplifier_saturation_decision_settings``, and
``initial_signal_generator_power_level_dbm``. The stored ``mg`` remains
unchanged; schema 4 deliberately does not migrate the measurement graph.

Measurements are indexed as follows::

   raw["efield"][frequency][port][point_index] -> list[entry]

Each entry uses descriptive names: ``cell_field_vector`` and optional
``probe_field_vector`` contain ``Quantity(V/m)`` vectors;
``measured_forward_power`` and ``measured_backward_power`` are
``Quantity(W)``. Optional fields record the point, probe mapping, leveling,
verification field strengths, and amplifier-saturation evidence.

Normative evaluation
--------------------

``constant_forward_power`` follows IEC 61000-4-20, 5.2.2.4.1.
``constant_field_strength`` follows 5.2.2.4.2 and Equation 17. Absolute
logarithmic power levels are stored in dBm:

.. math::

   P_\mathrm{ref,dBm}=\overline{P_\mathrm{dBm}}+k\,s_P,

where :math:`s_P` is a spread in dB and :math:`k=1.15` by default. Therefore
``measured_forward_power_level_mean_dbm`` and
``normative_reference_forward_power_level_dbm`` are absolute dBm levels,
whereas ``measured_forward_power_sigma_db`` remains a relative dB quantity.

The regular field-uniformity criterion is strictly below 2.61 dB; 2.61 dB
already begins the exception band, which ends at 4.35 dB. Likewise, the
regular TEM-mode criterion is strictly ``Q75 < 0.5``; ``Q75 == 0.5`` begins
the exception band.

Processed target result
-----------------------

After selecting a target (or for an unlabelled legacy-style run), these are
the principal frequency-indexed fields:

.. list-table:: Reference and assessment fields
   :header-rows: 1
   :widths: 43 20 37

   * - Key
     - Type
     - Meaning
   * - ``normative_reference_field_strength[frequency]``
     - ``Quantity(V/m)``
     - Reference field from the selected uniformity evaluation.
   * - ``normative_reference_forward_power[frequency]``
     - ``Quantity(W)``
     - Normatively derived reference forward power.
   * - ``normative_reference_forward_power_level_dbm[frequency]``
     - ``float`` or ``None``
     - Same statistical reference as an absolute dBm level when applicable.
   * - ``normative_reference_forward_power_method[frequency]``
     - ``str``
     - Derivation-method identifier.
   * - ``measured_forward_power_samples[frequency]``
     - sequence of ``Quantity(W)``
     - Point-wise measurements.
   * - ``measured_forward_power_mean[frequency]``
     - ``Quantity(W)``
     - Arithmetic mean; not a substitute for the normative reference.
   * - ``measured_forward_power_level_mean_dbm[frequency]``
     - ``float``
     - Mean of the measured absolute power levels in dBm.
   * - ``measured_forward_power_sigma_db[frequency]``
     - ``float``
     - Sample standard deviation in dB.
   * - ``field_strength_per_sqrt_forward_power[frequency]``
     - ``Quantity((V/m)/sqrt(W))``
     - Field factor based on the normative references.
   * - ``verification_target_field_strength[frequency]``
     - ``Quantity(V/m)``
     - Effective verification target.
   * - ``forward_power_for_verification_target[frequency]``
     - ``Quantity(W)``
     - Normative power scaled to that target.

``verification_by_frequency`` contains the complete evaluator result.
``frequency_results`` is the report-oriented frequency view;
``point_measurements_by_frequency`` contains complete point entries, and
``point_results`` contains compact point summaries. The related fields include
``normative_reference_field_strength_by_scale``,
``measured_primary_field_level_mean_dbv_per_m``,
``measured_primary_field_sigma_db``, ``measured_primary_field_mean``,
``measured_primary_field_standard_deviation``,
``primary_field_uniformity_span_db``,
``secondary_to_primary_field_ratio_q75``, ``measured_point_coverage``, and
``normatively_covered_points``.

``verification_passed[frequency]`` combines field uniformity, TEM-mode
dominance, and target reachability. The individual maps are
``field_uniformity_passed`` and ``tem_mode_passed``.
``frequency_range_summary`` contains
``verification_overall_passed``, ``field_uniformity_overall_passed``,
``tem_mode_overall_passed``, and the exception-frequency counts.
``all_targets_summary`` summarizes the target container. Provenance is grouped
below ``provenance``; reprocessing details are in ``provenance["reprocessing"]``.
``reference_dataset`` registers the derived reference with the history.
``analytical_e0y_max_series_index`` describes the optional analytical
comparison setting.

Immunity references
-------------------

The sole canonical path is::

   processed["immunity_reference"][target_label][frequency]

An entry contains ``label``, ``immunity_test_field_strength``,
``normative_reference_field_strength``,
``normative_reference_forward_power``, and
``immunity_test_forward_power``. The separate amplifier-saturation procedure
uses ``amplifier_saturation_test_field_factor``,
``amplifier_saturation_test_field_increase_db``,
``amplifier_saturation_test_field_strength``, and
``amplifier_saturation_test_forward_power``. Its evidence is stored below
``amplifier_saturation_check_passed``,
``amplifier_saturation_check_methods``,
``amplifier_saturation_decision_settings``, and
``amplifier_saturation_check``. The saturation-test power is not the regular
EUT exposure power.

Scaling follows

.. math::

   P_\mathrm{test}=P_\mathrm{ref}
   \left(\frac{E_\mathrm{test}}{E_\mathrm{ref}}\right)^2.

Preferred access
----------------

.. code-block:: python

   from mpylab.env.Measure import load_pickle_compat
   from mpylab.tools.aunits import EFIELD
   from scuq.quantities import Quantity

   history = load_pickle_compat("temcell_history.p")
   target = history.select_verification_target(
       reference="stage1_verification",
       verification_target="verification-3-v-per-m",
   )
   selection = history.select_immunity_reference_power(
       reference="stage1_verification",
       frequency=150e6,
       required_immunity_efield=Quantity(EFIELD, 3.0),
   )
   power = selection["immunity_test_forward_power"]

The later immunity measurement records this selection below
``rawData_Immunity[description]["immunity_reference_power_selection"][frequency]``
and in ``processedData_Immunity``.

Reprocessing and compatibility
------------------------------

Schema 4 is a deliberate hard rename; schema-3 aliases are not written.
Loading a historical pickle does not silently re-evaluate it. A trusted source
can be migrated reproducibly without overwriting it:

.. code-block:: console

   python tools/reprocess_tem_verification_pickle.py SOURCE.p CORRECTED.p \
       --description stage1_verification

The corrected result records the source SHA256, mpylab version, UTC timestamp,
and standards reference. A power value alone never authorizes exposure:
verification, amplifier-saturation evidence, frequency coverage, preflight,
and configured protection limits must all be valid.