Python Antenna Modulation

Description

This feature allows defining an antenna's gain pattern using an external Python function, specified within the XML configuration. When the simulation requires the antenna gain for a specific direction, FERS calls the designated Python function. It passes the calculated azimuth and elevation angles to the function and expects a single floating-point number representing the linear power gain in return.

The interaction is managed by the C++ class python::PythonAntennaMod, specifically its getGain(const math::SVec3& direction) method, which handles the call to the Python interpreter and retrieves the result.

Assumptions

• Assumes the Python module specified in the XML configuration exists within the Python environment's path and contains a function with the specified name.
• Assumes the user-provided Python function adheres strictly to the expected signature: def function_name(azimuth: float, elevation: float) -> float:.
• Assumes the azimuth and elevation arguments passed by FERS (derived from the math::SVec3 direction vector, likely in radians) are in the units expected by the Python function.
• Assumes the single numeric value returned by the Python function represents the linear power gain (i.e., a ratio, not in dB or dBi) as expected by the FERS simulation core for use in power calculations.
• Assumes the embedded Python interpreter is correctly initialized and managed (see Python Interpreter Management).

Limitations

• Frequency Independence: The Python function interface only provides azimuth and elevation angles. The simulation frequency or wavelength is not passed as an argument. This means modeling frequency-dependent antenna patterns directly within the Python function is difficult unless the frequency is hardcoded or accessed through external means, limiting the dynamic nature of the pattern.
• Performance Overhead: Each gain calculation requires a call from C++ into the Python interpreter, involving data type conversions, function lookup, execution within Python, and potential contention for Python's Global Interpreter Lock (GIL). This can introduce significant performance overhead compared to native C++ antenna models, particularly in simulations requiring frequent gain lookups (e.g., many targets, dense multipath, high update rates).
• Limited Data Interface: Only the directional components (azimuth, elevation) relative to the antenna's boresight are passed to the Python function. No other contextual simulation state (e.g., current simulation time, platform's absolute orientation) is directly available to the function via its arguments.
• Error Handling Genericity: If the Python script fails (e.g., module not found, function signature mismatch, runtime error within the Python code, incorrect return type), FERS typically throws a generic std::runtime_error. Diagnosing the specific Python-level error may require inspecting stderr output or adding explicit error handling within the Python script itself.

Related Components

• C++ Interface Class: python::PythonAntennaMod (defined in python_extension.h/.cpp)
• Configuration: Defined in XML via <antenna> element with pattern="python" attribute, along with child elements <module> and <function> specifying the Python target. (See XML Parsing)
• Dependency: Relies on the setup described in Python Interpreter Management.
• Caller: Used by Antenna objects during simulation steps requiring gain calculation (e.g., Core Simulation Physics).

Validation Status

• Needs Verification: Functionality depends heavily on external, user-provided Python code and correct environment setup. Requires validation specific to the implemented Python function.
• Key Areas for Validation:
  • Verification of angle units (radians vs. degrees) between C++ (SVec3 interpretation) and the Python function's expectation.
  • Confirmation that the returned gain value is correctly interpreted (linear scale).
  • Behavior at edge-case angles (e.g., poles at +/- pi/2 elevation, azimuth wrap-around at +/- pi).
  • Robustness and clarity of error reporting when the Python module/function is invalid or fails during execution.
  • Measurable performance impact in relevant scenarios compared to native models.
  • Compatibility and consistency across the supported range of Python versions (3.7-3.11.12).
• Priority: Medium (Potentially High if Python-based antenna modeling is a critical requirement for planned simulations or research goals).