Generic File Antenna Pattern

Description

This antenna model allows loading an antenna gain pattern from an external file containing a 2D grid of gain values. The simulation uses the Pattern class to handle loading (via serial::readPattern) and provides gain values for specific directions using bilinear interpolation on the loaded grid data.

This pattern is configured in the simulation XML using pattern="file" within the <antenna> definition, along with a filename parameter specifying the path to the grid data file.

<antenna name="MyGridAntenna" type="monostatic">
    <pattern type="file" filename="path/to/my_pattern.bin"/> <!-- Example -->
    <!-- Other antenna parameters -->
</antenna>

Assumptions

• Assumes the loaded data file contains a 2D grid representing antenna gain over Azimuth spanning [-π, +π] and Elevation spanning [-π, +π].
• Assumes bilinear interpolation between the grid points is an appropriate and sufficiently accurate method for determining gain at intermediate angles.
• Assumes the internal grid indexing logic and wrap-around handling (especially for azimuth) within the Pattern class are correct.
• Assumes the gain values stored in the file are absolute linear power gain values (not dB) and that frequency/wavelength dependence is already baked into these values, as wavelength is ignored during the lookup process itself.

Limitations

• Interpolation Quality: The accuracy of the antenna gain lookup heavily depends on the density and quality of the provided grid data, as bilinear interpolation is used between points. Sparse grids may lead to inaccurate gain representation.
• Coverage Requirement: The implementation implicitly assumes the grid data file covers the full Azimuth [-π, +π] and Elevation [-π, +π] ranges. Behavior with files covering smaller angular regions is undefined and needs verification.
• Frequency Independence: The model ignores the simulation's wavelength (lambda) during gain lookup. It cannot inherently model frequency-dependent antenna patterns unless multiple separate simulations are run with different pattern files corresponding to different frequencies.
• Elevation Wrap-Around: The handling of elevation angles near the poles or potential wrap-around logic might be non-physical or behave unexpectedly depending on the specific implementation within Pattern::getGain.
• Angle Calculation: Uses the vector difference between the look direction and the antenna's reference boresight vector (angle - refangle) to determine the azimuth/elevation components for lookup within the grid.

Related Components

• XML Parsing: xml_parser.cpp::parseAntenna
• Antenna Class: antenna_factory.h::FileAntenna (inherits from Antenna)
• Gain Logic: antenna_factory.h::FileAntenna::getGain
• Pattern Handling: antenna_pattern.h::Pattern class
• Grid Loading/Interpolation: antenna_pattern.cpp::Pattern::getGain, serial::readPattern
• Relevant Wiki Pages: Antenna Models, XML Parsing

Validation Status

• Needs Verification: The correctness of gain values retrieved using this model requires explicit validation against known data or reference patterns.
• Key Areas for Validation:
  • Accuracy of the bilinear interpolation implementation.
  • Correctness of grid indexing and wrap-around logic, particularly for azimuth and near elevation limits.
  • Behavior when the input file grid does not cover the full [-π, +π] Az/El range.
  • Verification that the angle calculation (vector difference) correctly maps to the grid coordinates expected by Pattern::getGain.
  • Confirmation of the expected units and format for the external grid data file loaded by serial::readPattern.
• Priority: Medium (Core functional component relying on external data and specific interpolation logic)