mpylab.env.tem.calibration_geometry module

Geometry helpers for TEM/GTEM calibration and verification planes.

class mpylab.env.tem.calibration_geometry.CalibrationPlane(name: str, z: Quantity, h: Quantity, points: tuple[CalibrationPoint, ...] = (), width: Quantity | None = None, height: Quantity | None = None, center: CalibrationPoint | None = None)

Bases: object

Calibration or verification x-y plane at a fixed cell position.

Parameters:

  • name (str) – Stable identifier used in measurement history and selection output.

  • z (Quantity) – Longitudinal cell coordinate in meters.

  • h (Quantity) – Septum height at z in meters.

  • points (tuple of CalibrationPoint, optional) – Ordered measurement positions in the x-y plane.

  • width (Quantity, optional) – Full dimensions of a generated uniform area.

  • height (Quantity, optional) – Full dimensions of a generated uniform area.

  • center (CalibrationPoint, optional) – Geometric center of a generated uniform area.

Notes

height is the vertical size of the plane, whereas h is the septum height used to locate the plane in the GTEM cell.

center: CalibrationPoint | None = None
classmethod from_h(name, h, geometry, points=())

Create a plane at a specified septum height.

Parameters:

  • name (str) – Stable plane identifier.

  • h (float or Quantity) – Septum height in meters.

  • geometry (GTEMGeometry) – Fixed cell geometry used to derive longitudinal coordinate z.

  • points (iterable, optional) – CalibrationPoint objects or (x, y) and (x, y, label) tuples. Numeric coordinates denote meters.

Returns:

Immutable plane with normalized coordinates.

Return type:

CalibrationPlane

classmethod from_uniform_area_h(name, h, width, height, geometry, center=(0, 0))

Create a uniform-area plane from its size according to IEC 61000-4-20.

width and height are the full dimensions of the uniform area, not the point spacing. Areas up to 0.5 m x 0.5 m use four corners plus the center point. Larger or non-tabulated areas use the smallest 0.5 m grid that covers the area.

Parameters:

  • name (str) – Stable plane identifier.

  • h (float or Quantity) – Septum height locating the plane, in meters.

  • width (float or Quantity) – Full horizontal and vertical dimensions of the uniform area.

  • height (float or Quantity) – Full horizontal and vertical dimensions of the uniform area.

  • geometry (GTEMGeometry) – Fixed cell geometry used to derive longitudinal coordinate z.

  • center (CalibrationPoint or tuple, optional) – Area center as a point or (x, y) coordinates in meters.

Returns:

Plane containing the generated ordered measurement points.

Return type:

CalibrationPlane

Raises:

ValueError – If either area dimension is not positive.

classmethod from_uniform_area_z(name, z, width, height, geometry, center=(0, 0))

Create a uniform-area plane at a longitudinal coordinate.

Parameters:

  • name (str) – Stable plane identifier.

  • z (float or Quantity) – Longitudinal coordinate locating the plane, in meters.

  • width (float or Quantity) – Full horizontal and vertical dimensions of the uniform area.

  • height (float or Quantity) – Full horizontal and vertical dimensions of the uniform area.

  • geometry (GTEMGeometry) – Fixed cell geometry used to derive septum height h.

  • center (CalibrationPoint or tuple, optional) – Area center as a point or (x, y) coordinates in meters.

Returns:

Plane containing the generated ordered measurement points.

Return type:

CalibrationPlane

Raises:

ValueError – If either area dimension is not positive.

classmethod from_z(name, z, geometry, points=())

Create a plane at a longitudinal coordinate.

Parameters:

  • name (str) – Stable plane identifier.

  • z (float or Quantity) – Longitudinal coordinate in meters.

  • geometry (GTEMGeometry) – Fixed cell geometry used to derive septum height h.

  • points (iterable, optional) – CalibrationPoint objects or (x, y) and (x, y, label) tuples. Numeric coordinates denote meters.

Returns:

Immutable plane with normalized coordinates.

Return type:

CalibrationPlane

h: Quantity
height: Quantity | None = None
name: str
points: tuple[CalibrationPoint, ...] = ()
width: Quantity | None = None
z: Quantity
class mpylab.env.tem.calibration_geometry.CalibrationPlaneSelection(mode: str, target_h: Quantity, plane: CalibrationPlane | None = None, lower: CalibrationPlane | None = None, upper: CalibrationPlane | None = None, fraction: float | None = None)

