Cannot use antenna pattern defined outside`antenna_pattern.py`

[mlouielu]

The built-in create_factory for register_antenna_pattern() use globals() for the v_pattern:

def create_factory(name: str) -> Callable[[str, str], PolarizedAntennaPattern]:
    r"""Create a factory method for the instantiation of polarized antenna
    patterns

    Note that there must be a vertical antenna pattern function with name
    "v_{s}_pattern" which is used.

    :param name: Name under which to register the factory method
    :returns: Callable creating an instance of PolarizedAntennaPattern
    """
    def f(*, polarization, polarization_model="tr38901_2"):
        return PolarizedAntennaPattern(
                                v_pattern=globals()["v_" + name + "_pattern"],
                                polarization=polarization,
                                polarization_model=polarization_model)
    return f

Which will not work if the user register their own custom antenna pattern:

import sionna.rt
import mitsuba as mi

from sionna.rt.antenna_pattern import register_antenna_pattern, create_factory
from sionna.rt.antenna_array import PlanarArray


def v_poc_pattern(theta, phi):
    return mi.Complex2f(10, 0.0)


register_antenna_pattern("poc", create_factory("poc"))

array = PlanarArray(num_rows=1, num_cols=1, pattern="poc", polarization="V")

Output:

Traceback (most recent call last):
  File "/poc2.py", line 14, in <module>
    array = PlanarArray(num_rows=1, num_cols=1, pattern="poc", polarization="V")
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/sionna-rt/src/sionna/rt/antenna_array.py", line 200, in __init__
    antenna_pattern = antenna_pattern_registry.get(pattern)(**kwargs)
                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/sionna-rt/src/sionna/rt/antenna_pattern.py", line 599, in f
    v_pattern=globals()["v_" + name + "_pattern"],
              ~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^
KeyError: 'v_poc_pattern'

Although user can define their own callback to do the same thing:

import sionna.rt
import mitsuba as mi

from sionna.rt.antenna_pattern import (
    register_antenna_pattern,
    create_factory,
    PolarizedAntennaPattern,
)
from sionna.rt.antenna_array import PlanarArray


def v_poc_pattern(theta, phi):
    return mi.Complex2f(10, 0.0)


def f(*, polarization, polarization_model="tr38901_2"):
    return PolarizedAntennaPattern(
        v_pattern=v_poc_pattern,
        polarization=polarization,
        polarization_model=polarization_model,
    )


register_antenna_pattern("poc", f)

array = PlanarArray(num_rows=1, num_cols=1, pattern="poc", polarization="V")

I think it will still be better if user can use the same API interface -- or at least to document this in the tutorial.

[alonekite]

Hi @mlouielu,

I looked into this issue. The current Custom Antenna Patterns developer guide documents the recommended approach for patterns defined outside antenna_pattern.py: define a custom factory callback and pass the external pattern function directly to PolarizedAntennaPattern, rather than using create_factory(name).

The limitation described here still exists: create_factory(name) looks up v_<name>_pattern in the globals of antenna_pattern.py, so it is suitable for built-in patterns but not for pattern functions defined in a user module.

I also noticed that the Introduction tutorial linked the antenna-pattern text to the Radio Materials guide instead of the Custom Antenna Patterns guide. I opened PR #PR_NUMBER to correct that link and make the existing custom-pattern documentation easier to discover.

The PR addresses the documentation and discoverability aspect only; it does not change the behavior of create_factory(). The maintainers can decide whether the current documented factory approach is sufficient or whether this issue should remain open as a possible API enhancement.

[njroussel]

Hi,

Indeed, the intended API usage for handling custom antenna patterns is described here: https://nvlabs.github.io/sionna/rt/developer/dev_custom_antenna_patterns.html.

The create_factory method is, as far as I can tell, not meant to be used publicly. You should provide your own factory methods as you've done in the last snippet of code.