kaira.metrics.signal.ErrorVectorMagnitude

Inheritance diagram of ErrorVectorMagnitude

Inheritance diagram for ErrorVectorMagnitude

class kaira.metrics.signal.ErrorVectorMagnitude(normalize: bool = True, mode: str = 'rms', percentile: float = 95.0, threshold: float | None = None, name: str | None = None, *args: Any, **kwargs: Any)[source]

Bases: BaseMetric

Error Vector Magnitude (EVM) metric.

EVM measures the difference between the ideal constellation points and the received constellation points, expressed as a percentage. It captures both magnitude and phase errors in the received signal. Lower EVM values indicate better signal quality.

EVM is calculated as: EVM(%) = sqrt(E[||error_vector||^2] / E[||reference_vector||^2]) * 100

where error_vector = received_signal - reference_signal

Features: - Multiple calculation modes: ‘rms’, ‘peak’, ‘percentile’ - Normalized and non-normalized variants - Per-symbol and aggregate statistics - Magnitude and phase error decomposition - EVM threshold compliance checking - Support for multi-dimensional signals

normalize

Whether to normalize by reference signal power (default: True).

Type:

bool

mode

EVM calculation mode (‘rms’, ‘peak’, or ‘percentile’).

Type:

str

percentile

Percentile value when mode is ‘percentile’ (default: 95.0).

Type:

float

threshold

EVM threshold for compliance checking (in %).

Type:

Optional[float]

Methods

__init__

Initialize the EVM metric.

add_state

Add a state tensor to the module (torchmetrics compatibility).

calculate_constellation_evm

Calculate EVM for each point in a constellation.

calculate_magnitude_phase_evm

Calculate separate magnitude and phase EVM components.

calculate_multi_dimensional_evm

Calculate EVM along a specific dimension (useful for MIMO or multi-carrier systems).

calculate_per_symbol_evm

Calculate EVM for each symbol separately.

calculate_statistics

Calculate comprehensive EVM statistics.

check_compliance

Check EVM compliance against threshold.

compute

Compute the final EVM value from accumulated state.

compute_with_stats

Compute metric with mean and standard deviation.

forward

Compute the Error Vector Magnitude for the current batch.

get_evm_vs_time

Calculate EVM over sliding time windows.

get_recommended_thresholds

Get recommended EVM thresholds for common modulation schemes.

reset

Reset the metric state.

update

Update the metric state with new data.

Attributes

higher_is_better

is_differentiable

is_differentiable = True
higher_is_better = False
__init__(normalize: bool = True, mode: str = 'rms', percentile: float = 95.0, threshold: float | None = None, name: str | None = None, *args: Any, **kwargs: Any)[source]

Initialize the EVM metric.

Parameters:

  • normalize (bool) – Whether to normalize by reference signal power (default: True).

  • mode (str) – EVM calculation mode (‘rms’, ‘peak’, or ‘percentile’).

  • percentile (float) – Percentile value when mode is ‘percentile’ (default: 95.0).

  • threshold (Optional[float]) – EVM threshold for compliance checking (in %).

  • name (Optional[str]) – Optional name for the metric.

  • *args – Variable length argument list passed to the base class.

  • **kwargs – Arbitrary keyword arguments passed to the base class.

add_state(name: str, default: Tensor, dist_reduce_fx: str = 'sum')[source]

Add a state tensor to the module (torchmetrics compatibility).

reset()[source]

Reset the metric state.

update(x: Tensor, y: Tensor)[source]

Update the metric state with new data.

Parameters:

  • x (Tensor) – The transmitted/reference signal tensor.

  • y (Tensor) – The received signal tensor.

compute() → Tensor[source]

Compute the final EVM value from accumulated state.

Returns:

Error Vector Magnitude as a percentage.

Return type:

Tensor

forward(x: Tensor, y: Tensor, *args: Any, **kwargs: Any) → Tensor[source]

Compute the Error Vector Magnitude for the current batch.

Parameters:

  • x (Tensor) – The transmitted/reference signal tensor.

  • y (Tensor) – The received signal tensor.

  • *args – Variable length argument list (unused).

  • **kwargs – Arbitrary keyword arguments (unused).

Returns:

Error Vector Magnitude as a percentage.

Return type:

Tensor

calculate_per_symbol_evm(x: Tensor, y: Tensor) → Tensor[source]

Calculate EVM for each symbol separately.

Parameters:

  • x (Tensor) – The transmitted/reference signal tensor.

  • y (Tensor) – The received signal tensor.

Returns:

Per-symbol EVM values as percentages.

Return type:

Tensor

calculate_magnitude_phase_evm(x: Tensor, y: Tensor) → Tuple[Tensor, Tensor][source]

Calculate separate magnitude and phase EVM components.

Parameters:

  • x (Tensor) – The transmitted/reference signal tensor.

  • y (Tensor) – The received signal tensor.

Returns:

Magnitude EVM and Phase EVM in percentages.

Return type:

tuple[Tensor, Tensor]

check_compliance(x: Tensor, y: Tensor) → dict[source]

Check EVM compliance against threshold.

Parameters:

  • x (Tensor) – The transmitted/reference signal tensor.

  • y (Tensor) – The received signal tensor.

Returns:

Compliance report with pass/fail status and statistics.

Return type:

dict

calculate_statistics(x: Tensor, y: Tensor) → dict[source]

Calculate comprehensive EVM statistics.

Parameters:

  • x (Tensor) – The transmitted/reference signal tensor.

  • y (Tensor) – The received signal tensor.

Returns:

Dictionary containing various EVM statistics.

Return type:

dict

calculate_multi_dimensional_evm(x: Tensor, y: Tensor, dim: int = -1) → Tensor[source]

Calculate EVM along a specific dimension (useful for MIMO or multi-carrier systems).

Parameters:

  • x (Tensor) – The transmitted/reference signal tensor.

  • y (Tensor) – The received signal tensor.

  • dim (int) – Dimension along which to calculate EVM (default: -1, last dimension).

Returns:

EVM values along the specified dimension.

Return type:

Tensor

calculate_constellation_evm(constellation_points: Tensor, received_symbols: Tensor) → dict[source]

Calculate EVM for each point in a constellation.

Parameters:

  • constellation_points (Tensor) – Ideal constellation points.

  • received_symbols (Tensor) – Received symbols corresponding to constellation points.

Returns:

Per-constellation-point EVM statistics.

Return type:

dict

get_evm_vs_time(x: Tensor, y: Tensor, window_size: int = 100) → Tensor[source]

Calculate EVM over sliding time windows.

Parameters:

  • x (Tensor) – The transmitted/reference signal tensor.

  • y (Tensor) – The received signal tensor.

  • window_size (int) – Size of the sliding window.

Returns:

EVM values for each time window.

Return type:

Tensor

Get recommended EVM thresholds for common modulation schemes.

Parameters:

modulation_scheme (str) – Modulation scheme name.

Returns:

Recommended thresholds for different applications.

Return type:

dict

compute_with_stats(x: Tensor, y: Tensor, *args: Any, **kwargs: Any) → Tuple[Tensor, Tensor]

Compute metric with mean and standard deviation.

Parameters:

  • x (torch.Tensor) – The first input tensor (typically predictions)

  • y (torch.Tensor) – The second input tensor (typically targets)

  • *args – Variable length argument list.

  • **kwargs – Arbitrary keyword arguments.

Returns:

Mean and standard deviation of the metric

Return type:

Tuple[torch.Tensor, torch.Tensor]