[Bug] Core simulator incorrectly models out-of-band interference due to lack of receiver selectivity

[davidbits]

Affected Package / Scope

Core Simulator (fers)

Bug Description

The core simulation engine does not model receiver front-end selectivity (i.e., RF/IF filtering). It operates by calculating the complex baseband equivalent for every signal path and then performing a direct linear superposition of these baseband signals at the receiver.

This architectural choice leads to a physically inaccurate representation of how a real receiver handles interference. Out-of-band signals are not attenuated or filtered based on the receiver's operating frequency and bandwidth. Instead, they are treated as if they were in-band, causing their energy to be aliased into the final baseband output, which corrupts the desired signal.

This limitation makes the simulator unsuitable for accurately modeling scenarios involving electronic warfare, out-of-band jammers, or interference from other radio systems.

Steps to Reproduce

1. Create a minimal CW simulation scenario with the following components:
   • A receiver (Rx) with its timing source frequency set to 1.0 GHz, representing its LO.
   • A weak in-band transmitter (Tx_InBand) with a carrier frequency of 1.0 GHz and a power of 1W.
   • A strong out-of-band transmitter (Tx_OutOfBand) with a carrier frequency of 1.1 GHz and a power of 1000W.
   • All components are static and within range of each other.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE simulation SYSTEM "fers-xml.dtd">
<simulation name="OutOfBandInterferenceTest">
    <parameters>
        <starttime>0</starttime>
        <endtime>0.001</endtime>
        <rate>20e6</rate> <!-- 20 Msps, for a +/- 10 MHz baseband -->
    </parameters>

    <waveform name="InBandWave">
        <power>1.0</power>
        <carrier_frequency>1.0e9</carrier_frequency>
        <cw/>
    </waveform>

    <waveform name="OutOfBandWave">
        <power>1000.0</power>
        <carrier_frequency>1.1e9</carrier_frequency>
        <cw/>
    </waveform>

    <timing name="RxTiming">
        <frequency>1.0e9</frequency> <!-- Receiver LO Frequency -->
    </timing>

    <antenna name="IsotropicAnt" pattern="isotropic"/>

    <platform name="RxPlatform">
        <motionpath>
            <positionwaypoint>
                <x>0</x>
                <y>0</y>
                <altitude>0</altitude>
                <time>0</time>
            </positionwaypoint>
        </motionpath>
        <fixedrotation>
            <startazimuth>0</startazimuth>
            <startelevation>0</startelevation>
            <azimuthrate>0</azimuthrate>
            <elevationrate>0</elevationrate>
        </fixedrotation>
        <receiver name="Rx" antenna="IsotropicAnt" timing="RxTiming">
            <cw_mode/>
        </receiver>
    </platform>

    <platform name="TxInBandPlatform">
        <motionpath>
            <positionwaypoint>
                <x>1000</x>
                <y>0</y>
                <altitude>0</altitude>
                <time>0</time>
            </positionwaypoint>
        </motionpath>
        <fixedrotation>
            <startazimuth>0</startazimuth>
            <startelevation>0</startelevation>
            <azimuthrate>0</azimuthrate>
            <elevationrate>0</elevationrate>
        </fixedrotation>
        <transmitter name="Tx_InBand" waveform="InBandWave" antenna="IsotropicAnt" timing="RxTiming">
            <cw_mode/>
        </transmitter>
    </platform>

    <platform name="TxOutOfBandPlatform">
        <motionpath>
            <positionwaypoint>
                <x>2000</x>
                <y>0</y>
                <altitude>0</altitude>
                <time>0</time>
            </positionwaypoint>
        </motionpath>
        <fixedrotation>
            <startazimuth>0</startazimuth>
            <startelevation>0</startelevation>
            <azimuthrate>0</azimuthrate>
            <elevationrate>0</elevationrate>
        </fixedrotation>
        <transmitter name="Tx_OutOfBand" waveform="OutOfBandWave" antenna="IsotropicAnt" timing="RxTiming">
            <cw_mode/>
        </transmitter>
    </platform>
</simulation>

