Python Function Antenna Pattern

Description

Allows defining an antenna's gain pattern using an external, user-provided Python function. This provides maximum flexibility for implementing complex or custom antenna models that are not covered by the built-in types.

It is configured within the antenna definition in the FERS XML scenario file using pattern="python". Additional parameters specify the Python module file (<module>) and the specific function name within that module (<function>) that calculates the gain. During simulation, FERS calls this Python function, passing the calculated azimuth and elevation angles, and uses the returned value as the antenna gain for that direction.

Assumptions

• A compatible Python environment (version 3.7-3.11.12) is properly set up and accessible to FERS (see Python Interpreter Management).
• The Python module file specified by the <module> parameter exists, is accessible, and can be imported by the embedded interpreter.
• The specified Python module contains a function with the exact name specified by the <function> parameter.
• The Python function's signature precisely matches: func(azimuth_radians: float, elevation_radians: float) -> gain: float.
• The azimuth and elevation angles passed by FERS are correctly interpreted by the Python function (units are expected to be radians).
• The gain value returned by the Python function is a linear power ratio (not dB) suitable for use in the radar equation calculations.
• The internal C++ wrapper class (python::PythonAntennaMod) correctly interfaces with the embedded Python interpreter, passing arguments and retrieving the return value.
• The Python function executes efficiently enough not to become a significant simulation bottleneck, especially if called frequently.

Limitations

• External Dependency: The entire pattern calculation logic resides in user-provided Python code. FERS only provides the Az/El inputs and consumes the gain output. Correctness is entirely dependent on the user's Python implementation.
• Strict Signature: The Python function must adhere to the specific two-argument signature (azimuth_radians, elevation_radians) and return a single numeric gain value. Deviations will cause runtime errors.
• Frequency Agnostic: FERS passes only the directional angles (Az/El) to the Python function. The function cannot directly account for the operating frequency/wavelength unless the frequency is hardcoded within the Python script or accessed via less robust methods like global state.
• Performance Overhead: Calling into the Python interpreter for each gain lookup incurs performance overhead compared to native C++ antenna models. This can significantly impact simulation speed, particularly in scenarios with many targets, multipath interactions, or high sampling rates requiring frequent gain lookups.
• Error Handling: Errors within the Python function (e.g., syntax errors, calculation errors, incorrect return types) will typically raise Python exceptions. FERS catches these and converts them into C++ exceptions (usually std::runtime_error), which may halt the simulation. Debugging requires understanding both the C++ context and the Python traceback.
• Flexibility vs. Risk: While offering high flexibility, this approach introduces complexity (managing Python environment, code dependencies) and runtime risks (performance degradation, hard-to-debug Python errors).
• Angle Calculation Method: The specific azimuth and elevation angles passed to Python are derived from the vector difference between the look direction vector and the antenna's reference pointing direction vector (angle - refangle).

Related Components

• C++ Classes:
  • antenna_factory::PythonAntenna: The C++ antenna model implementation that uses this mechanism.
  • python::PythonAntennaMod: The C++ class responsible for managing the interaction with the Python function (loading, calling, data conversion).
• Dependencies: Python Interpreter Management (Handles overall Python environment setup and initialization).

Validation Status

• Needs Verification:
  • Correctness of passing Az/El angles (units, coordinate system representation) between C++ and Python.
  • Correct interpretation and application of the gain value returned from Python within FERS's calculations.
  • Robustness of error handling when the Python script is missing, contains errors, or returns unexpected data types/values.
  • Actual performance impact in various simulation scenarios compared to native C++ models.
• Key Areas for Validation:
  • Develop unit tests for python::PythonAntennaMod focusing specifically on the C++/Python data marshalling (passing floats, receiving float/double).
  • Create integration tests using simple Python antenna scripts with known, easily verifiable outputs (e.g., constant gain=1.0, gain = cos(elevation), etc.) to confirm the end-to-end data flow and that the applied gain is correct.
  • Implement tests that intentionally trigger Python errors (e.g., incorrect function signature, exceptions within the Python code, non-numeric return value) to ensure FERS handles these failures gracefully (e.g., logs informative errors, throws appropriate C++ exceptions).
  • Conduct performance benchmark tests comparing simulations using Python antennas versus equivalent (if possible) native C++ antennas under identical, demanding scenarios (e.g., many targets).
• Priority: Medium (High flexibility makes it important to validate the interface, but it might be used less often than core models. Performance validation is key if intended for complex scenarios.)