Bases: object

Result of selecting calibration data for a target height.

Parameters:

  • mode (str) – One of exact, nearest, or interpolate.

  • target_h (Quantity) – Requested septum height in meters.

  • plane (CalibrationPlane, optional) – Selected plane for exact or nearest selection.

  • lower (CalibrationPlane, optional) – Bracketing planes for interpolation.

  • upper (CalibrationPlane, optional) – Bracketing planes for interpolation.

  • fraction (float, optional) – Linear height fraction from lower to upper.

fraction: float | None = None
lower: CalibrationPlane | None = None
mode: str
plane: CalibrationPlane | None = None
target_h: Quantity
upper: CalibrationPlane | None = None
class mpylab.env.tem.calibration_geometry.CalibrationPoint(x: Quantity, y: Quantity, label: str | None = None)

Bases: object

Labeled point in a calibration or verification x-y plane.

Parameters:

  • x (Quantity) – Coordinates in the plane, expressed as lengths.

  • y (Quantity) – Coordinates in the plane, expressed as lengths.

  • label (str, optional) – Stable human-readable point identifier.

classmethod from_values(x, y, label=None)

Create a point and normalize its coordinates to meters.

Parameters:

  • x (float or Quantity) – Plane coordinates. Numeric values are interpreted in meters.

  • y (float or Quantity) – Plane coordinates. Numeric values are interpreted in meters.

  • label (str, optional) – Stable point identifier.

Returns:

Normalized immutable point.

Return type:

CalibrationPoint

label: str | None = None
x: Quantity
y: Quantity
class mpylab.env.tem.calibration_geometry.GTEMGeometry(height_per_z: float, width_per_z: float | None = None, gap_per_z: float | None = None, characteristic_impedance: float = 50, max_height: Quantity | None = None, type_designation: str | None = None, geometry_heights: tuple[Quantity, ...] = (), geometry_z_positions: tuple[Quantity, ...] = (), delta_z: Quantity | None = None, first_index: int | None = None)

Bases: object

Fixed linear GTEM geometry using h = height_per_z * z.

Parameters:

  • height_per_z (float or dimensionless Quantity) – Ratio between septum height h and longitudinal coordinate z.

  • width_per_z (float or dimensionless Quantity, optional) – Ratio between cell width a and z used by analytical e0y.

  • gap_per_z (float or dimensionless Quantity, optional) – Ratio between septum gap g and z used by analytical e0y.

  • characteristic_impedance (float or Quantity, optional) – Cell impedance; its numeric expectation is stored as a float in ohms. The default is 50.

  • max_height (Quantity, optional) – Maximum septum height, stored in meters.

  • type_designation (str, optional) – Human-readable cell designation such as "GTEM 1750".

  • geometry_heights (tuple of Quantity, optional) – Heights used to establish the fixed geometry. They do not define calibration or verification planes.

  • geometry_z_positions (tuple of Quantity, optional) – Positions derived from h / height_per_z for geometry_heights.

  • delta_z (Quantity, optional) – Measured spacing between successive geometry-height stations.

  • first_index (int, optional) – Index metadata for the first measured station. It does not define an absolute first z coordinate and does not enter the slope fit.

a_from_z(z)

Calculate cell width from a longitudinal coordinate.

Parameters:

z (float or Quantity) – Longitudinal coordinate. Numeric input is interpreted in meters.

Returns:

Width a = width_per_z * z in meters.

Return type:

scuq.quantities.Quantity

Raises:

ValueError – If width_per_z is not defined.

characteristic_impedance: float = 50
delta_z: Quantity | None = None
first_index: int | None = None
classmethod from_height_series(h_max, heights, delta_z, first_index=1, relative_tolerance=0.02, type_designation=None, width_per_z=None, gap_per_z=None, characteristic_impedance=50)

Create GTEM geometry from measured heights at equidistant z positions.

The height series defines the fixed cell geometry only. It does not define calibration or verification planes. For GTEM cells this helper constructs the zero-offset model h = k * z while deriving k only from measured height differences at the known spacing.

