.. index:: e0y, GTEM field factor, TEMCell data structure

TEM e0y data
============

``TEMCell.Measure_e0y`` determines the frequency-dependent field factor of a
GTEM cell. ``TEMCell.Evaluate_e0y`` normalizes the measured field components
by the square root of forward power. Both stages use ``description`` as the
dataset name::

   raw = history.rawData_e0y[description]
   result = history.processedData_e0y[description]

The paths documented below are the supported persisted contract. Additional
leveling and workflow metadata are additive and can differ between measurement
modes.

Raw data
--------

The measured values are stored under::

   raw["efield"][frequency][port][position_index][entry_index]

``frequency`` is a numeric frequency value in Hz. ``port`` and
``position_index`` are integer indices; the innermost level is a list of
repeated measurements.

.. list-table:: Keys of a raw dataset
   :header-rows: 1
   :widths: 27 25 48

   * - Key
     - Type
     - Meaning
   * - ``efield``
     - nested mapping
     - Field and power values by frequency, port, and position.
   * - ``geometry``
     - ``GTEMGeometry``
     - Geometry used for the measurement.
   * - ``source``
     - mapping
     - Field-factor provenance; see below.
   * - ``point``
     - ``CalibrationPoint`` or ``None``
     - Named measurement point if its position is known.
   * - ``probe_axis_maps``
     - mapping
     - Axis mapping for each field probe.
   * - ``field_probe_values_are_cell_mapped``
     - ``bool``
     - ``True`` identifies ``value`` as already mapped to cell axes.
   * - ``measurement_graph_mode``
     - ``str``
     - ``"GTEM"`` for the standard workflow; the graph context actually used.
   * - ``mg``
     - ``MGraph``
     - Persisted measurement-graph description. Do not use it to restore open
       device connections.

Each entry in the innermost list has at least ``value``, ``pfwd``, and
``pbwd``. ``value`` is a vector of three field-strength quantities ordered as
``cell_x``, ``cell_y``, ``cell_z``. ``pfwd`` and ``pbwd`` are power
quantities; ``pbwd`` may be ``None``. Typical optional keys are
``value_probe`` (a vector in probe axes), ``field_probe``,
``probe_axis_map``, ``point``, and ``position``. Leveling can add further
``leveling_`` keys as well as target and protection metadata.

Provenance and position
-----------------------

``source`` always has ``source_type``, ``method``, and ``geometry``. A
measurement with a known position uses ``source_type == "point"`` and adds
``position``. Its ``x``, ``y``, ``z``, and ``h`` values are length quantities;
``h`` is the septum height at the measurement location and ``z`` is the
longitudinal cell coordinate. Older or incompletely configured datasets can
have ``source_type == "unknown"``.

Processed data
--------------

The central path for subsequent calculations is::

   result["e0y"][frequency][port][sample_index][component_index]

The component index follows ``cell_x``, ``cell_y``, ``cell_z``. Each value is
a quantity in ``(V/m)/sqrt(W)``. ``sample_index`` counts evaluated entries of
a port in position and repetition order. Prefer ``points`` for
position-related access.

.. list-table:: Top-level keys of ``processedData_e0y[description]``
   :header-rows: 1
   :widths: 30 70

   * - Key
     - Meaning
   * - ``e0y``
     - Normalized field vectors by frequency and port.
   * - ``points``
     - Complete entries by frequency and point label.
   * - ``point_summary``
     - Last summarized entry for each point and frequency.
   * - ``frequency_summary``
     - Measured-point count and names plus comparison summary.
   * - ``probe_axis_map``, ``probe_axis_maps``
     - Effective default mapping and mapping for each probe.
   * - ``geometry``, ``source``
     - Measurement geometry and provenance.
   * - ``source_e0y``
     - Name of this e0y dataset.
   * - ``e0y_comparison``
     - Pointwise comparison with the analytical GTEM value.
   * - ``e0y_comparison_summary``
     - Statistical summary of the analytical comparison by frequency.
   * - ``analytical_e0y_max_m``
     - Upper series index used by the analytical calculation.
   * - ``e0y_comparison_status``
     - Availability or reason why the comparison was skipped.

``points[frequency][point_label]`` is a list. Each entry contains ``port``,
``position_index``, ``entry_index``, ``point``, ``position``, ``value``,
``value_probe``, ``pfwd``, ``pbwd``, ``e0y``, ``field_probe``, and
``probe_axis_map``. Optional values remain present as ``None``.

``point_summary[point_label][frequency]`` contains ``point``, ``position``,
``field``, ``primary_field``, ``pfwd``, ``pbwd``, ``e0y``, ``field_probe``,
and ``probe_axis_map``. ``primary_field`` is the measured ``cell_y``
component. This summary is convenient, but older entries are lost when a
measurement is repeated; ``points`` is authoritative for complete analysis.

Analytical comparison
---------------------

With a known position and geometry,
``e0y_comparison[frequency][point_label]`` contains ``point``, ``position``,
``measured_e0y``, ``analytical_e0y``, ``ratio``, ``delta_relative``, and
``delta_db``. Both field factors are quantities in ``(V/m)/sqrt(W)``; the
ratio and deviations are numbers. The three ratio fields are ``None`` when
the analytical value is zero.

``e0y_comparison_summary[frequency]`` contains ``point_count`` and the
minimum, maximum, and mean of ``ratio`` and ``delta_db``. The status is one of
``available``, ``skipped_missing_position``, ``skipped_missing_geometry``, or
``skipped_incomplete_data``. The comparison is informational and does not
change ``e0y``.

Geometry validation and reuse
-----------------------------

Evaluation rejects conflicting active, raw, and ``source`` geometries.
Applications must therefore not copy the field factor into another history
without its associated ``geometry`` and ``source``. Use explicit e0y-source
selection for emission calculations; a verification measurement can also
provide a suitable source. See :doc:`tem-verification-data`.