2. Run the FERS simulation with the above scenario.
3. Analyze the output HDF5 file for the receiver Rx. Perform an FFT on the I/Q data.

Expected Behavior

A real receiver with a front-end filter centered at 1.0 GHz would heavily attenuate the 1.1 GHz signal from Tx_OutOfBand. After mixing with the 1.0 GHz LO, the jammer's signal would appear at 100 MHz in the IF stage and be completely rejected by any reasonable IF filter (e.g., 10 MHz bandwidth).

The final digitized I/Q data should only contain the DC component from the weak in-band transmitter (Tx_InBand) and system noise. The strong out-of-band signal should be absent.

Actual Behavior

The FERS engine calculates the baseband representation of both signals and adds them linearly. The signal from Tx_OutOfBand is treated as a 100 MHz complex sinusoid at baseband (1.1 GHz - 1.0 GHz).

When this summed signal is sampled at 20 Msps, the 100 MHz component aliases down to DC (100 MHz % 20 MHz = 0). The resulting I/Q data in the output file is dominated by a massive DC component from the aliased out-of-band transmitter, completely obscuring the weak in-band signal.

This is incorrect because the information about the jammer's original carrier frequency is lost during the baseband summation, making it impossible to filter out correctly in post-processing. The simulation effectively assumes the receiver has infinite bandwidth.

Environment

• OS: Any
• For fers: Any build, commit hash f0c75a2
• For fers-ui: N/A

[davidbits]

Analysis and Verification

To verify this behavior, a Python analysis script (analysis.py) was created to process the HDF5 output from the minimal example scenario. The script performs an FFT on the receiver's I/Q data and compares the measured results against theoretical expectations.

Theoretical Expectations

1. Correct Behavior (Real Receiver): A real receiver would use RF/IF filters to reject the 1.1 GHz out-of-band signal. The final output would only contain the DC component from the weak 1.0 GHz in-band transmitter.
2. FERS Behavior (The Bug): FERS performs a linear summation of the baseband signals before filtering. The 1.1 GHz signal is converted to a 100 MHz baseband signal relative to the 1.0 GHz LO. When sampled at 20 Msps, this 100 MHz signal aliases directly to 0 Hz (DC), as 100 MHz % 20 MHz = 0. The final output should therefore contain a massive DC component that is the vector sum of both the in-band and the aliased out-of-band signals.

Analysis Script (analysis.py)

Analysis Script

import h5py
import numpy as np
import matplotlib.pyplot as plt

# --- Theoretical Constants and Scenario Parameters ---
C = 299792458.0  # Speed of light in m/s

# In-Band Transmitter (Tx1)
PT1 = 1.0  # Power in Watts
FC1 = 1.0e9  # Carrier Frequency in Hz
R1 = 1000.0  # Range in meters

# Out-of-Band Transmitter (Tx2)
PT2 = 1000.0
FC2 = 1.1e9
R2 = 2000.0

# Receiver
F_LO = 1.0e9
F_SAMPLE = 20.0e6  # Sampling rate from XML


def calculate_theoretical_amplitude(pt, fc, r):
    """Calculates the theoretical received voltage amplitude."""
    wavelength = C / fc
    # Friis equation for isotropic antennas (Gt=Gr=1)
    pr = pt * (wavelength / (4 * np.pi * r)) ** 2
    # Voltage is proportional to sqrt(Power)
    amplitude = np.sqrt(pr)
    return amplitude