Parameters:

  • h_max (float, Quantity, or str) – Maximum height in meters, or a GTEM type designation whose numeric component specifies millimeters.

  • heights (sequence of float or Quantity) – At least two positive, strictly increasing measured heights.

  • delta_z (float or Quantity) – Fixed measured distance between successive height stations.

  • first_index (int, optional) – Index metadata for the first station. It does not establish an absolute z origin or contribute to the fitted slope.

  • relative_tolerance (float, optional) – Maximum relative deviation of each adjacent height-difference slope from their mean.

  • type_designation (str, optional) – Human-readable cell designation. It defaults to h_max when that argument is a string.

  • width_per_z (float or dimensionless Quantity, optional) – Cell-width to longitudinal-position ratio.

  • gap_per_z (float or dimensionless Quantity, optional) – Septum-gap to longitudinal-position ratio.

  • characteristic_impedance (float or Quantity, optional) – Characteristic impedance. Numeric input is interpreted in ohms; a quantity must have an electrical-resistance dimension.

Returns:

Geometry whose height_per_z is the mean of the adjacent height differences divided by delta_z.

Return type:

GTEMGeometry

Raises:

ValueError – If spacing, indices, heights, or adjacent slopes are invalid.

classmethod from_max_height(max_height, z_at_max_height, type_designation=None, width_per_z=None, gap_per_z=None, characteristic_impedance=50)

Create geometry from maximum height and its longitudinal position.

Parameters:

  • max_height (float or Quantity) – Maximum septum height. Numeric input is interpreted in meters.

  • z_at_max_height (float or Quantity) – Longitudinal coordinate at max_height, in meters.

  • type_designation (str, optional) – Human-readable GTEM designation.

  • width_per_z (float or dimensionless Quantity, optional) – Cell-width to longitudinal-position ratio.

  • gap_per_z (float or dimensionless Quantity, optional) – Septum-gap to longitudinal-position ratio.

  • characteristic_impedance (float or Quantity, optional) – Characteristic impedance. Numeric input is interpreted in ohms; a quantity must have an electrical-resistance dimension.

Returns:

Geometry with height_per_z = max_height / z_at_max_height.

Return type:

GTEMGeometry

Raises:

ValueError – If z_at_max_height is zero.

classmethod from_type_designation(type_designation, z_at_max_height, width_per_z=None, gap_per_z=None, characteristic_impedance=50)

Create geometry using a maximum height encoded in its designation.

Parameters:

  • type_designation (str) – Designation such as "GTEM 1750"; its numeric part is treated as the maximum height in millimeters.

  • z_at_max_height (float or Quantity) – Longitudinal coordinate at maximum height, in meters.

  • width_per_z (float or dimensionless Quantity, optional) – Cell-width to longitudinal-position ratio.

  • gap_per_z (float or dimensionless Quantity, optional) – Septum-gap to longitudinal-position ratio.

  • characteristic_impedance (float or Quantity, optional) – Characteristic impedance. Numeric input is interpreted in ohms; a quantity must have an electrical-resistance dimension.

Returns:

Geometry derived from the parsed maximum height.

Return type:

GTEMGeometry

g_from_z(z)

Calculate septum gap from a longitudinal coordinate.

Parameters:

z (float or Quantity) – Longitudinal coordinate. Numeric input is interpreted in meters.

Returns:

Gap g = gap_per_z * z in meters.

Return type:

scuq.quantities.Quantity

Raises:

ValueError – If gap_per_z is not defined.

gap_per_z: float | None = None
geometry_heights: tuple[Quantity, ...] = ()
geometry_z_positions: tuple[Quantity, ...] = ()
h_from_z(z)

Calculate septum height from a longitudinal coordinate.

Parameters:

z (float or Quantity) – Longitudinal coordinate. Numeric input is interpreted in meters.

Returns:

Height h = height_per_z * z in meters.

Return type:

scuq.quantities.Quantity

height_per_z: float
max_height: Quantity | None = None
type_designation: str | None = None
width_per_z: float | None = None
z_from_h(h)

Calculate longitudinal coordinate from septum height.

Parameters:

h (float or Quantity) – Septum height. Numeric input is interpreted in meters.

Returns:

