mpylab.tools.am_headroom module

AM headroom and amplifier-saturation checks for immunity measurements.

class mpylab.tools.am_headroom.AMHeadroomResult(status: str, passed: bool, method: str, normative: bool, factor: float, expected_drop_db: float, minimum_drop_db: float, maximum_drop_db: float, actual_drop_db: float, high_value: Quantity, reduced_value: Quantity, reason: str, decision_rule: str = 'nominal_interval', decision_status: str = 'unknown', allow_upper_uncertainty: bool = False, coverage_factor: float = 1.0, standard_uncertainty_minus_db: float = 0.0, standard_uncertainty_plus_db: float = 0.0, expanded_uncertainty_minus_db: float = 0.0, expanded_uncertainty_plus_db: float = 0.0, decision_interval_lower_db: float = 0.0, decision_interval_upper_db: float = 0.0)

Bases: object

Structured result of an AM headroom check.

Parameters:

  • status (str) – Detailed decision outcome. Both fields contain passed, passed_with_uncertainty, failed_below_interval, or failed_above_interval. decision_status makes the meaning explicit for serialized consumers.

  • decision_status (str) – Detailed decision outcome. Both fields contain passed, passed_with_uncertainty, failed_below_interval, or failed_above_interval. decision_status makes the meaning explicit for serialized consumers.

  • passed (bool) – Whether exposure may proceed under the selected decision rule.

  • method (str) – Measurement method, either forward_power or field_proxy.

  • normative (bool) – Whether the result uses the normative forward-power method.

  • factor (float) – Peak-to-carrier field factor used for the headroom test.

  • expected_drop_db (float) – Generator reduction corresponding to factor.

  • minimum_drop_db (float) – Minimum accepted headroom reduction in decibels.

  • maximum_drop_db (float) – Maximum accepted headroom reduction in decibels.

  • actual_drop_db (float) – Nominal measured reduction in decibels.

  • high_value (scuq.quantities.Quantity) – Measurements before and after the generator reduction, including their SCUQ uncertainty components.

  • reduced_value (scuq.quantities.Quantity) – Measurements before and after the generator reduction, including their SCUQ uncertainty components.

  • reason (str) – Human-readable explanation of the decision.

  • decision_rule (str) – Rule used to compare the measurement with the accepted interval.

  • allow_upper_uncertainty (bool) – Whether overlap of the expanded uncertainty interval may satisfy only the upper boundary. The lower boundary always uses the nominal value.

  • coverage_factor (float) – Multiplier applied to the standard dB uncertainty.

  • standard_uncertainty_minus_db (float) – Asymmetric one-standard-uncertainty contributions on the dB scale.

  • standard_uncertainty_plus_db (float) – Asymmetric one-standard-uncertainty contributions on the dB scale.

  • expanded_uncertainty_minus_db (float) – Standard uncertainties multiplied by coverage_factor.

  • expanded_uncertainty_plus_db (float) – Standard uncertainties multiplied by coverage_factor.

  • decision_interval_lower_db (float) – Expanded-uncertainty bounds. They are diagnostic unless allow_upper_uncertainty is true and the nominal value exceeds the upper boundary.

  • decision_interval_upper_db (float) – Expanded-uncertainty bounds. They are diagnostic unless allow_upper_uncertainty is true and the nominal value exceeds the upper boundary.

actual_drop_db: float
allow_upper_uncertainty: bool = False
as_dict()

Return a pickle-friendly representation of the result.

coverage_factor: float = 1.0
decision_interval_lower_db: float = 0.0
decision_interval_upper_db: float = 0.0
decision_rule: str = 'nominal_interval'
decision_status: str = 'unknown'
expanded_uncertainty_minus_db: float = 0.0
expanded_uncertainty_plus_db: float = 0.0
expected_drop_db: float
factor: float
high_value: Quantity
maximum_drop_db: float
method: str
minimum_drop_db: float
normative: bool
passed: bool
reason: str
reduced_value: Quantity
standard_uncertainty_minus_db: float = 0.0
standard_uncertainty_plus_db: float = 0.0
status: str
mpylab.tools.am_headroom.am_headroom_drop_db(factor)

