XML File Antenna Pattern

Description

Allows loading antenna gain patterns (both azimuth and elevation components) from a custom XML file format. This antenna type is selected in the main simulation configuration XML by setting the pattern attribute to "xml" within the <antenna> definition and providing the path to the pattern file via the filename parameter.

Assumptions

• Assumes the specified XML pattern file exists, is readable, and conforms to the specific format expected by the loadAntennaGainAxis function (containing separate <azimuth> and <elevation> sections, each with <gainsample> elements containing <angle> and <gain>).
• Assumes azimuth and elevation components of the gain pattern are separable, allowing the total gain to be calculated as the product (azi_gain * elev_gain) of the individually looked-up azimuth and elevation gain values.
• Assumes the 1D linear interpolation performed by the interp::InterpSet class between the sampled gain points defined in the XML file is sufficiently accurate for the specific antenna pattern.
• Assumes that looking up gain based on the absolute value of the angle (abs(angle)) relative to the boresight is the correct and intended behavior for interpreting the pattern data provided in the file.
• Assumes the internal normalization logic applied after loading (potentially involving division by the maximum absolute gain value found) is appropriate and yields the intended final gain scaling.
• Assumes that the gain values provided in the XML file are independent of the radar signal's wavelength (frequency), as wavelength is explicitly ignored during the gain lookup process for this antenna type.

Limitations

• Format Rigidity: The simulator is strictly tied to the specific custom XML format expected by the internal parsing function (loadAntennaGainAxis). It cannot parse other common or standard antenna pattern data formats.
• Separability Requirement: The model inherently assumes the azimuth and elevation patterns are mathematically separable and combines them via multiplication. This might not accurately represent complex, non-separable 3D antenna patterns where gain depends on azimuth and elevation simultaneously in a more complex way.
• Linear Interpolation: Gain values between the sampled points defined in the XML are determined by simple linear interpolation (interp::InterpSet). The accuracy of the resulting pattern representation depends heavily on the density and strategic placement of the <gainsample> points in the XML file. Sparse sampling can lead to significant errors.
• Absolute Angle Lookup: The use of the absolute angle (abs(angle)) for looking up gain values prevents the correct representation of antenna patterns that are asymmetric around the zero-degree axis (boresight) in either azimuth or elevation.
• Normalization Effect: The internal normalization logic (potentially based on max(abs(value))) might obscure the absolute gain values intended by the user if they expect the numbers in the XML file to be used directly without further scaling based on the maximum value found.
• Wavelength Independence: The gain lookup mechanism completely ignores the signal's wavelength. Any frequency-dependent behavior of the antenna must be handled externally by providing different pattern files for simulations run at different frequencies.
• Lookup Failure: If the calculated look angle falls outside the range defined by the <angle> samples in the XML file for either azimuth or elevation, the gain lookup fails, and the simulation terminates with a fatal error.
• Angle Calculation Method: This model uses the vector difference between the look direction vector and the antenna's reference boresight vector to determine the azimuth/elevation components for lookup. This differs from the scalar angle calculation (Antenna::getAngle) used by some other simpler antenna models (e.g., Sinc, Parabolic Dish), which might lead to slightly different interpretations of the angle depending on geometry.

Related Components

• XML Parsing Entry: xml_parser.cpp :: parseAntenna
• Class Definition: antenna_factory.h :: XmlAntenna
• Loading Logic: antenna_factory.cpp :: XmlAntenna::loadAntennaDescription
• XML Parsing Logic: antenna_factory.cpp :: loadAntennaGainAxis
• Gain Calculation: antenna_factory.cpp :: XmlAntenna::getGain
• Core Dependency: interp::InterpSet class (provides 1D linear interpolation using std::map), defined in interpolation_set.h and interpolation_set.cpp.

Validation Status

• Needs Verification: The correctness of the implemented gain calculation needs thorough verification against known patterns, specifically testing the impact of the separability, absolute angle lookup, linear interpolation, and normalization assumptions.
• Key Areas for Validation:
  • Verify the exact XML structure required by loadAntennaGainAxis against documentation or code comments.
  • Test with known, simple patterns (e.g., constant gain, linear slope) loaded via XML to confirm the linear interpolation behavior matches expectations.
  • Validate the final gain calculation result, particularly ensuring the azi_gain * elev_gain combination is correctly implemented.
  • Test behavior with intentionally asymmetric pattern data loaded via XML to demonstrate and quantify the effect of the abs(angle) lookup limitation.
  • Investigate the normalization logic applied after loading to understand how it scales the gain values provided in the file.
  • Confirm the behavior and error message when an angle lookup falls outside the defined range in the XML file.
  • Compare gain results against other antenna models (where overlap exists, e.g., a simple pattern representable multiple ways) for consistency checks.
• Priority: High (This model has several non-trivial assumptions and limitations related to format, interpolation, and angle handling that directly affect the core antenna gain calculation, a fundamental part of the radar simulation).