Coordinate z = h / height_per_z in meters.

Return type:

scuq.quantities.Quantity

Raises:

ValueError – If height_per_z is zero.

mpylab.env.tem.calibration_geometry.gtem_geometry_from_config(config)

Create a GTEMGeometry from script configuration data.

Parameters:

config (GTEMGeometry or dict) – Existing geometry or mapping using one of three representations: heights with delta_z, z_at_max_height with a maximum height, or the direct ratio height_per_z. Optional analytical parameters are width_per_z, gap_per_z, and characteristic_impedance.

Returns:

Normalized fixed geometry.

Return type:

GTEMGeometry

Raises:

  • TypeError – If config is neither a geometry nor a mapping.

  • ValueError – If the geometry kind or required representation fields are invalid.

mpylab.env.tem.calibration_geometry.parse_gtem_max_height(type_designation)

Parse the maximum height from a GTEM type designation.

"GTEM 1750" is interpreted as a maximum height of 1750 mm.

Parameters:

type_designation (str) – Designation containing a numeric maximum height in millimeters.

Returns:

Maximum cell height reduced to meters.

Return type:

scuq.quantities.Quantity

Raises:

ValueError – If the designation contains no numeric value.

mpylab.env.tem.calibration_geometry.same_calibration_plane(left, right, tolerance=1e-09)

Compare two named calibration-plane definitions.

Parameters:

  • left (CalibrationPlane) – Plane definitions to compare.

  • right (CalibrationPlane) – Plane definitions to compare.

  • tolerance (float, optional) – Absolute tolerance in meters for positions and dimensions.

Returns:

True when names, positions, dimensions, centers, and ordered labeled points agree within tolerance.

Return type:

bool

mpylab.env.tem.calibration_geometry.same_gtem_geometry(left, right, tolerance=1e-09)

Compare the physical parameters of two fixed GTEM geometries.

Parameters:

  • left (GTEMGeometry or dict) – Geometries or accepted configuration mappings to compare.

  • right (GTEMGeometry or dict) – Geometries or accepted configuration mappings to compare.

  • tolerance (float, optional) – Absolute comparison tolerance. Lengths use meters; ratios and characteristic impedance use their stored numeric values.

Returns:

True when height, width and gap ratios, characteristic impedance, and maximum height agree within tolerance.

Return type:

bool

Notes

Descriptive metadata and the original height-series samples are not part of this physical-equivalence comparison.

mpylab.env.tem.calibration_geometry.select_calibration_plane(planes: Iterable[CalibrationPlane], target_h, on_missing='error', tolerance=1e-09)

Select or bracket a calibration plane for a requested height.

on_missing controls behavior when no plane at exactly target_h is available:

  • "error" raises ValueError.

  • "nearest" returns the closest plane.

  • "interpolate" returns lower/upper planes and the linear fraction between them.

Parameters:

  • planes (iterable of CalibrationPlane) – Available planes. Input order is irrelevant; selection sorts by h.

  • target_h (float or Quantity) – Requested septum height. Numeric input is interpreted in meters.

  • on_missing ({"error", "nearest", "interpolate"}, optional) – Policy used when no plane matches target_h within tolerance.

  • tolerance (float, optional) – Absolute height tolerance in meters for an exact match.

Returns:

Exact or nearest selection, or bracketing planes and interpolation fraction. This function selects geometry only; it does not interpolate measured values itself.

Return type:

CalibrationPlaneSelection

Raises:

ValueError – If no planes exist, exact selection is required but unavailable, the policy is unsupported, or interpolation would extrapolate beyond the available height range.

mpylab.env.tem.calibration_geometry.uniform_area_from_config(config, geometry)

Create a norm-oriented uniform-area plane from configuration data.

Parameters:

  • config (CalibrationPlane or dict) – Existing plane or mapping containing name, full width and height, and exactly one position key, h or z. Numeric lengths are interpreted in meters. center defaults to (0, 0).

  • geometry (GTEMGeometry) – Fixed cell geometry used to convert between h and z.

Returns:

Plane populated with the norm-oriented uniform-area points.

Return type:

CalibrationPlane

Raises:

  • TypeError – If config is neither a plane nor a mapping.

  • ValueError – If required dimensions, the name, or the plane position are missing.