Return the required generator reduction for an AM headroom factor.

mpylab.tools.am_headroom.am_headroom_factor(modulation_depth_percent)

Return the peak-to-carrier field factor for sinusoidal AM.

modulation_depth_percent is expressed in percent. For the usual 80 % modulation depth, the returned factor is 1.8.

mpylab.tools.am_headroom.corrected_forward_power_at_port(measurement_graph, *, amplifier_output, power_meter, waveguide_port, measured_power)

Correct a directional-coupler reading to a measurement-system port.

Parameters:

  • measurement_graph (mpylab.tools.mgraph.MGraph) – Graph providing power-ratio path corrections.

  • amplifier_output (str) – Node names for the correction reference, meter, and target port.

  • power_meter (str) – Node names for the correction reference, meter, and target port.

  • waveguide_port (str) – Node names for the correction reference, meter, and target port.

  • measured_power (scuq.quantities.Quantity or None) – Power reported by the forward-power meter. None indicates that no meter result is available.

Returns:

Corrected magnitude in watts, with uncertainty preserved, or None.

Return type:

scuq.quantities.Quantity or None

mpylab.tools.am_headroom.evaluate_am_headroom(high_value, reduced_value, *, factor=1.8, method='forward_power', drop_tolerance_db=2.0, maximum_drop_db=7.1, coverage_factor=1.0, allow_upper_uncertainty=False)

Evaluate the signal reduction used to check amplifier saturation.

With the usual factor 1.8, the default nominal acceptance interval is 3.10545 dB through 7.1 dB. The lower boundary demonstrates that amplifier compression does not exceed 2 dB. The upper default follows the current IEC 61000-4-3:2020 linearity interval and is also used by mpylab as an explicit interpretation for IEC 61000-4-20:2022. Other procedures can select a different factor, drop_tolerance_db, or maximum_drop_db. field_proxy applies the same interval to field strengths when forward power is unavailable, but that result is explicitly marked as non-normative.

Parameters:

  • high_value (scuq.quantities.Quantity or real) – Values measured before and after reducing the generator. Forward power uses watts; the field proxy uses volts per metre. Plain real values are interpreted in the unit required by method and carry zero uncertainty.

  • reduced_value (scuq.quantities.Quantity or real) – Values measured before and after reducing the generator. Forward power uses watts; the field proxy uses volts per metre. Plain real values are interpreted in the unit required by method and carry zero uncertainty.

  • factor (float, optional) – Peak-to-carrier field factor. The default 1.8 corresponds to 80 % AM.

  • method ({"forward_power", "field_proxy"}, optional) – forward_power evaluates 10*log10(high/reduced) and is marked normative. field_proxy evaluates 20*log10(high/reduced) and is explicitly non-normative.

  • drop_tolerance_db (float, optional) – Amount subtracted from the expected reduction to form the lower accepted boundary. It must be finite and non-negative.

  • maximum_drop_db (float, optional) – Upper accepted boundary in decibels. The default is 7.1 dB. It must be finite and not smaller than the calculated lower boundary.

  • coverage_factor (float, optional) – Positive finite multiplier for the asymmetric standard uncertainties. It affects the reported uncertainty interval. That interval changes a decision only when allow_upper_uncertainty is true.

  • allow_upper_uncertainty (bool, optional) – If true, a nominal result above maximum_drop_db passes as passed_with_uncertainty when its expanded uncertainty interval overlaps the upper boundary. The default is false. Uncertainty is never applied at the lower boundary.

Returns:

Measurement, uncertainty interval, method classification, and decision outcome.

Return type:

AMHeadroomResult

Raises:

  • TypeError – If numeric parameters or quantities have incompatible types.

  • ValueError – If a method is unknown, a numeric parameter is out of range, or either measurement is non-positive.

Notes

By default, pass/fail uses only the nominal measured drop at both interval boundaries. Correlated SCUQ components in high_value and reduced_value are still propagated through their ratio for diagnostics and for the optional upper-bound overlap rule.