def analyze_h5_file(filename="Rx_results.h5"):
    """
    Reads the FERS HDF5 output, performs FFT analysis, and plots the results.
    """
    try:
        with h5py.File(filename, 'r') as f:
            print(f"Successfully opened '{filename}'")

            # FERS CW output saves I and Q data separately
            if 'I_data' not in f or 'Q_data' not in f:
                print("Error: 'I_data' or 'Q_data' datasets not found in HDF5 file.")
                return

            i_data = f['I_data'][:]
            q_data = f['Q_data'][:]

            # Combine into a complex signal
            iq_signal = i_data + 1j * q_data

            num_samples = len(iq_signal)
            print(f"Read {num_samples} complex samples.")

            if num_samples == 0:
                print("No data to analyze.")
                return

            # --- FFT Analysis ---
            fft_result = np.fft.fft(iq_signal)
            fft_freq = np.fft.fftfreq(num_samples, d=1 / F_SAMPLE)

            # Shift the FFT for plotting (0 Hz in the center)
            fft_result_shifted = np.fft.fftshift(fft_result)
            fft_freq_shifted = np.fft.fftshift(fft_freq)

            # Convert to Magnitude in dB
            # Adding a small epsilon to avoid log(0)
            fft_magnitude_db = 20 * np.log10(np.abs(fft_result_shifted) / num_samples + 1e-12)

            # --- Theoretical Calculations for Comparison ---
            amp_in_band = calculate_theoretical_amplitude(PT1, FC1, R1)
            amp_out_of_band = calculate_theoretical_amplitude(PT2, FC2, R2)

            # FERS scales output voltage, so we need to find the peak to compare relative power
            dc_component_fers = fft_result[0] / num_samples
            dc_magnitude_fers = np.abs(dc_component_fers)

            print("\n--- Analysis Results ---")
            print(f"Theoretical Amplitude (In-Band Tx):      {amp_in_band:.4e}")
            print(f"Theoretical Amplitude (Out-of-Band Tx):  {amp_out_of_band:.4e}")
            print(f"Measured DC Magnitude from FERS output:  {dc_magnitude_fers:.4e}")

            if dc_magnitude_fers > amp_in_band * 1.1:  # Allow 10% tolerance
                print(
                    "\n[CONCLUSION] The measured DC component is significantly larger than expected from the in-band signal alone.")
                print(
                    "This confirms that the out-of-band transmitter's energy has aliased to DC, as predicted by the bug report.")
            else:
                print("\n[CONCLUSION] The measured DC component is consistent with the in-band signal only.")
                print("This might indicate the bug is not present or the scenario is not triggering it as expected.")

            # --- Plotting ---
            plt.style.use('seaborn-v0_8-darkgrid')
            fig, ax = plt.subplots(figsize=(12, 7))

            ax.plot(fft_freq_shifted / 1e6, fft_magnitude_db)

            ax.set_title("FFT of FERS Receiver Output (Out-of-Band Interference Test)", fontsize=16)
            ax.set_xlabel("Frequency (MHz)", fontsize=12)
            ax.set_ylabel("Magnitude (dB)", fontsize=12)
            ax.grid(True, which='both', linestyle='--', linewidth=0.5)

            # Highlight the massive DC peak
            peak_db = np.max(fft_magnitude_db)
            ax.axvline(0, color='r', linestyle='--', label=f'Massive DC Peak at {peak_db:.1f} dB')
            ax.legend()

            plt.tight_layout()
            plt.show()
            # plt.savefig("fft_analysis_issue_90.png")

    except FileNotFoundError:
        print(f"Error: The file '{filename}' was not found.")
        print("Please run the FERS simulation first to generate the output file.")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")


if __name__ == "__main__":
    analyze_h5_file()

Results

Running the analysis script on the output of the minimal scenario produces the following console output:

$ python3 analysis.py 
Successfully opened 'Rx_results.h5'
Read 20000 complex samples.

--- Analysis Results ---
Theoretical Amplitude (In-Band Tx):      2.3857e-05
Theoretical Amplitude (Out-of-Band Tx):  3.4292e-04
Measured DC Magnitude from FERS output:  3.4659e-04

[CONCLUSION] The measured DC component is significantly larger than expected from the in-band signal alone.
This confirms that the out-of-band transmitter's energy has aliased to DC, as predicted by the bug report.

The graphical output (analysis_plot.png) clearly shows the predicted behavior:

The plot shows a single, massive peak at 0 Hz with a magnitude of approximately -69.2 dB. All other frequencies are at the numerical noise floor. This confirms that the energy from the strong 1.1 GHz out-of-band transmitter has been incorrectly aliased to DC and summed with the in-band signal, validating the bug report.